Self-Hosting Onboarding Guide

A complete walkthrough for deploying and operating FeatureSignals on your own infrastructure — from initial requirements through production hardening, backup strategy, and ongoing monitoring.

System Requirements

Installation

FeatureSignals is distributed as a set of Docker images. The recommended deployment method is Docker Compose:

1. Clone the Repository

git clone https://github.com/dinesh-g1/featuresignals.git
cd featuresignals

2. Configure Environment

Copy the example environment file and customize it for your deployment:

cp .env.example .env
# Edit .env with your configuration values
nano .env

Key environment variables to configure:

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — Random 64+ character secret for token signing
• API_BASE_URL — Public URL where the API server is reachable
• APP_BASE_URL — Public URL where the dashboard is reachable
• SMTP_* — SMTP server settings for transactional email

3. Start the Services

docker compose up -d

This starts PostgreSQL, the API server (port 8080), and the Flag Engine dashboard (port 3000). Database migrations run automatically on first startup.

4. Verify Installation

# Check that all services are running
docker compose ps


# Verify the API server responds
curl http://localhost:8080/health


# Verify the dashboard is accessible
curl http://localhost:3000

SSL / TLS Setup

FeatureSignals must be served over HTTPS in production. The recommended approach is to place a reverse proxy (nginx or Caddy) in front of the application:

Option A: Caddy (Recommended)

Caddy automatically obtains and renews TLS certificates via Let's Encrypt:

featuresignals.example.com {
    reverse_proxy localhost:3000
}


api.featuresignals.example.com {
    reverse_proxy localhost:8080
}

Option B: nginx + Certbot

Traditional nginx setup with Certbot for certificate management:

sudo apt install nginx certbot python3-certbot-nginx
sudo certbot --nginx -d featuresignals.example.com -d api.featuresignals.example.com

Backup Strategy

A comprehensive backup strategy protects against data loss. The most critical data to back up is the PostgreSQL database:

Database Backups

Use pg_dump for logical backups. Schedule this as a cron job:

# Daily database backup at 2 AM UTC
0 2 * * * postgres pg_dump -U featuresignals featuresignals | gzip > /backups/featuresignals-$(date +\%Y\%m\%d).sql.gz


# Retain last 30 days of backups
0 3 * * * postgres find /backups -name "featuresignals-*.sql.gz" -mtime +30 -delete

What to Back Up

• PostgreSQL database — All configuration data: flags, segments, projects, environments, API keys, audit logs
• Environment configuration — Your .env file (contains secrets and connection strings)
• TLS certificates — If not using auto-renewal (Caddy handles this automatically)
• Custom configurations — Any modified nginx/Caddy configs, custom migration scripts

Restore Procedure

# 1. Stop the application
docker compose down


# 2. Restore the database
gunzip < /backups/featuresignals-20260115.sql.gz | psql -U featuresignals featuresignals


# 3. Restart the application
docker compose up -d

Monitoring

A healthy self-hosted deployment requires monitoring at multiple levels:

Security Hardening

Upgrades

To upgrade FeatureSignals to a new version:

# Pull the latest images
docker compose pull


# Apply any new database migrations and restart
docker compose up -d


# Verify the upgrade
docker compose ps
curl http://localhost:8080/health

Next Steps

• On-Premises Deployment— Kubernetes, air-gapped, and advanced deployment patterns
• Docker Compose Reference— detailed configuration options
• Configuration Reference— all environment variables and their defaults