Database Setup for Self-Hosting

Overview

DeployStack uses PostgreSQL as its database backend, providing enterprise-grade reliability with ACID compliance, connection pooling, and advanced features for production deployments. Important: PostgreSQL must be running and accessible before starting your DeployStack instance.

What You’ll Need

PostgreSQL 13+ installed and running (or included in Docker Compose)
Database connection details (host, port, username, password)
About 5-10 minutes to complete the configuration

Deployment Options

Option 1: Docker Compose (Recommended)

If you’re using our Docker Compose setup, PostgreSQL is included and automatically configured. No manual database setup required!

# PostgreSQL is automatically included
docker-compose up -d

The Docker Compose setup includes:

PostgreSQL 18 Alpine
Automatic health checks
Persistent data volume
Pre-configured connection details

Option 2: External PostgreSQL Server

For production deployments with existing PostgreSQL infrastructure:

Step 1: Prepare PostgreSQL Database

Create Database and User

Connect to your PostgreSQL server and create a dedicated database and user:

-- Connect to PostgreSQL as admin
psql -U postgres

-- Create database
CREATE DATABASE deploystack;

-- Create user with password
CREATE USER deploystack_user WITH ENCRYPTED PASSWORD 'your_secure_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE deploystack TO deploystack_user;

-- Grant schema privileges (PostgreSQL 15+)
\c deploystack
GRANT ALL ON SCHEMA public TO deploystack_user;
GRANT ALL ON ALL TABLES IN SCHEMA public TO deploystack_user;
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO deploystack_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO deploystack_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO deploystack_user;

-- Exit
\q

Verify Connection

Test the database connection:

# Test connection
psql -h localhost -U deploystack_user -d deploystack -c "SELECT version();"

# You should see PostgreSQL version information

Step 2: Configure Environment Variables

Set PostgreSQL connection details in your environment:

For Docker Deployments

Add to your .env file:

# PostgreSQL Configuration
POSTGRES_HOST=your-postgres-host     # e.g., localhost or postgres.example.com
POSTGRES_PORT=5432                   # Default PostgreSQL port
POSTGRES_DATABASE=deploystack        # Database name
POSTGRES_USER=deploystack_user       # Database user
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_SSL=false                   # Set to 'true' for SSL connections

For Local Development

Edit services/backend/.env:

# PostgreSQL Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=deploystack
POSTGRES_USER=deploystack
POSTGRES_PASSWORD=deploystack
POSTGRES_SSL=false

Step 3: Start DeployStack

Once PostgreSQL is configured, start your DeployStack instance:

Docker Compose

docker-compose up -d

Individual Containers

# Start backend with PostgreSQL configuration
docker run -d \
  --name deploystack-backend \
  -p 3000:3000 \
  -e POSTGRES_HOST=your-postgres-host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DATABASE=deploystack \
  -e POSTGRES_USER=deploystack_user \
  -e POSTGRES_PASSWORD=your_secure_password_here \
  -e POSTGRES_SSL=false \
  -e DEPLOYSTACK_ENCRYPTION_SECRET=your-secret-here \
  -v deploystack_backend_persistent:/app/persistent_data \
  deploystack/backend:latest

Step 4: Complete Setup Wizard

Access DeployStack: Navigate to your frontend URL (e.g., http://localhost:8080)
Automatic Redirect: You’ll be redirected to /setup
Database Initialization: The wizard will:
- Test PostgreSQL connection
- Apply database migrations
- Create necessary tables
- Initialize system data
Create Admin Account: Set up your administrator account
Configuration: Complete basic platform settings

SSL/TLS Connection

For secure connections to PostgreSQL:

Enable SSL in PostgreSQL

Configure PostgreSQL (postgresql.conf):

ssl = on
ssl_cert_file = '/path/to/server.crt'
ssl_key_file = '/path/to/server.key'
ssl_ca_file = '/path/to/root.crt'

Set Environment Variable:
POSTGRES_SSL=true
Restart PostgreSQL and DeployStack backend

Production Considerations

Connection Pooling

DeployStack uses node-postgres with connection pooling:

Default max connections: 20
Idle timeout: 30 seconds
Connection timeout: 2 seconds

Database Maintenance

# Vacuum database (reclaim storage)
psql -U deploystack_user -d deploystack -c "VACUUM ANALYZE;"

# Check database size
psql -U deploystack_user -d deploystack -c "SELECT pg_size_pretty(pg_database_size('deploystack'));"

# View active connections
psql -U deploystack_user -d deploystack -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'deploystack';"

Backup Strategy

# Create backup
pg_dump -h localhost -U deploystack_user deploystack > backup.sql

# Compressed backup
pg_dump -h localhost -U deploystack_user deploystack | gzip > backup.sql.gz

# Custom format (supports parallel restore)
pg_dump -h localhost -U deploystack_user -Fc deploystack > backup.dump

# Restore from backup
psql -h localhost -U deploystack_user deploystack < backup.sql

# Restore from custom format
pg_restore -h localhost -U deploystack_user -d deploystack backup.dump

Performance Tuning

Edit PostgreSQL configuration (postgresql.conf):

# Memory settings
shared_buffers = 256MB              # 25% of RAM
effective_cache_size = 1GB          # 50-75% of RAM
maintenance_work_mem = 64MB
work_mem = 16MB

# Connections
max_connections = 100

# Write-ahead log
wal_buffers = 16MB
checkpoint_completion_target = 0.9

# Query planner
random_page_cost = 1.1              # For SSD storage
effective_io_concurrency = 200      # For SSD storage

Troubleshooting

”Connection refused” or “Cannot connect”

Solutions:

Check PostgreSQL is running:

# For system service
sudo systemctl status postgresql

# For Docker
docker ps | grep postgres

Check PostgreSQL is listening:
netstat -an | grep 5432

Check PostgreSQL configuration (postgresql.conf):

listen_addresses = '*'              # Or specific IP

Check firewall rules:

# Allow PostgreSQL port
sudo ufw allow 5432

“Authentication failed”

Solutions:

Verify credentials: Double-check username and password

Check pg_hba.conf:

# Allow password authentication
host    all             all             0.0.0.0/0               md5

Reload PostgreSQL after config changes:
sudo systemctl reload postgresql

“Database does not exist”

Solutions:

Create database as shown in Step 1
Check database name matches environment variable
Verify user has access:
\l -- List all databases

“Permission denied”

Solutions:

Grant proper privileges as shown in Step 1
Check user permissions:
\du -- List user permissions

Migration Errors

Solutions:

Check PostgreSQL version: DeployStack requires PostgreSQL 13+
Verify user privileges: User needs CREATE, ALTER, DROP permissions
Check logs: Review backend logs for detailed error messages

Manual migration reset (development only):

-- Connect to database
psql -U deploystack_user -d deploystack

-- Drop all tables
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;
GRANT ALL ON SCHEMA public TO deploystack_user;

-- Restart backend to re-apply migrations

Monitoring

Check Database Health

-- Check active connections
SELECT count(*) FROM pg_stat_activity WHERE datname = 'deploystack';

-- Check table sizes
SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Check index usage
SELECT schemaname, tablename, indexname, idx_scan as scans
FROM pg_stat_user_indexes
ORDER BY idx_scan DESC;

-- Check slow queries
SELECT pid, now() - query_start as duration, query
FROM pg_stat_activity
WHERE state = 'active' AND now() - query_start > interval '1 second'
ORDER BY duration DESC;

Security Notes

Use strong passwords for database users
Enable SSL/TLS for production deployments
Restrict network access using pg_hba.conf
Regular backups are essential for data protection
Rotate passwords periodically
Monitor access logs for suspicious activity

Next Steps

After successful database setup:

Complete Setup Wizard - Create your admin account
Configure Global Settings - Set up email, authentication, etc.
Deploy Satellites - Set up MCP server management infrastructure
Create Teams - Invite team members and set up workspaces

Your DeployStack instance is now ready to use!

Guides

Administration

Overview

What You’ll Need

Deployment Options

Option 1: Docker Compose (Recommended)

Option 2: External PostgreSQL Server

Step 1: Prepare PostgreSQL Database

Create Database and User

Verify Connection

Step 2: Configure Environment Variables

For Docker Deployments

For Local Development

Step 3: Start DeployStack

Docker Compose

Individual Containers

Step 4: Complete Setup Wizard

SSL/TLS Connection

Enable SSL in PostgreSQL

Production Considerations

Connection Pooling

Database Maintenance

Backup Strategy

Performance Tuning

Troubleshooting

”Connection refused” or “Cannot connect”

“Authentication failed”

“Database does not exist”

“Permission denied”

Migration Errors

Monitoring

Check Database Health

Security Notes

Next Steps

​Overview

​What You’ll Need

​Deployment Options

​Option 1: Docker Compose (Recommended)

​Option 2: External PostgreSQL Server

​Step 1: Prepare PostgreSQL Database

​Create Database and User

​Verify Connection

​Step 2: Configure Environment Variables

​For Docker Deployments

​For Local Development

​Step 3: Start DeployStack

​Docker Compose

​Individual Containers

​Step 4: Complete Setup Wizard

​SSL/TLS Connection

​Enable SSL in PostgreSQL

​Production Considerations

​Connection Pooling

​Database Maintenance

​Backup Strategy

​Performance Tuning

​Troubleshooting

​”Connection refused” or “Cannot connect”

​“Authentication failed”

​“Database does not exist”

​“Permission denied”

​Migration Errors

​Monitoring

​Check Database Health

​Security Notes

​Next Steps

Overview

What You’ll Need

Deployment Options

Option 1: Docker Compose (Recommended)

Option 2: External PostgreSQL Server

Step 1: Prepare PostgreSQL Database

Create Database and User

Verify Connection

Step 2: Configure Environment Variables

For Docker Deployments

For Local Development

Step 3: Start DeployStack

Docker Compose

Individual Containers

Step 4: Complete Setup Wizard

SSL/TLS Connection

Enable SSL in PostgreSQL

Production Considerations

Connection Pooling

Database Maintenance

Backup Strategy

Performance Tuning

Troubleshooting

”Connection refused” or “Cannot connect”

“Authentication failed”

“Database does not exist”

“Permission denied”

Migration Errors

Monitoring

Check Database Health

Security Notes

Next Steps