Self-Hosted Setup

Overview

dForge can be self-hosted on any infrastructure that supports Docker. A standard deployment includes:

Service	Default port	Description
postgres	5438	PostgreSQL 18 — auto-initializes the auth schema on first run
auth	5002	Auth API — JWT, user management, email sending
api	5001	Main tenant API — RPC, actions, reports
app	5179	SvelteKit frontend (dev or production build)
seq	5341	Seq log viewer (structured logs UI)
cli	—	CLI tool (on-demand container)

Prerequisites

• Docker and Docker Compose
• PostgreSQL 18+ (or use the included Docker image)
• 2 GB RAM minimum (4 GB recommended)
• 10 GB disk space (varies with data volume)

Quick Start with Docker Compose

git clone <repo-url> && cd dForge-core/docker

# Start everything
docker compose up -d

# Create a tenant with sample modules
./setup-tenant.sh mycompany "My Company" admin@mycompany.com

Open http://localhost:5179 and log in.

setup-tenant.sh accepts an optional --erp flag to install the full ERP stack instead of the default CRM + HR sample.

Configuration

Environment Variables

All config lives in docker/.env (committed defaults) and docker/.env.local (gitignored, for secrets).

Variable	Description	Default
POSTGRES_USER	PostgreSQL user	dforge
POSTGRES_PASSWORD	PostgreSQL password	dforge
POSTGRES_PORT	PostgreSQL host port	5438
POSTGRES_DB	PostgreSQL admin database	dforge
JWT_SECRET	JWT signing secret (must be at least 32 characters)	(required)
JWT_ISSUER	JWT issuer URL	https://auth.dforge.app
JWT_AUDIENCE	JWT audience URL	https://dforge.app
EMAIL_PROVIDER	Email backend (resend, log)	resend
EMAIL_FROM_ADDRESS	From address	noreply@dforge.app
EMAIL_RESEND_API_KEY	Resend API key (set in .env.local)	—
APP_PORT	Frontend port	5179
SEQ_URI	Seq log viewer URL	http://seq:80

Database Setup

dForge uses two types of databases:

1. Auth database — stores users, tenants, sessions. Created once.
2. Tenant databases — one per tenant. Created automatically when you provision a tenant. Named dforge_{tenant_code}.

Each tenant database has:

• dforge schema — metadata tables (entities, views, security)
• Module schemas (e.g., crm, hr, fin) — business data tables
• A dedicated database user (tenant_{tenant_code}) with access restricted to its own database

Tenant Management

The cli.sh helper wraps the CLI container so you don’t have to type docker compose run every time. Run from the docker/ directory.

Create a Tenant

./cli.sh tenant create --code acme --name "Acme Corp"

This creates the tenant database (dforge_acme), a dedicated database user (tenant_acme), and initializes the metadata schema.

List Tenants

./cli.sh tenant list

Install Modules

./cli.sh module install --code acme --path /modules/crm
./cli.sh module install --code acme --path /modules/hr
./cli.sh module install --code acme --path /modules/fin

# Reinstall to pick up changes
./cli.sh module install --code acme --path /modules/crm --force

# List installed modules
./cli.sh module list --code acme

Modules are mounted into the CLI container at /modules/.

Reset Everything

./reset.sh    # Wipes all data and starts fresh

Production Checklist

Security

• Generate strong, unique JWT_SECRET
• Set strong DB_ADMIN_PASSWORD
• Enable SSL/TLS for all connections
• Configure firewall rules (only expose ports 443, 5179)
• Set up regular database backups
• Review PostgreSQL authentication settings (pg_hba.conf)

Performance

• Allocate sufficient RAM to PostgreSQL (shared_buffers = 25% of system RAM)
• Configure connection pooling if running many tenants
• Set up monitoring (CPU, memory, disk, database connections)
• Configure log rotation

Backups

• Schedule automated PostgreSQL backups (pg_dump per tenant database)
• Test backup restoration procedure
• Store backups in a separate location from the application server
• Document recovery time objective (RTO)

Updates

dForge releases are distributed as Docker images. To update:

docker compose pull
docker compose up -d

Database migrations run automatically on startup when a new version requires schema changes.

Monitoring

Logging

dForge outputs structured logs to stdout and ships them to Seq (the bundled log viewer at http://localhost:5341). For external aggregation, point any structured-log collector at the API and Auth containers’ stdout, or set SEQ_URI to your own Seq instance.

Health Checks

• API: GET /health — returns 200 if the API is running
• Auth: GET /health — returns 200 if the auth service is running
• Database: monitor PostgreSQL connection count and query performance

Scaling

For high-traffic deployments:

• Horizontal: Run multiple API instances behind a load balancer. Each instance is stateless.
• Database: Consider read replicas for reporting workloads. Each tenant database can be moved to a separate PostgreSQL server.
• Caching: API uses in-memory metadata caching with automatic invalidation on module install/uninstall.