Quickstart

You need Docker with Compose and git. Everything else runs in containers.

1. 1

   Start the store and the server

   This starts rustfs, a local S3-compatible store, and one gitcask process on port 8080 using gitcask.standalone.toml.

   docker compose up --build --wait

2. 2

   Mint a token

   A demo JWT signed with a throwaway key, allowed to administer local/demo for one hour.

   TOKEN=$(docker compose run --rm token --config /etc/gitcask/gitcask.standalone.toml token mint \
     --key /run/secrets/gitcask-private.pem --principal local-demo --scope local/demo:admin --ttl 1h)

3. 3

   Create the repository

   Creating a repository is one PUT. gitcask keeps no repository list; your platform does.

   curl -fsS -X PUT -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/local/demo

4. 4

   Clone and push

   Git sends the token as the Basic-auth password. The username is ignored.

   git clone "http://ignored:$TOKEN@127.0.0.1:8080/local/demo.git"
   cd demo && git commit --allow-empty -m first && git push -u origin HEAD:main

gitcask indexed your pack, uploaded it with its index and a log entry, then made it visible with one compare-and-swap of the repository manifest. Only then did git report the new branch.

Stop the server, delete its cache directory and start it again: the repository clones exactly as before, because the bucket is the repository. Architecture walks through every object it wrote.

• Your platform signs tokens with its own Ed25519 key; gitcask holds only the public key or a JWKS URL. Opaque tokens work through introspection instead. See Authentication.
• Point [store] at your S3 bucket and run the published image. See Operations.