Self-Hosted Deployment

Deploy Msghub on your own infrastructure using Docker Compose. You own your data, your infrastructure, and your deployment.

Prerequisites

Docker Engine 20.10+
Docker Compose 1.29+
PostgreSQL 12+ (or use Docker)
Redis 6+ (or use Docker)
4+ CPU cores
8GB+ RAM
50GB+ storage

Quick Start

1. Clone Repository

git clone https://github.com/msghub/msghub-docker.git
cd msghub-docker

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env:

# Database
DATABASE_URL=postgresql://msghub:password@postgres:5432/msghub

# Redis
REDIS_URL=redis://redis:6379

# API
API_KEY=mk_live_your_secret_key_here
API_PORT=3000

# Domain
DOMAIN=your-domain.com

3. Start Services

docker-compose up -d

This starts:

Msghub API (port 3000)
PostgreSQL database
Redis cache
Nginx reverse proxy (port 80, 443)

4. Initialize Database

docker-compose exec api npm run migrate

5. Create Admin User

docker-compose exec api npm run create-admin

Follow prompts to create admin account.

6. Access Dashboard

Open https://your-domain.com in your browser.

Configuration

Environment Variables

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`REDIS_URL`	Redis connection string	`redis://host:6379`
`API_KEY`	API key for authentication	`mk_live_...`
`API_PORT`	API port	`3000`
`DOMAIN`	Your domain	`messaging.example.com`
`NODE_ENV`	Environment	`production`
`LOG_LEVEL`	Log level	`info`

Database Configuration

Use external PostgreSQL:

DATABASE_URL=postgresql://user:password@db.example.com:5432/msghub

Or use Docker:

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: msghub
      POSTGRES_USER: msghub
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

Redis Configuration

Use external Redis:

REDIS_URL=redis://redis.example.com:6379

Or use Docker:

services:
  redis:
    image: redis:7
    volumes:
      - redis_data:/data

SSL/TLS Setup

Let's Encrypt (Recommended)

docker-compose exec nginx certbot certonly \
  --webroot -w /var/www/certbot \
  -d your-domain.com

Nginx will automatically use the certificate.

Custom Certificate

Place certificate files in ./certs/:

certs/
  ├── your-domain.com.crt
  └── your-domain.com.key

Nginx will use them automatically.

Backup & Recovery

Backup Database

docker-compose exec postgres pg_dump -U msghub msghub > backup.sql

Backup Redis

docker-compose exec redis redis-cli BGSAVE
docker cp msghub_redis_1:/data/dump.rdb ./backup/

Restore Database

docker-compose exec -T postgres psql -U msghub msghub < backup.sql

Restore Redis

docker cp ./backup/dump.rdb msghub_redis_1:/data/
docker-compose exec redis redis-cli SHUTDOWN
docker-compose up -d redis

Scaling

Horizontal Scaling

Run multiple API instances:

services:
  api1:
    image: msghub/api:latest
    ports:
      - "3001:3000"
  api2:
    image: msghub/api:latest
    ports:
      - "3002:3000"
  api3:
    image: msghub/api:latest
    ports:
      - "3003:3000"
  
  nginx:
    # Load balance across api1, api2, api3

Database Scaling

Use read replicas:

# Primary database
DATABASE_URL=postgresql://user:pass@primary.db:5432/msghub

# Read replicas
READ_REPLICA_URLS=postgresql://user:pass@replica1.db:5432/msghub,postgresql://user:pass@replica2.db:5432/msghub

Monitoring

Health Check

curl https://your-domain.com/health

Response:

{
  "status": "healthy",
  "database": "connected",
  "redis": "connected"
}

Logs

View logs:

docker-compose logs -f api
docker-compose logs -f postgres
docker-compose logs -f redis

Metrics

Prometheus metrics available at:

https://your-domain.com/metrics

Upgrades

Update Msghub

# Pull latest image
docker pull msghub/api:latest

# Stop current instance
docker-compose down

# Update docker-compose.yml
# Change image version if needed

# Start new instance
docker-compose up -d

# Run migrations
docker-compose exec api npm run migrate

Troubleshooting

Database Connection Failed

# Check database is running
docker-compose ps postgres

# Check connection string
echo $DATABASE_URL

# Test connection
docker-compose exec api psql $DATABASE_URL

Redis Connection Failed

# Check Redis is running
docker-compose ps redis

# Test connection
docker-compose exec redis redis-cli ping

Port Already in Use

# Change port in docker-compose.yml
ports:
  - "8000:3000"  # Use 8000 instead of 3000

# Or kill process using port
lsof -i :3000
kill -9 <PID>

Security

Change Default Password

Log in as admin
Go Settings → Account
Change password

Enable 2FA

Go Settings → Security
Enable Two-Factor Authentication
Scan QR code with authenticator app

Firewall Rules

# Allow only HTTPS
ufw allow 443/tcp
ufw allow 80/tcp  # For Let's Encrypt renewal
ufw deny 3000/tcp  # Block direct API access

API Key Rotation

Go Settings → API Keys
Generate new key
Update applications
Delete old key