Skip to main content

Shellui local dev stack

The shared compose file lives in shellui/shellui at dev/docker-compose.yml. It builds this repo with target: dev, bind-mounts the checkout at /app, and maps host port 8004 to container port 8000.

Start the full stack from the shellui repo:

cd shellui/dev
./start.sh

Clone layout, URLs, common commands and troubleshooting are in the Shellui dev stack guide. This page only covers what is specific to this service.

This page lists what email-service expects in that stack. For a standalone clone of email-service only, see Run email-service.

Ports and URLs​

RoleValue
Browser and public originhttp://localhost:8004
Compose service name (internal)email
Container listen port8000
Mailpit SMTP (platform fallback)mailpit:1025 (host UI on 8025)

Callers on the host use EMAIL_SERVICE_URL=http://localhost:8004. Other containers use http://email:8000.

Required variables​

Set these on the email container (compose maps prefixed names from dev/.env.local).

VariableExample in dev stackNotes
SECRET_KEYgeneratedAny non-empty value when DEBUG=true
DEBUGtrueEnables local defaults and Django autoreload in the dev target
POSTGRES_DATABASE_URLpostgres://shellui:shellui@postgres:5432/emailOne database per service on shared Postgres
REDIS_URLredis://redis:6379/3Shared Redis; use a distinct DB index from other services
PUBLIC_BASE_URLhttp://localhost:8004Links in mail and unsubscribe URLs
EMAIL_PUBLIC_URLhttp://localhost:8004Library static assets; defaults to PUBLIC_BASE_URL
ALLOWED_HOSTSlocalhost,127.0.0.1,emailInclude the compose service name
CSRF_TRUSTED_ORIGINShttp://localhost:8004,http://localhost:5173This service plus admin (5173)
CORS_ALLOW_ALL_ORIGINStrueLocal only; unset in production
IDENTITY_ISSUERhttp://localhost:8001Public issuer; must match identity JWT_ISSUER
IDENTITY_AUDIENCEshelluiMust match identity JWT_AUDIENCE
IDENTITY_JWKS_URLhttp://identity:8000/.well-known/jwks.jsonServer-to-server JWKS fetch inside the network
IDENTITY_SERVICE_URLhttp://identity:8000Audience and other identity API calls from the container
EMAIL_CREDENTIALS_KEYFernet keyEncrypt provider credentials at rest
EMAIL_VARIABLES_KEYFernet keyEncrypt template variables
EMAIL_HASH_PEPPERrandom stringHMAC pepper for recipient addresses

Generate Fernet keys and a pepper with python manage.py generate_env (see Configuration).

Identity: public issuer, internal JWKS​

Admin JWTs use IDENTITY_ISSUER as the expected iss claim (browser-facing http://localhost:8001). Verification loads keys from IDENTITY_JWKS_URL on the internal network (http://identity:8000/.well-known/jwks.json), not from the public host port. Pinning IDENTITY_JWKS or IDENTITY_JWKS_FILE is optional in dev.

Platform mail through Mailpit​

To deliver platform fallback mail into Mailpit without Resend:

VariableDev stack value
EMAIL_FALLBACK_PROVIDERsmtp
EMAIL_HOSTmailpit
EMAIL_PORT1025
EMAIL_USE_TLSfalse
EMAIL_USE_SSLfalse
EMAIL_SMTP_VERIFY_CERTfalse

Open http://localhost:8025 to read captured messages. Production keeps verified TLS; do not set EMAIL_SMTP_VERIFY_CERT=false outside local dev.

Workers and scheduled jobs​

The dev Docker target runs migrate and runserver only. The Shellui compose file may start lane workers and Celery in separate services or overrides. Set REDIS_URL so scheduled jobs can run when those processes are enabled.

For the production image, lane workers and the scheduler start in the same container via tools/docker-entrypoint.sh.

Service keys for callers​

In the dev stack, generate-env.sh writes one esk_ key per caller and compose passes them as EMAIL_DEV_SERVICE_KEYS (service=esk_... pairs). The dev entrypoint runs python manage.py register_dev_service_keys after migrate, which stores only the key hash and skips keys already registered. The command refuses to run unless DEBUG=true, so it never seeds keys in production. Dev keys are not scoped to a company, like production platform keys from create_service_key.

Point identity, storage, and hosting at EMAIL_SERVICE_URL=http://email:8000 inside the network (host port 8004 from your machine).

Dockerfile targets​

TargetUse
devShellui dev compose: deps in /opt/venv and /opt/node, source bind-mounted at /app
productionDefault build and Docker Hub publish (unchanged behaviour)

Build the dev target locally:

docker build --target dev -t shellui/email-service:dev .