Auth Container Command Reference

The Auth container ships two binaries inside the image:

authlance exposes the runtime sub-commands (serve, backup, load-backup, stripe-webhook).
authlancectl provides the administrative client for the license endpoints.

Both binaries live in /app inside the container and read configuration from /app/config/config.yaml.

Running commands inside Docker

# open a shell in the running auth container
docker compose exec authlance sh

# or run a one-off command directly
docker compose exec authlance ./authlance --help
docker compose exec authlance ./authlance <command> --config /app/config/config.yaml

The serve command is started automatically by start-authlance.sh, but you can re-run it manually with a different config when debugging.

`authlance` sub-commands

Command	Purpose	Key flags
`serve`	Boots the Authlance API, background workers, and NGINX reverse proxy.	`--config`, `-c` (defaults to `/app/config/config.yaml`).
`backup`	Dumps the configured MySQL databases, zips them, uploads to the secondary S3 bucket, and rotates daily/monthly backups.	`--config`, `-c` (must contain `backup.databases` and `s3Config`).
`load-backup`	Restores MySQL from the latest (or selected) backup stored in S3 or from a local archive.	`--config`, `-c`, `--key`, `--file`, `--monthly`.
`stripe-webhook`	Ensures the expected Stripe webhook endpoints exist and creates them if missing.	`--config`, `-c`, `--connect` (targets connected accounts).

Serve

The default entrypoint is equivalent to:

docker compose exec authlance ./authlance serve --config /app/config/config.yaml

Use a different config file (for example, when mounting /tmp/auth-config.yaml) by passing --config /tmp/auth-config.yaml. The command loads the config, initializes logging, builds the backend, and keeps running until the process is terminated.

Backup

Create an on-demand backup and push it to the configured S3 bucket:

docker compose exec authlance ./authlance backup --config /app/config/config.yaml

The command runs mysqldump for each database listed under backup.databases, stores each dump in a temporary directory, zips the files (named authlance-YYYY-MM-DD.zip), uploads the archive to s3Config.secondaryBucket, and performs daily/monthly retention. Make sure the config includes valid DB credentials and S3 keys before running it.

Load backup

To restore the latest daily snapshot from S3:

docker compose exec authlance ./authlance load-backup --config /app/config/config.yaml

Switch to a specific object with --key mysql/authlance-2024-05-01.zip, restore the latest monthly snapshot via --monthly, or use an already-downloaded archive with --file /tmp/authlance.zip (mutually exclusive with --key). The command will drop and recreate every database listed in the config, so run it only in controlled environments.

Stripe webhook

Ensure the standard Stripe webhook exists:

docker compose exec authlance ./authlance stripe-webhook --config /app/config/config.yaml

Add --connect to create the webhook that receives events from connected accounts. When a webhook is created, the secret is printed once—store it securely.

Administrative CLI (`authlancectl`)

authlancectl communicates with the Authlance admin API to inspect or reload the license state. It accepts flags or the environment variables AUTHLANCE_ADMIN_URL and AUTHLANCE_API_TOKEN.

# Show status in human-readable form
docker compose exec authlance ./authlancectl license status \
  --url http://nginx/authlance/identity/api/v1/admin \
  --token "$AUTHLANCE_API_TOKEN"

# Force a reload and print JSON
docker compose exec authlance ./authlancectl license reload \
  --token "$AUTHLANCE_API_TOKEN" \
  --json

Use --json when you prefer machine-readable output (e.g., in automation).

Tips

Always run commands with the same config file the container is already using unless you intentionally need different credentials.
backup and load-backup rely on the same S3 credentials. Validate connectivity (aws s3 ls) before executing them in production.
Add the commands to your automation by exec’ing into the container from CI/CD after docker compose up finishes.