Docker deployment

This page applies to deploying a single JumpCLI application service from source. Prepare commercial billing and authentication services separately, following their respective pages.

Prerequisites

• Docker 24 or later.
• Docker Compose v2.
• At least 2 GB of memory; 4 GB or more is recommended when the billing stack also runs.
• Persistent storage for data and images.

Prepare the environment file

cp .env.example .env

At a minimum, configure access control, administrator step-up verification, and the upstream model service. The example uses placeholders only:

ACCESS_KEY=replace-with-access-gate-secret
ADMIN_KEY=replace-with-distinct-step-up-secret
APP_VERSION=replace-with-verified-release-id
APP_IMAGE=sha256:replace-with-id-from-production-build-script
PUID=1001
PGID=1001
DEFAULT_API_URL=https://api.example.com
DEFAULT_API_KEY=replace-with-api-key-reference
DEFAULT_API_PATH=/v1/images/generations

For production HTTPS, use public domains rather than internal ports. This is a minimum example with no secrets:

PUBLIC_ORIGIN=https://app.jumpcli.com
ALLOWED_HOSTS=app.jumpcli.com
CASDOOR_PUBLIC_ORIGIN=https://auth.jumpcli.com
CASDOOR_REDIRECT_URI=https://app.jumpcli.com/api/identity/callback
ACCESS_COOKIE_SECURE=true
TRUST_PROXY_HEADERS=true
TRUSTED_PROXY_IPS=replace-with-your-proxy-ip-or-cidr

Enable TRUST_PROXY_HEADERS only after entering the actual reverse-proxy IP or CIDR. Do not put Casdoor, Meteroid, or payment keys in these examples or in version control.

Start

Build from the current source:

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build

In production, do not let Compose rebuild from the working directory. From the reviewed release directory, run:

APP_VERSION=<verified-commit> sh scripts/production_build_release.sh

Store the printed APP_IMAGE=sha256:... and the same APP_VERSION in .env, then start with the production Compose layers and --no-build --pull never.

View service status:

docker compose ps
docker compose logs web --tail 50

Verify

curl --fail --silent --show-error http://127.0.0.1:9090/ready
# Production Compose uses a dedicated loopback port and validates Host:
curl --fail --silent --show-error -H 'Host: app.jumpcli.com' http://127.0.0.1:19091/ready

The response should include "status":"ready". /health reports process liveness only and cannot replace the production readiness check. Then use a test account to complete one login and a minimal generation request.

Update

Before updating, back up the data directory and required maintenance logs; then pull the reviewed version and rebuild. Do not resolve startup problems by deleting data volumes.