Skip to content

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.

  1. 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.com and https://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.com

    It writes docker-compose.yml, which you can commit, and docker-compose.override.yml beside it, which holds every secret. Never commit the override.

  2. Back up the AES key from the override before anything else: see Back up the AES key.

  3. 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 -d

    Docker Compose reads the override without being asked. The first start seeds the database, which can take a minute.

  4. Check both servers answer on the host:

    Terminal window
    curl http://127.0.0.1:9090/health # healthy
    curl http://127.0.0.1:9091/health # healthy
  5. Put a proxy in front, with one of the three pages above, and then sign in.

  • 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-data volume. 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.1 alone, 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 down or restart, 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 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:

  1. 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.

  2. 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"
  3. 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 its environment:

    - "GOIABADA_AUTHSERVER_INTERNALBASEURL=https://goiabada-authserver:9443"
    - "GOIABADA_ADMINCONSOLE_INTERNAL_CA_FILE=/certs/ca.pem"
  4. 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.

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:

Terminal window
sudo chown 10001:10001 key.pem
# or
sudo chgrp 10001 key.pem && sudo chmod 0640 key.pem

The 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 writes bootstrap.env when GOIABADA_AUTHSERVER_BOOTSTRAP_ENV_OUTFILE names a file in it. Mount a named volume there, and read the file with docker 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.

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:ro

Either 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.

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, /health answered 200.
  • 1: unhealthy: a refused connection, no answer within 3 seconds, or any status but 200, 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: 3

For 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.

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:

Terminal window
container=$(docker compose ps -q goiabada-authserver)
docker run --rm -it --network container:$container --pid container:$container --user 10001:10001 busybox:1.37

In 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:

Terminal window
docker compose cp goiabada-authserver:/etc/ssl/certs/ca-certificates.crt .

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:

Terminal window
printf 'New password: ' && IFS= read -rs RECOVERY_PASSWORD && echo
printf '%s\n' "$RECOVERY_PASSWORD" | docker compose run --rm -T goiabada-authserver recover --email [email protected] --grant-manage --password-stdin
unset RECOVERY_PASSWORD

The 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.