Administrator's guide

Running CodeRealm for others

The site is one Linux machine. The work happens on hosts — people's own computers running CodeRealmRunner — and the server runs nothing of any project's. This is what the machine needs, how a release reaches it, and how it is backed up and restored. The user guide is the other half.

This is for the person who hosts the shared version for others. The site is one Linux machine; the work happens on hosts — people's own computers running CodeRealmRunner — and the server runs nothing of any project's.

One command on a fresh machine

On a Debian or Ubuntu server whose DNS name already points at it, as root:

curl -fsSL https://gitlab.com/olegrumyancev/coderealm/-/raw/main/ops/install-vps.sh | bash -s -- your.domain.example

It installs Docker, clones the repository to /opt/coderealm, writes .env with the domain and a generated database password, and starts the stack. A few minutes later the site answers at https://your.domain.example with a certificate from Let's Encrypt, and the first person to register becomes the GM. Any 4 GB machine is enough: the server holds the database and the repositories, and builds nothing.

What it is made of

compose.yml — four containers: PostgreSQL 17, the API, the web front, and Caddy in front of both with TLS. The API's own routes (/api, /git, /run) go straight to the API; everything else is the interface.
Two volumes hold everything the site keeps: db (the database) and data (bare repositories, chats, live-run checkouts, runner downloads, the secrets file). Back those two up and you have it all.
The schema moves by Alembic migrations, applied when the API starts. A change to the schema is a file in backend/migrations/versions; nothing is altered by hand.
The API image carries EB_SERVER_HOST=0: the server is a site and never a host, whatever is installed on it. Every run happens on a host of the person who owns the project.

Environment variables the API reads

Variable	Meaning
`EB_DATABASE_URL`	Database address. compose.yml sets it from EB_DB_PASSWORD in .env.
`EB_DATA_DIR`	Root for repositories, chats, runs and the secrets file. /data in the container, the data volume.
`EB_PUBLIC_ORIGIN`	The address of the site as users reach it, printed in account e-mails. compose.yml sets it from EB_DOMAIN.
`EB_TRUSTED_PROXIES`	Addresses or CIDR ranges whose forwarded headers name the real client. The image trusts loopback and the container network; behind Cloudflare, add its ranges.
`EB_COMMIT`	The commit the image was built from, shown by /api/health. The deploy job sets it.
`EB_ANALYZE_MODEL, EB_ANALYZE_CONFIRM_MODEL, EB_CONVERGE_MODEL, EB_GOLDEN_MODEL`	The models for the specification analysis (and its confirmation), convergence and the Golden User.
`EB_NO_WORKERS`	1 = serve the interface only, run nothing. For demonstrations and screenshots.
`EB_SOLO`	1 = the single-user mode CodeRealmApp uses. Not for a shared server.
`EB_SERVER_HOST`	0 = this server serves the site and runs nothing. 1 (the developer's own machine) makes it a host too, if claude is installed and signed in.

Day to day

Deploying. A merge into main on GitLab is a release: the pipeline tests, builds, then the deploy job connects to the server over SSH, pulls, rebuilds the containers and refuses to report success until the running API answers with the commit it deployed. It needs three CI variables — DEPLOY_HOST, DEPLOY_USER, DEPLOY_KEY — and does nothing until they exist. By hand it is git pull && docker compose up -d --build in /opt/coderealm.
Backups. ops/backup-linux.sh from cron: a database dump and a tarball of the data volume, fourteen kept, and a copy off-site through rclone when EB_BACKUP_RCLONE_DEST names a remote. Restoring: pg_restore into the db container, untar into the data volume, start.
Runner downloads. The pipeline builds and publishes the runner for Linux and Windows; ops/fetch-runner.sh <version> puts the published builds where the site serves them, checking each against its recorded checksum. The macOS build is still made on a Mac.
Registration. The first person to register becomes the GM. Then turn on Disable registration and hand accounts out from Users if the site is not meant to be open.
What went wrong. The notices badge in the header is the server's voice: a host that stopped answering, a runner that refused an update, a background run that failed. Nothing fails in silence; look there before looking in a log.
On a developer's own Mac the platform still runs without containers: two LaunchAgents, dev.coderealm-api and dev.coderealm-web, a Homebrew PostgreSQL, and ops/deploy.sh. That is the development setup, not the way to host it for others.

Before the site takes traffic

Two-factor sign-in on the provider, the DNS provider and GitLab. Registration closed after the first GM. The off-site backup destination named in EB_BACKUP_RCLONE_DEST, with credentials that can write and list but never delete. The full list, in the order the risks come, is docs/security-plan.md in the repository.