docker-compose.yml

# One node. What `big serve` is without --cluster: every shard, no peers, and the same coordinator
# a four-machine deployment runs.
#
#   cd deploy/single
#   mkdir -p secrets && chmod 700 secrets
#   big passwd secrets/users set ops --role superuser
#   docker compose up -d
#   curl -u ops:$PASSWORD localhost:7654/ready
#
# The users file is written by `big passwd` and by nothing else - it holds an argon2 hash, which
# a `printf` into a file cannot produce. `superuser` is the role to start with: every other role
# is a catalog object made with `CREATE ROLE`, and a users file naming one the catalog does not
# have yet is a credential that authenticates and may do nothing. See docs/access-control.md.

services:
  big:
    build:
      context: ../..
    # Published to loopback only, which is what makes the plaintext below a decision rather
    # than an oversight. **TLS is no longer "never":** `big serve` takes `--tls-cert` and
    # `--tls-key`, so a port reachable from anywhere else either terminates TLS here or behind a
    # reverse proxy - runbook.md has one that works.
    ports:
      - "127.0.0.1:7654:7654"
    volumes:
      - data:/data
      # The directory, never the file. A single-file bind mount breaks the first time anything
      # replaces the file rather than writing through it, which is what every editor does. The
      # entrypoint stages what is in here into a private copy - see deploy/entrypoint.sh.
      - ./secrets:/etc/big/secrets:ro
    command:
      - /data/big.db
      - 0.0.0.0:7654
      - --users
      # Staged from the mount by the entrypoint, which reads it as root and writes a private
      # copy: a bind mount carries the host's ownership, which the image cannot predict.
      - /run/big/users
      # **Set it on a new deployment.** There is no default, on purpose - a query that used to
      # finish must not start failing because the server was upgraded - but a daemon with no
      # ceiling is a daemon one expensive query can hold a worker on for as long as it likes.
      - --query-timeout
      - "30"
      # Full durability is the default and is stated anyway: an operator reading this file
      # should not have to know what the default is to know what they are running.
      - --durability
      - full
      # **Without this the container starts and exits.** `big serve` refuses a non-loopback bind
      # in the clear, and a container binds `0.0.0.0` by definition - its loopback is its own, so
      # there is no address here that would satisfy the check. What makes that safe is the port
      # above: published to `127.0.0.1`, so the clear-text hop is inside one machine. Put TLS on
      # this - `--tls-cert` and `--tls-key`, or a proxy in front - before publishing it wider,
      # and drop this flag when you do.
      - --insecure-no-tls
      # Where `POST /admin/backup` may write. **This is the only way to back up a running node**:
      # `big backup` needs the exclusive lock the daemon is holding, so it is for a file nothing
      # has open. The directory is the volume itself, which exists and is writable by the
      # daemon's user without any setup; a backup that stays here is not a backup, so copy it off
      # - see deploy/readme.md.
      - --backup-dir
      - /data
    restart: unless-stopped
    # No memory limit here, and that is a decision rather than an omission. Reads come out of
    # the mapping, so most of what this process appears to use is page cache the kernel will
    # give back; a hard limit turns that into an OOM kill under load. What bounds a *query* is
    # the engine's own ceiling, not the container's. Set one if you have measured your
    # workload, not because a template had one.
    #
    # deploy:
    #   resources:
    #     limits:
    #       memory: 2g
    # `big serve` has no signal handler, and it does not need one: the meta page flip is the only
    # atomic point in a commit, so a process that is killed outright leaves a file that is
    # either before that flip or after it. There is nothing to replay and nothing to lose, so
    # the default ten seconds is nine and a half more than this needs.
    stop_grace_period: 2s

volumes:
  data: