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 fox \

-p 3001:3001 \

-e APP_ENCRYPTION_KEY=$(openssl rand -hex 32) \

-v fox_data:/data \

5nickels/foxschema:latest

# → http://localhost:3001

Multi-arch (amd64 + arm64). Covers 9 of 10 dialects — for IBM Db2 see the variant below.

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 required — the app refuses to start without it in production. 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	3001	Host port published by compose — what you open in the browser.
API_PORT	3001	Port the app listens on inside the container.
APP_ENCRYPTION_KEY	—	Required. 32-byte key that encrypts saved DB passwords.
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 = no login (single user); false = real accounts.
AUTH_REQUIRED	false	true = every request needs a session (pair with accounts).
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: single-user vs. team + SSO

Do not expose the default setup to the public internet. The default is open single-user — no login, anyone who reaches the URL gets full access. Keep it on a trusted network / VPN, or enable accounts + SSO below. Always terminate TLS for anything internet-facing — FoxSchema handles database credentials.

For a shared or public deployment, enable real accounts with SSO (Google, GitHub, or Microsoft):

LOCAL_SINGLE_USER=false

AUTH_REQUIRED=true

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 variant

The common image excludes the ~1 GB IBM Db2 driver (no arm64 build exists). Db2 shows "driver not installed"; the other 9 dialects work. Need Db2? Build the Db2-enabled variant (linux/amd64 only):

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

Full Deployment Guide → Docker Hub → Desktop downloads →