Skip to content

Installation ​

License

PICKET is licensed under the PolyForm Noncommercial License 1.0.0. Running it for your own community, regiment or association is allowed; selling it, or offering it as a paid service, is not. This is a source-available license, not an OSI-approved open source one. Foxhole and its content belong to Siege Camp and are not covered by this license; PICKET is not affiliated with Siege Camp. See the LICENSE and NOTICE files.

PICKET runs as a single container image in several identical replicas, backed by PostgreSQL. The deploy/ directory contains everything needed for a Docker Compose host, Traefik included.

Requirements ​

  • A Linux host with Docker, Docker Compose v2 and BuildKit enabled to build the backup image. If needed, run export DOCKER_BUILDKIT=1 in the deployment shell; the Buildx plugin must be installed (docker buildx version).
  • The docker-rollout plugin, used for zero-downtime updates.
  • flock on the host (provided by util-linux), to prevent simultaneous deployments.
  • A domain whose DNS is managed by Cloudflare, and a Cloudflare API token limited to that zone (Zone → DNS → Edit). The stack includes its own Traefik: it listens on port 443 only and gets its certificates through the DNS challenge, so port 80 stays closed. Port 443 must be free on the host.
  • A host name for the endpoint, proxied by Cloudflare, with SSL/TLS mode Full (strict).

1. Create the Discord application ​

In the Developer Portal, create an application and note its Application ID and Public Key. Create the bot and copy its token. Enable Server Members Intent for precise voice-role filtering. Leave Presence Intent and Message Content Intent disabled. The code requests GUILDS, GUILD_MEMBERS and GUILD_VOICE_STATES (mask 131). No voice connection or audio permission is required. See Discord intents.

2. Prepare the host ​

Copy the entire deploy/ directory to the server, including backup/, then change into that directory:

sh
./init-secrets.sh                 # prepares PostgreSQL secrets and backup keys
read -rsp 'Bot token: ' TOKEN && printf '%s' "$TOKEN" > secrets/discord_bot_token; unset TOKEN   # keeps it out of the shell history
read -rsp 'Cloudflare token: ' TOKEN && printf '%s' "$TOKEN" > secrets/cloudflare_dns_token; unset TOKEN
cp .env.example .env              # then edit it: image, host name, Discord identifiers

The secrets/ directory is never committed. Required runtime secrets reach the containers as files (*_FILE variables), not as environment variables. The private backup identity is not mounted into any service.

The script also creates the empty secrets/discord_client_secret placeholder. To enable the stats dashboard, paste the OAuth2 client secret of the same Discord application into it and set DASHBOARD_HOST in this .env; see Voice statistics configuration. Keep the file empty if the dashboard is disabled. Neither the bot token nor the OAuth credential is generated locally; obtain both from Discord.

3. Prepare backups ​

Backup tools run in their own container, built from backup/Dockerfile with PostgreSQL 18, pg_dump and age. You do not need to install these tools on the server. Set up encryption before the first deployment: a missing or failed backup blocks migrations.

init-secrets.sh also prepares the encryption keys, with no separate generation command:

File created in secrets/Purpose
backup_recipientsPublic recipient, kept on the server and used by the backup service.
backup_identityPrivate identity, created with mode 600, required to restore the data.

The script uses age-keygen when installed; otherwise it builds the backup image and runs the tool through Docker. It preserves existing keys, including a public recipient whose private identity has already been moved off the server. Multiple public age1… recipients can be present, one per line.

The script prints an action to take: copy secrets/backup_identity to your vault, verify you can recover it, then remove that copy from the server. Keep secrets/backup_recipients in place. Without the private identity, backups cannot be restored.

On the server, from deploy/, prepare the destination with the user who deploys PICKET:

sh
install -d -m 700 ../backups
chmod 700 secrets
chmod 644 secrets/backup_recipients

backup.sh and rollout.sh automatically supply the deployment user’s identity to Compose at runtime. No manual UID/GID setup is needed, and scripts do not modify .env. Create the directory and run the scripts as the same user. BACKUP_DIR=../backups is already the default. Secrets generated by init are readable inside the container; the secrets/ directory stays protected on the host.

4. First start ​

sh
./rollout.sh ghcr.io/<owner>/picket@sha256:<digest>

The script locks the deployment, pulls the image, builds the backup image and starts PostgreSQL and Traefik. It then requires a verified encrypted backup before migrations, replaces the replicas, starts the daily backup service and registers slash commands (only if their definition changed).

Finally, in the Developer Portal, set Interactions Endpoint URL to https://<your host>/interactions. Discord sends a signed request to check it: the endpoint must answer, so complete this step once PICKET is running.

5. Check automatic tasks ​

The job-runner cleans up data every night around 03:00, Europe/Paris: servers past their retention period, journals older than 30 days and interaction records older than 7 days. No additional cron is needed. Remove an old purge cron if you installed one. For a manual cleanup:

sh
docker compose run --rm purge

The backup service runs daily at 03:30, Europe/Paris. On startup it catches up if there has been no successful backup for 24 hours; failed attempts are retried after fifteen minutes. It retains at most five successful backups, daily and pre-migration combined, and removes those at least 30 days old. The oldest is replaced after the new archive is verified and published; a failed attempt does not evict it to make room.

sh
docker compose ps backup
docker compose logs --tail=50 backup

The health check fails after 26 hours without a successful backup. Enable the operator monitoring for Discord alerts and use the short disaster recovery procedure for restores and monthly checks.

Upgrade an existing installation ​

Copy the files in deploy/, including backup/, preserving your .env and secrets/. Run ./init-secrets.sh again to create missing keys without replacing existing secrets. Secure the private identity, and set the new parameters and destination as above. Deploying the bot image does not update these host files.

Before the next deployment, verify a backup and start the daily service:

sh
./init-secrets.sh
docker compose build backup
docker compose up -d --wait postgres
./backup.sh pre-migration
./backup.sh start

The defaults DISCORD_REST_GLOBAL_RPS=20 and DATABASE_POOL_MAX=10 cover the budget of one permanent replica and its deployment overlap. With several replicas, size both limits for the simultaneous peak before deploying.

Behind Cloudflare ​

Use a dedicated host name for the interactions endpoint. Make sure no challenge, bot protection or WAF rule answers POST /interactions: Discord must reach PICKET with the request body unchanged, otherwise the signature check fails and Discord refuses the endpoint.

Updates from GitHub Actions ​

The repository ships a workflow that builds the image, pushes it to GitHub Container Registry and rolls it out over SSH.

  1. Create a dedicated key pair and allow it on the server with a forced command, in ~/.ssh/authorized_keys:

    text
    command="/opt/picket/deploy/ssh-entrypoint.sh",no-pty,no-port-forwarding,no-agent-forwarding,no-X11-forwarding ssh-ed25519 AAAA… picket-deploy

    The key can do nothing but deploy an image referenced by its digest (ghcr.io/<owner>/<image>@sha256:…).

  2. Create a GitHub environment named production, with required reviewers if you want a manual approval, and add the secrets DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY and DEPLOY_KNOWN_HOSTS (the server's pinned host key, so the connection never trusts an unknown host).

  3. Nothing to configure for the registry: the workflow sends the job's temporary token (read access to packages) to the server, which uses it for the pull and logs out right after. No personal token is ever stored on the server. For a manual ./rollout.sh, make the package public or run docker login ghcr.io yourself first.

The deployment only runs after the CI succeeded on main, never from a pull request.

How updates stay invisible ​

  • Database changes are additive; the previous and the new version run together during the switch.
  • A replica being stopped first reports itself as not ready, so Traefik stops sending it requests, then finishes the work in progress.
  • The Discord gateway connection is held by one replica at a time. When it stops, it hands the session over and the next replica resumes it without reconnecting from scratch.

Operating ​

  • Bot and CLI logs are JSON on standard output, with a version field; events associated with a server also include its identifier. Secrets are not logged.
  • /healthz and /readyz listen on an internal port that Traefik does not route.
  • Backups are encrypted in ../backups by default. A copy on the same disk does not protect against its loss: keep an independent copy with the same retention limits.
  • Test a restore in an isolated environment: verify picket.dump.age.sha256, decrypt with the private identity and use pg_restore --exit-on-error on an empty database after creating this stack’s roles. The dump includes all servers’ data despite row security, functions, policies, ownership and privileges; it excludes global roles and their passwords. It does not restore Discord messages or checked todo list items.