4.9 KiB
lodge
sync for files not meant to be in git
Runs in Docker, locally the same way as in production. Each part in backend/, frontend/ brings its own docker-compose.yml, included from the root one. COMPOSE_PROFILES in .env selects the services that run on this machine. docker-compose.override.yml in each part holds what differs between machines: published ports and the aliases on the external caddy network.
make env
make recreate
make env creates .env from the examples of every part and copies each docker-compose.override.yml.example. make recreate starts the selected profiles, make rebuild builds the images first, make logs, make restart and make down do what they say.
To deploy, git pull && make deploy. It runs make pre-deploy in every part, which builds images only when their inputs changed and applies migrations, then docker compose up -d, then make post-deploy, which restarts the services whose mounted code changed. A deploy system with its own up step calls the two hooks around it. What was built and started is remembered as refs/deploy/* in the clone.
make fmt, make check and make build run in every part. Part-specific targets live in the part's own Makefile: make -C backend ....
How it works
backend/ is one Go module with two binaries. lodge-server stores everything in a single SQLite file under backend/storage/, serves the API, the built frontend from frontend/build and the client binaries it was built together with, so a client always matches its server. lodge is the client: a CLI and a daemon in one.
A repository is identified by the hash of its root commit, so nothing is registered by hand. Files are content-addressed blobs; history is a log of revisions, each carrying the branch and the commit of the main repository at that moment. Every repository has a shared space and one space per branch. Which path goes where is set in .lodge at the repository root, which is synced like any other file:
shared docs/agents
shared CLAUDE.local.md
branch .agent
ignore vault/.obsidian/workspace*.json
ignore .DS_Store
ignore keeps matching files on the machine that has them: they are never pushed, pulled or watched. Its pattern is a glob over the whole path, or over any single name when it has no slash. Synced paths are hidden through .git/info/exclude; .gitignore is never touched, and files tracked by git are never synced. When two machines edit the same file, the later edit wins and the other version stays in history.
Adding a machine
Set ADMIN_TOKEN in .env, sign in to the admin with it, open Machines and press "Connect a machine". The same one-time install command, valid for ten minutes, is available without a browser:
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" https://lodge.example.com/api/codes
Running the returned curl ... | sh on a Mac or a Linux machine downloads the client, logs it in, starts the daemon under launchd or systemd, installs a post-checkout hook through init.templateDir so that fresh clones receive their files, and drops a skill for coding agents into ~/.claude/skills and ~/.agents/skills. Repositories cloned before that are picked up with lodge add. Where no daemon can run, set LODGE_URL and LODGE_TOKEN and call lodge sync.
make -C backend dev runs the server without Docker, make -C backend client builds the client into backend/bin.
Several servers
A repository can live on another lodge server than the rest of the machine, for example a team's server during an event, while everything else stays on the personal one. Inside the repository, lodge remote <url> <code> claims a code from that server and binds the repository to it; further repositories on the same server need only lodge remote <url>. Outside a repository the same command only stores the server's token. The binding belongs to the repository key, so worktrees and later clones follow it, and the daemon listens to every server it holds a token for. lodge remote prints the server of the current repository, lodge remote --default sends it back to the default one. lodge login and lodge update only touch the default server, and a machine with no default server at all syncs just the repositories bound with lodge remote.
The admin
The server serves the admin from frontend/build. History is drawn as a borehole log: every revision is a bed, newest on top, hatched by the machine that wrote it and labelled with the branch and commit of the main repository. Dragging along the column, or the arrow keys, shows the notes as they were at that revision, and every depth, file and view is a link. A file can be compared with its previous version and put back on the surface; a repository can be deleted with its history, which leaves the files on the machines alone. Machines are listed with their hatch and can be revoked.
make -C frontend dev runs the admin against a server on localhost:8080.