Deploying with Docker Compose
How to run my on one machine with Docker Compose: the smallest setup, one server process on SQLite with media files
in a named volume. PostgreSQL, object storage, and TLS are files to layer on top later
(Docker Compose files).
You need Docker and Docker Compose v2.
Start the server
Section titled “Start the server”The Compose files are in deploy/docker of the source. Take them from the tag of
the release you run, so that they match its image:
git clone --depth 1 --branch v0.1.0 https://github.com/mycroblog/my.gitcd my/deploy/dockercp example.env .env# Set MY_VERSION in .env to the same version, such as 0.1.0mkdir -m 700 secrets(umask 022; openssl rand -base64 32 > secrets/kek) # the key encryption key: back it up apart from the databasedocker compose up -d- Compose pulls the image
ghcr.io/mycroblog/myofMY_VERSION. There is nolatesttag, so the version has to be named: a release can need steps that a silent update would skip (the image’s tags). To build the image from the checkout instead, add the override:docker compose -f compose.yaml -f compose.build.yaml up -d --build. - The
schemaservice runsmy schema applyof the server image, which brings the database in a named volume to the schema of that release, and exits; the server (role=all) starts once it has succeeded. The schema is applied again on everyup, so after an upgrade you start the server the same way. - The server listens on
127.0.0.1:8080(the port isMY_HTTP_PORTin.env). It is ready whencurl localhost:8080/readyzreturns{"status":"ok"}. - The key encryption key (KEK) reaches the server from
secrets/kekas the Docker secret/run/secrets/my_kek, never as an environment variable (managing the key encryption key). - Every other setting of the configuration reference is set in
.env, whose template describes them.
Create an administrator
Section titled “Create an administrator”Create an administrator, then look the account up with WebFinger and fetch its actor. The password is read from the first line of standard input.
docker compose exec -T my my admin create -username alice -email alice@example.com < password.txtcurl 'http://localhost:8080/.well-known/webfinger?resource=acct:alice@localhost:8080'curl -H 'Accept: application/activity+json' http://localhost:8080/ap/actors/<the UUID of the self link from WebFinger>Sign in from a browser
Section titled “Sign in from a browser”With the pair MY_HOST=localhost:8080 and MY_WEB_ORIGIN=http://localhost:8080 of example.env, sign-in, the
client API, and media work over plain HTTP at http://localhost:8080 (ActivityPub ids stay
https://localhost:8080/...). If you change MY_HTTP_PORT, change the port of MY_HOST and MY_WEB_ORIGIN to match.
- Open
http://localhost:8080/loginin a browser (or press Sign in in the web client’s top bar); it opens the server’s sign-in screen. - On the sign-in screen, enter the email address and password of the administrator you created above.
- You are back in the web client, on your home timeline.
- The sign-in cookie is
Secure. Chrome and Firefox accept it onhttp://localhost; Safari (WebKit) does not, so use Chrome or Firefox locally. - Links of hashtags and mentions in post bodies use
https://, since they are the federated URLs.
Going public
Section titled “Going public”- Set
MY_HOSTin.envto your real domain, removeMY_WEB_ORIGIN(it defaults tohttps://{MY_HOST}), and terminate TLS in front of the server: the layercompose.caddy.yamlruns Caddy for that (Docker Compose files), or let the server serve HTTPS itself (serving HTTPS from the server).MY_HOSTis stored in the database on first start and cannot be changed later. - Behind a reverse proxy of your own, set
MY_TRUSTED_PROXIESin.envso that rate limits such as the one on sign-in apply per client IP rather than to the proxy (trusted_proxies). - Before opening the server to users, go through the production checklist.
docker compose downstops the stack.down -valso deletes the data volumes.
For every setting see the configuration reference; for day-to-day operation see running the server.
For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt