Quickstart

This runs a licensed self-hosted JoobQUI server with Docker Compose, connects it to your organization, creates the first admin and connects a worker. It uses the deployment bundle of your release: selfhosted.compose.yml and selfhosted.env.example, in a deploy/ folder. Every variable is explained in Configuration.

You need Docker with Compose, the image of your release (JOOBQUI_SELF_HOSTED_IMAGE), and an admin account of an organization with a paid self-hosted licence at app.joobq.io. There is no licence key to copy: the server fetches its licence when you Sign in with JoobQ in step 3.

Just trying it?

docker run -d -p 4000:4000 -v joobqui-data:/data ghcr.io/azutoolkit/joobqui-selfhosted:latest starts a server with nothing configured: its setup page asks for the licence (Sign in with JoobQ), Redis and PostgreSQL. See Self-hosted server.

1. Create the secrets

From the folder that holds deploy/ (the Compose file reads ../secrets/ relative to deploy/; the container runs as UID 10001, so the files must be readable by it):

mkdir -p secrets
openssl rand -hex 32 > secrets/selfhosted_sdk_token
openssl rand -hex 32 > secrets/selfhosted_session_secret
openssl rand -hex 24 > secrets/selfhosted_postgres_password
printf "postgres://joobqui:%s@postgres:5432/joobqui" "$(cat secrets/selfhosted_postgres_password)" > secrets/selfhosted_database_url
printf "%s" "redis://redis:6379/0" > secrets/selfhosted_redis_url   # the bundled Redis (profile redis), for a trial
chmod 444 secrets/*

Then deploy/.env:

JOOBQUI_SELF_HOSTED_IMAGE=ghcr.io/azutoolkit/joobqui-selfhosted:<your release tag>
JOOBQUI_SELF_HOSTED_DOMAIN=queues.example.com

2. Migrate and start

docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env --profile redis run --rm migrate
docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env --profile redis --profile https up -d

The https profile puts Caddy in front and gets a certificate for JOOBQUI_SELF_HOSTED_DOMAIN from Let's Encrypt (ports 80 and 443 must be reachable). The server's settings are kept in the selfhosted_data volume (/data): back it up with the database.

3. Sign in with JoobQ

Until it has a licence the server serves only its setup page. Find the one-time setup code in its log:

docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env logs app | grep -A4 "not set up yet"

Open https://queues.example.com/, enter the code and the public address, and choose Sign in with JoobQ. The page shows a short code (also in the log). Choose Open JoobQ, sign in at app.joobq.io as an organization admin, check that the address is your server's and choose Approve. Only approve a code your own server shows you. The server saves its licence in /data and the page moves on; save and it restarts into the console. Then check it:

docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env exec app ./joobqui doctor

doctor checks the database, Redis, the session secret and the licence.

No browser near the server? ./joobqui connect --url https://queues.example.com prints the code instead. For unattended installs, create an enrollment token on the portal's licensing page and start the server with JOOBQUI_ENROLLMENT_TOKEN set (see Licence and Pro key).

4. Create the first admin

Sign-up is closed by default. The first account made from the command line is an admin:

docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env exec app ./joobqui accounts:create admin@example.com admin

It asks for the password twice (or reads JOOBQUI_ACCOUNT_PASSWORD). Sign in at https://queues.example.com/ui/.

5. Connect a worker

The worker profile runs an example Python worker with the SDK token:

docker compose -f deploy/selfhosted.compose.yml --env-file deploy/.env --profile redis --profile https --profile worker up -d

For your own worker, give it JOOBQ_GATEWAY_URL (the deployment's origin) and the SDK token, and follow SDKs: install and connect. It shows on the console's Workers page once it has registered.

What is Core and what is Pro

Everything in this quickstart is Core. Workflows, rate limiting, the two unique-job release modes, workflow schedules and alerts need a JoobQ Pro key: see Licensing: Core and Pro.