HUB
Sign inSign up
email-service logo

shellui/email-service

By shellui

•Updated 4 days ago

Email service for templating and sending Shellui emails.

Image
0

1.6K

shellui/email-service repository overview

⁠email-service

email-service sends mail for Shellui. identity-service, storage-service, and hosting-service call it for sign-in links, invitations, and event mail. Pull shellui/email-service to run it. Shellui is free to run under the MIT License.

⁠What the image includes

The production stage is python:3.14-slim. Gunicorn listens on port 8000. The entrypoint is /app/tools/docker-entrypoint.sh, and the process runs as the non-root user appuser.

The default command migrates, then starts Gunicorn, the scheduler, and a worker per mail lane (auth, transactional, bulk). Pass worker to run the scheduler and lane workers without Gunicorn or migrations. The image includes Node.js 22 for React Email rendering. The image declares a volume at /app/data.

⁠Start with docker run

This command starts the web process and maps host port 8000 to the container. Replace each placeholder with a real value. Postgres and Redis must accept connections at the URLs you set. The command does not start those databases.

docker run --rm -p 8000:8000 \
  -e SECRET_KEY=your_secret_key_here \
  -e DEBUG=false \
  -e ALLOWED_HOSTS=email.example.com \
  -e CSRF_TRUSTED_ORIGINS=https://email.example.com \
  -e PUBLIC_BASE_URL=https://email.example.com \
  -e IDENTITY_SERVICE_URL=https://id.example.com \
  -e IDENTITY_ISSUER=https://id.example.com \
  -e IDENTITY_AUDIENCE=shellui \
  -e POSTGRES_DATABASE_URL=postgres://email:your_password_here@db:5432/email \
  -e REDIS_URL=redis://redis:6379/0 \
  -e EMAIL_CREDENTIALS_KEY=your_credentials_key_here \
  -e EMAIL_VARIABLES_KEY=your_variables_key_here \
  -e EMAIL_HASH_PEPPER=your_hash_pepper_here \
  shellui/email-service:latest

⁠Start with Compose

This Compose file sets the same required variables. Point POSTGRES_DATABASE_URL and REDIS_URL at Postgres and Redis you already run.

services:
  email-service:
    image: shellui/email-service:latest
    ports:
      - "8000:8000"
    environment:
      SECRET_KEY: your_secret_key_here
      DEBUG: "false"
      ALLOWED_HOSTS: email.example.com
      CSRF_TRUSTED_ORIGINS: https://email.example.com
      PUBLIC_BASE_URL: https://email.example.com
      IDENTITY_SERVICE_URL: https://id.example.com
      IDENTITY_ISSUER: https://id.example.com
      IDENTITY_AUDIENCE: shellui
      POSTGRES_DATABASE_URL: postgres://email:your_password_here@db:5432/email
      REDIS_URL: redis://redis:6379/0
      EMAIL_CREDENTIALS_KEY: your_credentials_key_here
      EMAIL_VARIABLES_KEY: your_variables_key_here
      EMAIL_HASH_PEPPER: your_hash_pepper_here

⁠Required environment variables

Use these production variables from config/env_registry.py when DEBUG is false:

VariableRole
SECRET_KEYSigns sessions and cross-site request forgery (CSRF) tokens, and must be at least 50 characters.
DEBUGLeave this false in production. The image defaults to false.
ALLOWED_HOSTSPublic host names, comma-separated, no scheme
CSRF_TRUSTED_ORIGINSFull HTTPS origin of this service
PUBLIC_BASE_URLPublic URL of this service, including links in mail
IDENTITY_SERVICE_URLidentity-service origin. When keys are not pinned, email-service fetches the JSON Web Key Set (JWKS) from that origin at /.well-known/jwks.json.
IDENTITY_ISSUERJSON Web Token (JWT) iss claim. Match identity-service JWT_ISSUER.
IDENTITY_AUDIENCEJWT aud claim. Match identity-service JWT_AUDIENCE.
POSTGRES_DATABASE_URLPostgreSQL connection URL
REDIS_URLShared cache and job broker
EMAIL_CREDENTIALS_KEYFernet key for provider credentials
EMAIL_VARIABLES_KEYFernet key for template variables
EMAIL_HASH_PEPPERHash-based message authentication code (HMAC) secret for recipient addresses

Generate SECRET_KEY and the three mail secrets with the commands in the configuration reference⁠. That page also lists each optional variable and its default.

⁠Image tags

The publish workflow builds linux/amd64 and linux/arm64. For Git tag vX.Y.Z, it pushes these tags:

TagWhen
X.Y.ZEvery published release
X.YThat same release
latestEvery release except a GitHub prerelease, plus every manual run

⁠Health check

The image health check calls GET /health/live on port 8000. A 200 means the web process is up, and the check does not query Postgres or Redis. In worker mode the check passes while the entrypoint is running. GET /api/v1/health is public and returns the process version.

Read the source, the handbook, the changelog, the license, and Shellui:

Tag summary

Content type

Image

Digest

sha256:29771a613…

Size

340.4 MB

Last updated

4 days ago

docker pull shellui/email-service