Self-Hosting

Self-host FoxSchema

The web app ships as a single container that serves both the UI and the API on one configurable port. Your database credentials and schema data never leave your infrastructure.

1. Quick start

Pull the prebuilt image

docker run -d --name foxschema \

-p 3210:3210 \

-v foxschema_data:/data \

5nickels/foxschema:latest

# → http://localhost:3210

One image covers all 14 dialects, including IBM Db2. It is linux/amd64 only, because the Db2 driver has no arm64 build. Sign-in is required: the first open creates the administrator account, and from another machine it asks for a setup code printed in docker logs foxschema.

Or build from source with Compose

git clone https://github.com/tedious-code/foxschema.git && cd foxschema

cp .env.example .env # set APP_ENCRYPTION_KEY (openssl rand -hex 32)

docker compose -f docker-compose.app.yml up -d --build

2. The encryption key

APP_ENCRYPTION_KEY encrypts the database passwords you save. It is auto-generated on the /data volume on first boot, so no .env is needed for a basic Docker run. Generate one with openssl rand -hex 32.

Keep the key stable and secret — use your platform's secret manager, never the image or a committed file. If it changes, previously saved passwords can't be decrypted and must be re-entered.

3. Configuration

Variable	Default	Purpose
PORT	3210	Host port published by compose — what you open in the browser.
API_PORT	3210	Port the app listens on inside the container.
APP_ENCRYPTION_KEY	—	Encrypts saved DB passwords. Auto-generated on the /data volume in Docker; set explicitly for managed/secret-store deploys.
APP_DB_ENGINE	sqlite	FoxSchema's own metadata store: sqlite, postgres, or mysql.
APP_DB_URL	—	Metadata-store URL when the engine is postgres/mysql.
LOCAL_SINGLE_USER	true	true = personal install; false = shared server. Sign-in is required either way. This only decides machine-level actions (installing drivers, self-update, changing the metadata DB), which a shared server refuses.
APP_PUBLIC_URL	—	The URL people reach FoxSchema at (for example https://fox.example.com). Invite and reset emails link here, and SSO callbacks use it.
SMTP_HOST, SMTP_FROM	—	Mail relay for invite and password-reset emails (also SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD).
SSO_*	—	OAuth for Google / Microsoft / GitHub (see below).

4. Where your data lives

Saved connections, migration history, and settings live in a SQLite file on the /data volume — keep the volume to keep your data. docker compose down preserves it; down -v deletes it.

On ephemeral-disk platforms (e.g. Cloud Run), point the metadata store at a managed database instead:

APP_DB_ENGINE=postgres

APP_DB_URL=postgresql://user:pass@db-host:5432/foxmeta

5. Access: sign-in and SSO

Complete setup before you share the URL. Sign-in is always required, but whoever finishes the first-run setup owns the install, which is why setup from another machine needs the one-time code from the server log. Keep internet-facing installs behind TLS and, ideally, a VPN, because FoxSchema handles database credentials.

There is no self-registration: admins invite people under Profile → Access control. For a shared server, declare it and, if you use SSO (Google, GitHub or Microsoft), add the provider settings:

LOCAL_SINGLE_USER=false

SSO_REDIRECT_BASE=https://fox.example.com

SSO_GOOGLE_CLIENT_ID=... # + SSO_GOOGLE_CLIENT_SECRET

# callback per provider: ${SSO_REDIRECT_BASE}/api/auth/sso/<provider>/callback

6. IBM Db2

The image includes the IBM Db2 driver, so there is no separate Db2 image or tag. The Db2 driver has no linux/arm64 build, so the image runs on linux/amd64 only.

Full Deployment Guide → Docker Hub → Install options →