Docker Compose
This page helps you run Goiabada in production from the Docker Compose files the setup wizard writes.
The Compose files run the auth server, the admin console and the database on one host, and publish the two servers on 127.0.0.1 alone. A proxy on the same host puts them on the internet: Cloudflare Tunnel, Cloudflare + Nginx or Reverse proxy. Each of those pages runs this one first.
Run the wizard’s files
Section titled “Run the wizard’s files”-
Run the setup wizard in an empty directory, and choose Production with reverse proxy. Give it the two public URLs, such as
https://auth.example.comandhttps://admin.example.com, and a database. Or answer with flags:Terminal window ./goiabada-setup-linux-amd64 --type=production --db=postgres \--auth-url=https://auth.example.com --admin-url=https://admin.example.comIt writes
docker-compose.yml, which you can commit, anddocker-compose.override.ymlbeside it, which holds every secret. Never commit the override. -
Back up the AES key from the override before anything else: see Back up the AES key.
-
Start Goiabada with the command the wizard printed. With both files in the current directory, under their own names, it’s:
Terminal window docker compose up -dDocker Compose reads the override without being asked. The first start seeds the database, which can take a minute.
-
Check both servers answer on the host:
Terminal window curl http://127.0.0.1:9090/health # healthycurl http://127.0.0.1:9091/health # healthy -
Put a proxy in front, with one of the three pages above, and then sign in.
What the files run
Section titled “What the files run”- The database runs beside Goiabada, in a container of its own for MySQL, PostgreSQL and SQL Server, with its data in a named volume. With SQLite, the auth server keeps the database file in the
sqlite-datavolume. Database covers using a database server of your own instead. - The auth server starts once the database answers, and the admin console once the auth server’s health check,
/app/goiabada-authserver healthcheck, passes. A first start or an upgrade has up to five minutes to seed or migrate the database before Docker Compose counts the auth server unhealthy. - Both servers publish their ports on
127.0.0.1alone, 9090 for the auth server and 9091 for the admin console. Nothing outside the host reaches them, so your proxy is the only way in. - Both servers trust one proxy hop to tell them the client’s IP address: see Client IP and proxy trust.
- Each server gets up to 60 seconds to stop when you run
docker compose downorrestart, so requests in flight finish. - The wizard’s rate limiter answer, yes unless you said no, is written as
GOIABADA_AUTHSERVER_RATELIMITER_ENABLED. See Rate limits.
The hop to the auth server
Section titled “The hop to the auth server”The admin console calls the auth server at GOIABADA_AUTHSERVER_INTERNALBASEURL, which the wizard sets to http://goiabada-authserver:9090: straight to the auth server’s container, over the Compose network, without passing your proxy.
That hop is plain HTTP, and it carries the admin console’s client secret, its refresh token and administrators’ tokens. A Compose network never leaves the host, so the hop is as safe as the host is. The generated file says so in a comment above the variable.
When that isn’t enough, encrypt the hop with the auth server’s own HTTPS listener:
-
Make a certificate for the name the admin console calls,
goiabada-authserver, from a certificate authority of your own, and mount it into the auth server’s container, readable by the user the images run as. -
Turn on the auth server’s HTTPS listener, in its
environment:- "GOIABADA_AUTHSERVER_LISTEN_HOST_HTTPS=0.0.0.0"- "GOIABADA_AUTHSERVER_LISTEN_PORT_HTTPS=9443"- "GOIABADA_AUTHSERVER_CERTFILE=/certs/goiabada-authserver.pem"- "GOIABADA_AUTHSERVER_KEYFILE=/certs/goiabada-authserver-key.pem" -
Mount your certificate authority’s certificate into the admin console’s container, then point the admin console at the listener and have it trust that authority with
GOIABADA_ADMINCONSOLE_INTERNAL_CA_FILE, in itsenvironment:- "GOIABADA_AUTHSERVER_INTERNALBASEURL=https://goiabada-authserver:9443"- "GOIABADA_ADMINCONSOLE_INTERNAL_CA_FILE=/certs/ca.pem" -
Restart both servers with
docker compose up -d.
If the admin console then can’t reach the auth server, see Can’t reach the auth server.
The user the images run as
Section titled “The user the images run as”Both images run as uid 10001 and gid 10001, and never as root. The image names them by number, since it has no /etc/passwd, so a platform that refuses a root container, such as Kubernetes with runAsNonRoot, can verify the user. The binary and the /app directory holding it belong to root, so the process can’t replace what its next start runs.
A file you mount into a container must be readable by uid 10001 or gid 10001, such as the certificate and key named by GOIABADA_AUTHSERVER_CERTFILE and GOIABADA_AUTHSERVER_KEYFILE (and the admin console’s pair). A key file left at mode 0600 and owned by root can’t be read; give it to the user, or to the group with mode 0640:
sudo chown 10001:10001 key.pem# orsudo chgrp 10001 key.pem && sudo chmod 0640 key.pemThe auth server writes to two directories, and its image creates both owned by 10001:
/data, where the generated Compose file mounts the SQLite volume. Docker copies a mount point’s ownership into an empty named volume, so a new volume mounted here is writable from the first start. A volume mounted at a path the image lacks gets a directory Docker creates owned by root, where the server can write nothing./bootstrap, where the legacy bootstrap writesbootstrap.envwhenGOIABADA_AUTHSERVER_BOOTSTRAP_ENV_OUTFILEnames a file in it. Mount a named volume there, and read the file withdocker compose cp goiabada-authserver:/bootstrap/bootstrap.env .. A bind mount of a host directory that doesn’t exist yet is created owned by root, and the write is refused.
The generated file also drops every capability, keeps the root file system read-only and gives each server a /tmp in memory.
What the images contain
Section titled “What the images contain”Each image is built from an empty base, and holds only what its server reads:
| Path | Image | What it is |
|---|---|---|
/app/goiabada-authserver |
Auth server | The server’s binary, owned by root |
/app/goiabada-adminconsole |
Admin console | The server’s binary, owned by root |
/etc/ssl/certs/ca-certificates.crt |
Both | The certificate authorities the server trusts for the TLS connections it makes, as of the release’s build |
/tmp |
Both | An empty folder anyone can write to, as on any Linux system |
/data |
Auth server | Where the SQLite volume mounts, owned by 10001 |
/bootstrap |
Auth server | Where the legacy bootstrap writes its file, owned by 10001 |
Both run as 10001:10001. There’s nothing else in them: no shell, no package manager and no other program, so an image scanner finds no operating system package to report, and docker compose exec has nothing to run but the server. Debugging without a shell shows how to look inside a running one.
To trust a certificate authority of your own as well, such as one that signed your SMTP server’s certificate, mount its certificate into the container and point SSL_CERT_FILE at it. The server then reads that file and every file in /etc/ssl/certs, the image’s bundle among them. To trust only the authorities you choose, mount your own bundle over /etc/ssl/certs/ca-certificates.crt instead:
volumes: - ./ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt:roEither file must be readable by the user the images run as.
An image of your own built FROM leodip/goiabada:… can COPY files in, but can’t RUN a shell command or install a package in that stage, since it has no shell. Do that work in an earlier stage built from another image, and COPY the result in. A program you copy in must be statically linked, as the image has no C library. If your Dockerfile sets USER, end it with USER 10001:10001, by number, for the reason above.
Health checks
Section titled “Health checks”Both binaries check their own server with the healthcheck command: one GET of /health on the server’s own listener, which answers whenever the server is up and listening, without asking the database. It prints nothing when the server is healthy, and otherwise one line saying what it met, and exits with:
0: healthy,/healthanswered200.1: unhealthy: a refused connection, no answer within 3 seconds, or any status but200, a redirect included.2: a listener variable that doesn’t parse, or an argument given. The command takes none.
Each image declares the command as its own health check, every 10 seconds, with a 5-second timeout and 3 retries, and 5 minutes for a first start’s seed or an upgrade’s migrations before its failures count. The image’s check applies wherever nothing sets one of its own: a plain docker run, a Docker Swarm service, and the admin console under the wizard’s files.
To check a container in a Compose file or an orchestrator of your own, use the exec form, with the image’s timings:
healthcheck: test: ["CMD", "/app/goiabada-authserver", "healthcheck"] interval: 10s timeout: 5s start_period: 300s retries: 3For the admin console, the test is ["CMD", "/app/goiabada-adminconsole", "healthcheck"]. A CMD-SHELL test, or one that runs any other program, fails, since the images hold no shell and no other program. On Kubernetes, use an httpGet probe on /health, as the wizard’s manifest does.
The check asks the HTTP listener, GOIABADA_AUTHSERVER_LISTEN_HOST_HTTP and GOIABADA_AUTHSERVER_LISTEN_PORT_HTTP, whenever that listener is on. When it’s off, the check asks the HTTPS one, which GOIABADA_AUTHSERVER_LISTEN_HOST_HTTPS, GOIABADA_AUTHSERVER_LISTEN_PORT_HTTPS, GOIABADA_AUTHSERVER_CERTFILE and GOIABADA_AUTHSERVER_KEYFILE turn on. A wildcard host, 0.0.0.0 or ::, is asked on loopback. Over HTTPS, the check doesn’t verify the certificate, which names your public host rather than loopback. The admin console’s check reads its own GOIABADA_ADMINCONSOLE_ variables of the same names.
An automatic health check runs as a process of its own, and doesn’t inherit the flags the server was started with. If you set the listener with flags, set it in the container’s environment as well, or the check asks the default listener.
Debugging without a shell
Section titled “Debugging without a shell”The images hold no shell, so docker compose exec goiabada-authserver sh fails with exec: "sh": executable file not found. Look inside from a tool container beside the server instead, sharing its network and its processes. From the directory holding the Compose files:
container=$(docker compose ps -q goiabada-authserver)docker run --rm -it --network container:$container --pid container:$container --user 10001:10001 busybox:1.37In the tool container, ps lists the server as PID 1, the server answers on 127.0.0.1:9090, and /proc/1/root/ holds the server’s files, such as the SQLite database in /proc/1/root/data/. Only the server’s own uid and gid can read that folder, so the tool container runs as 10001:10001: as root, ls /proc/1/root/ says Permission denied. If you run the server as another user, run the tool container as that one. For the admin console, use goiabada-adminconsole, which answers on 127.0.0.1:9091.
To read one file out, docker compose cp needs no tool container, and works on the read-only root file system:
docker compose cp goiabada-authserver:/etc/ssl/certs/ca-certificates.crt .Recover a locked-out administrator
Section titled “Recover a locked-out administrator”When nobody who holds authserver:manage can sign in any more, the auth server’s recover subcommand restores sign-in for one named user. The Compose file gives the auth server’s service the database credentials, so one command runs it with them:
printf 'New password: ' && IFS= read -rs RECOVERY_PASSWORD && echoprintf '%s\n' "$RECOVERY_PASSWORD" | docker compose run --rm -T goiabada-authserver recover --email [email protected] --grant-manage --password-stdinunset RECOVERY_PASSWORDThe first line asks for the new password without showing it. Recover the user with the auth server has every flag and what the command changes.