Docker builds, images and tags

This page documents the Liteset Dockerfile — its multi-stage build targets, key build-args, and tagging conventions. For a step-by-step production deployment workflow (compose file, healthchecks, secret bootstrap) see Production Docker Deployment.

Liteset vs Apache Superset images

• Apache Superset images (apache/superset:6.0.0, apache/superset:dockerize, etc.) are published by the upstream project and run Flask under Gunicorn.
• Liteset images are built from this repository's Dockerfile and run Litestar/ASGI under Uvicorn (with uvloop). The default container CMD is uvicorn superset.app:create_app --factory --host 0.0.0.0 --port 8088 --workers 4 --loop uvloop.

The upstream apache/superset:* runtime images are not compatible with Liteset's process model — build (or pull from your own registry) a Liteset-tagged image instead. The single exception is apache/superset:dockerize, which the Liteset Helm chart reuses as a tiny init-container only to invoke the dockerize binary while waiting for Postgres/Redis TCP readiness.

Build targets

The Dockerfile defines four published build stages plus a couple of internal intermediates. You select one with --target:

Target	Approx. size	Purpose
lean	~1.2 GB	Production runtime. Uvicorn launcher, non-root superset user, assets baked in, drivers in requirements/base.txt (includes asyncpg + psycopg2-binary).
dev	~1.7 GB	Local development. Extra dev dependencies (requirements/development.txt), git, MySQL build deps, runs as superset. Use with --reload and a source mount.
ci	~1.3 GB	Continuous integration. Built FROM lean plus the [postgres] extra; CMD is /app/docker/entrypoints/docker-ci.sh which runs superset init and then the server.
superset-node	n/a	Internal stage producing the compiled frontend bundle. Not normally pulled directly; consumed by lean and dev.

No py311 / websocket / dockerize targets. Liteset always builds on python:3.11.13-slim-bookworm (override via PY_VER), serves WebSockets natively from the main app (no sidecar), and reuses apache/superset:dockerize verbatim for the Helm wait-for-Postgres init container — there is no Liteset equivalent to build.

Build commands

# Production image
DOCKER_BUILDKIT=1 docker build --target lean -t liteset:lean .

# Dev image, with source intended to be bind-mounted at runtime
DOCKER_BUILDKIT=1 docker build --target dev -t liteset:dev .

# CI image (used by GitHub Actions for smoke tests)
DOCKER_BUILDKIT=1 docker build --target ci -t liteset:ci .

Tag whatever way fits your registry (ghcr.io/your-org/liteset:6.0.0, etc.). Liteset does not publish official images to Docker Hub at this time.

Key Dockerfile ARGs

These can all be passed via --build-arg KEY=value:

• PY_VER (default 3.11.13-slim-bookworm) — base Python image tag. The runtime is regularly tested on 3.11; CPython 3.10–3.13 are supported by Liteset's pyproject.toml. We do not recommend bumping this unless you are working on forward-/backward-compatibility.
• BUILD_TRANSLATIONS (default false) — when true, compiles .po → .mo translation files in the backend and keeps non-English locales in the moment-timezone webpack bundle. Leave at false if you only need English UI — saves a few hundred KB of JS and a couple of seconds on pybabel.
• DEV_MODE (default false) — when true, skips the webpack production build entirely. Used by docker-compose.yml (the interactive dev stack) because the frontend is mounted from the host and rebuilt continuously by a separate superset-node container running npm run dev.
• INCLUDE_CHROMIUM (default false) — bake Chromium into the image for Playwright-based Alerts & Reports / thumbnails.
• INCLUDE_FIREFOX (default false) — same, for Firefox.
• NPM_BUILD_CMD (default build) — npm run <cmd> invoked inside superset-node to produce the asset bundle.
• BUILDPLATFORM (default amd64) — the BuildKit platform used to compile the frontend on cross-arch builds.

Database drivers

Unlike the upstream apache/superset:lean image, Liteset's lean image ships both PostgreSQL drivers out of the box:

• asyncpg — used by Liteset's async SQLAlchemy session at runtime.
• psycopg2-binary — used by Alembic migrations (superset db upgrade), which still run synchronously.

Both are listed in requirements/base.txt and installed into the venv during the lean build. No layering is required to talk to a PostgreSQL metadata DB.

For analytics-database drivers (Snowflake, BigQuery, MSSQL, etc.) and for any extras like the Authlib OAuth client or openpyxl Excel uploads, derive your own image:

# Pin the Liteset tag you want to ship.
FROM liteset:lean

USER root

ENV PLAYWRIGHT_BROWSERS_PATH=/usr/local/share/playwright-browsers

RUN . /app/.venv/bin/activate && \
    uv pip install \
      pymssql \
      snowflake-sqlalchemy \
      Authlib \
      openpyxl \
      Pillow \
      playwright && \
    playwright install-deps && \
    PLAYWRIGHT_BROWSERS_PATH=/usr/local/share/playwright-browsers playwright install chromium

USER superset

CMD ["/usr/bin/run-server.sh"]

/usr/bin/run-server.sh is the production launcher copied into the lean image — it sources the bootstrap script, runs Alembic migrations if requested and execs Uvicorn with the right --workers / --loop flags. The same script is the default CMD for the lean image.

Caching

The build uses BuildKit cache mounts for uv, npm and apt to keep rebuilds fast (--mount=type=cache,target=...). No external cache image is required, but DOCKER_BUILDKIT=1 must be set (or docker buildx build used) for the mounts to take effect.

Platforms

The Liteset GitHub Actions build matrix currently targets linux/amd64 only. linux/arm64 builds are not yet validated. If you need ARM builds for Apple Silicon / Graviton, build the image yourself with docker buildx build --platform linux/arm64; expect them to work in practice (no native code besides the cryptography and psycopg2 wheels) but they are unsupported.

Working with Apple Silicon

Recent Apple Macs ship ARM-based CPUs. Until the multi-arch matrix is enabled, you can either build locally with --platform linux/arm64 or force the amd64 image to run under Rosetta:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

The amd64 image runs fine under Rosetta on M1/M2/M3 hardware; the only downside is slightly higher CPU usage in the container.