Docker Compose quickstart

Get the source#

Clone the Desyn repository (or unpack a release archive) and enter it. Every command in the self-hosting guides runs from the repository root.

git clone <repository-url> desyn
cd desyn

Point Compose at the stack#

export COMPOSE_FILE=deploy/compose/desyn.selfhost.yml

With COMPOSE_FILE set, a plain docker compose … uses the self-hosting stack; the commands in these docs assume it. Add the line to your shell profile, or pass -f deploy/compose/desyn.selfhost.yml to every command instead. Compose reads its variables from deploy/compose/.env, next to the stack file.

Create the stack environment#

Copy the template and fill its four required secrets with fresh random values:

cp deploy/compose/.env.example deploy/compose/.env
chmod 600 deploy/compose/.env
for name in POSTGRES_PASSWORD INSTANCE_SECRET MINIO_ROOT_PASSWORD RENDER_WORKER_SECRET; do
  sed -i "s|^$name=.*|$name=$(openssl rand -hex 32)|" deploy/compose/.env
done

deploy/compose/.env and deploy/compose/convex.env are ignored by git. Keep both with your backups: INSTANCE_SECRET protects the Convex deployment, and the others are needed to reach your data.

Create the backend configuration#

The server functions read their own configuration from the Convex deployment. Start from the template and fill its secrets, reusing two values from the stack environment:

cp deploy/compose/convex.selfhost.env.example deploy/compose/convex.env
chmod 600 deploy/compose/convex.env
stack() { grep "^$1=" deploy/compose/.env | cut -d= -f2-; }
put() { sed -i "s|^$1=.*|$1=$2|" deploy/compose/convex.env; }
put BETTER_AUTH_SECRET "$(openssl rand -hex 32)"
put AI_KEY_ENCRYPTION_SECRET "$(openssl rand -hex 32)"
put RENDER_WORKER_SECRET "$(stack RENDER_WORKER_SECRET)"
put AWS_SECRET_ACCESS_KEY "$(stack MINIO_ROOT_PASSWORD)"

The template already selects the self-hosted edition (DESYN_EDITION=selfhost), the bundled worker and MinIO, and the log mail transport. Optionally add OPENROUTER_API_KEY and FAL_AI_API_KEY for AI features, and stock photo keys. The configuration reference explains every variable.

Choose your URLs#

The browser talks to three origins (app, Convex API, Convex HTTP actions) plus the storage endpoint. The public ones are baked into the web image when it is built, so set them before the first build.

DESYN_APP_URL=https://design.example.org
DESYN_SITE_URL=https://design.example.org
DESYN_CONVEX_URL=https://convex.example.org
DESYN_CONVEX_SITE_URL=https://convex-site.example.org

APP_URL=https://design.example.org
SITE_URL=https://design.example.org
S3_ENDPOINT=https://s3.example.org
S3_PUBLIC_BASE_URL=https://s3.example.org/desyn

DESYN_BIND=0.0.0.0

S3_ENDPOINT=http://192.168.1.20:9000
S3_PUBLIC_BASE_URL=http://192.168.1.20:9000/desyn

Build and start#

docker compose up -d --build
docker compose ps

The first build compiles the web app and the Rust worker and can take 15–30 minutes (DESYN_BUILD_JOBS in .env sets the parallel Rust jobs). When it finishes, docker compose ps shows every service running and convex-backend and postgres healthy; minio-init exits after creating the bucket.

Generate the admin key#

docker compose exec convex-backend ./generate_admin_key.sh

Copy the key from the last line of the output into CONVEX_SELF_HOSTED_ADMIN_KEY in deploy/compose/.env; the convex-tools service reads it from there. Treat it like a root password: it grants full control over the deployment. You also use it to log in to the dashboard.

Push the backend configuration#

grep -E '^[A-Z0-9_]+=.+' deploy/compose/convex.env | docker compose run --rm -T convex-tools env set --force

The first run builds the convex-tools image (a few minutes). The grep passes only variables that have a value, so empty optional keys are not set. Run the same command whenever you change convex.env; changes apply to new function calls immediately.

Deploy the functions#

docker compose run --rm convex-tools deploy --yes

This type-checks and uploads the schema, functions and scheduled jobs from the image's copy of convex/. Run it again after every upgrade.

Create your account#

Open your app URL and sign up. The first account on a fresh installation becomes the administrator and can open the admin console at /admin.

With the default MAIL_TRANSPORT=log, the verification email is not sent but written to the backend logs: open the dashboard at http://127.0.0.1:6791 (log in with the admin key) and look under Logs. Configure email before you invite anyone.