Releases and Docker Hub
This page is for maintainers: how to cut an identity-service release and publish the shellui/identity-service image to Docker Hub. The canonical guide is PUBLISH.md at the repository root. Operators upgrading a deployment should read the Upgrade notes instead.
Image overview
| Item | Value |
|---|---|
| Registry | Docker Hub |
| Repository | shellui/identity-service |
| Recommended tags | 0.9.2, 0.9, latest (see Tagging) |
| Listen port | 8000 |
| Data volume | /app/data (SQLite default path: /app/data/db.sqlite3) |
The image contains the application code and collected static files only. Secrets and configuration come from environment variables at container start (see Configuration).
Pre-release checklist
Run the automated checklist, the same script as pull requests to main:
./tools/pre-release-check.sh
See PUBLISH.md for options and the manual breakdown. In short:
1. Version alignment
These must match the release version (for example 0.9.2):
versioninpyproject.toml(also the OpenAPI version, throughconfig.settings.VERSION)- the
CHANGELOG.mdentry, with its date - green CI and pre-release workflows on the release commit
- the Git tag
v0.9.2(recommended, not checked by the script)
The docs at docs.shellui.com/identity are built and published by shellui/shellui, not by a tag in this repository. CI here only checks that docs/ builds (the Docs build job in .github/workflows/ci.yml).
2. No secrets in the build context
# .env must not be tracked or copied into the image
test ! -f .env || grep -q '^\.env$' .gitignore
docker build -t shellui/identity-service:release-check .
docker run --rm --entrypoint sh shellui/identity-service:release-check \
-c 'test ! -f /app/.env && echo "OK: .env not in image"'
.dockerignore excludes .env, *.sqlite3, .git, and local tooling files. Only .env.example is included, with placeholder values.
3. Smoke test the image
The script starts the image in production mode (DEBUG=false) next to a Redis container. To do it by hand:
eval "$(uv run python manage.py generate_jwt_keys --shell)"
export SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(50))')"
docker build -t shellui/identity-service:0.9.2 .
docker network create identity-smoke
docker run --rm -d --name identity-smoke-redis --network identity-smoke redis:8-alpine
docker run --rm -d --name identity-release-smoke --network identity-smoke -p 18000:8000 \
-e SECRET_KEY \
-e JWT_PRIVATE_KEY \
-e JWT_ISSUER=https://auth.local \
-e JWT_AUDIENCE=shellui \
-e REDIS_URL=redis://identity-smoke-redis:6379/0 \
-e SECURE_SSL_REDIRECT=false \
-e ALLOWED_HOSTS=localhost,127.0.0.1 \
shellui/identity-service:0.9.2
# 400 (missing company_id) proves gunicorn and Django are up
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18000/api/v1/settings
# JWKS must return at least one RSA key
curl -s http://127.0.0.1:18000/.well-known/jwks.json \
| python3 -c "import sys,json; assert len(json.load(sys.stdin).get('keys',[]))>=1"
docker rm -f identity-release-smoke identity-smoke-redis
docker network rm identity-smoke
SECURE_SSL_REDIRECT=false is only there so curl can use plain HTTP. Keep it on in real deployments.
4. Multi-architecture build
On Apple Silicon, the default image is linux/arm64 only, and most cloud VMs expect linux/amd64. Publish both with buildx:
docker buildx create --use --name multi 2>/dev/null || docker buildx use multi
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t shellui/identity-service:0.9.2 \
--push .
Tagging
For release 0.9.2, publish these tags:
| Tag | Purpose |
|---|---|
0.9.2 | Exact release, pin it in production |
0.9 | Latest patch of the 0.9 line |
latest | Newest release, use with care |
Publish to Docker Hub
You need push access to the shellui organization on Docker Hub, docker login, and a clean Git tree at the release commit. There is no GitHub Actions workflow for the Docker publish yet: releases are manual.
From the repository root, build and push all tags for both platforms:
VERSION=0.9.2
IMAGE=shellui/identity-service
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t "${IMAGE}:${VERSION}" \
-t "${IMAGE}:0.9" \
-t "${IMAGE}:latest" \
--push .
git tag -a "v${VERSION}" -m "Release ${VERSION}"
git push origin "v${VERSION}"
For a single-platform push from your machine, use docker build and docker push "${IMAGE}:${VERSION}", then docker tag and push the other tags.
Run the published image
The production checklist is in Run identity-service. A minimal production run looks like this:
docker run -d \
--name identity-service \
-p 8000:8000 \
-v identity-service-data:/app/data \
-e SECRET_KEY='your_secret_key_here' \
-e JWT_PRIVATE_KEY='your_pem_private_key_here' \
-e JWT_ISSUER='https://auth.example.com' \
-e JWT_AUDIENCE='shellui' \
-e REDIS_URL='redis://redis:6379/0' \
-e ALLOWED_HOSTS='auth.example.com' \
-e CSRF_TRUSTED_ORIGINS='https://auth.example.com' \
-e POSTGRES_DATABASE_URL='postgres://user:password@db:5432/identity' \
shellui/identity-service:0.9.2
OAuth credentials are stored per company in the database (Shellui admin, POST /api/v1/oauth-social-apps, or Django admin), not in environment variables. The entrypoint runs migrations on start, then starts gunicorn and the scheduled jobs as user appuser.
Security notes
| Topic | Status |
|---|---|
.env in the image | Excluded by .dockerignore, and checked by the pre-release script |
JWT_PRIVATE_KEY | Provided at runtime, never baked into the image |
| JWKS endpoint | /.well-known/jwks.json exposes public keys only |
Build-time SECRET_KEY | Used only for collectstatic during docker build. It shows in the build history as build-only-not-for-runtime and is not used at runtime |
| SQLite and database files | Excluded from the image. Use a volume or PostgreSQL |
| Process user | gunicorn and the worker run as appuser. The entrypoint may run brief setup as root |
DEBUG | Optional, false when unset (settings and Dockerfile). docker-compose.yml sets true for local runs |
Do not commit .env or real OAuth secrets. Do not pass secrets as Docker build arguments: they can appear in the image history.
Known limitations
- SQLite on a volume is fine for a single-node trial. Use
POSTGRES_DATABASE_URLin production - Behind a TLS-terminating proxy, set
CSRF_TRUSTED_ORIGINS; the app relies onSECURE_PROXY_SSL_HEADER
Rollback
Pull and run a previous tag or digest:
docker pull shellui/identity-service:0.7.0
Data in the identity-service-data volume or PostgreSQL does not depend on the image tag. Migrations do not run backwards on their own, so test a downgrade before you rely on it.