hilingin/deployments

Hiling Production Deployment Guide

This directory contains all necessary files for deploying the Hiling application stack to production using Docker Compose.

Architecture

The application consists of 5 services:

1. PostgreSQL - Main database
2. Meilisearch - Search engine
3. Backend - Go API server (hiling_go)
4. OpenGraph - Deno-based OpenGraph service
5. Frontend - Preact/React frontend served by Nginx

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2.0+
• At least 2GB RAM
• 10GB free disk space

Quick Start

1. Configuration

Copy the environment template and configure it:

cd deployments
cp .env.example .env

Edit .env and set the following required variables:

# REQUIRED: Set a strong password for PostgreSQL
DB_PASSWORD=your_secure_password_here

# REQUIRED: Set a 32-character secret key for JWT tokens
TOKEN_SYMMETRIC_KEY=your_32_character_secret_key_here

# REQUIRED: Set a master key for Meilisearch
MEILI_MASTER_KEY=your_secure_meilisearch_master_key

2. Build and Start Services

docker-compose up -d --build

This will:

• Build all custom Docker images
• Start all services in the correct order
• Wait for health checks to pass
• Run in detached mode

3. Verify Deployment

Check service status:

docker-compose ps

All services should show as "Up" or "healthy".

View logs:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend

4. Database Initialization

If this is a fresh deployment, you may need to run database migrations:

docker-compose exec backend ./main migrate

(Adjust the command based on your migration setup)

Service Endpoints

Once deployed, services are accessible at:

• Frontend: http://localhost:80
• Backend API: http://localhost:8888
• OpenGraph Service: http://localhost:1234
• Meilisearch: http://localhost:7700
• PostgreSQL: localhost:5432

Configuration Reference

Environment Variables

Database

• DB_USERNAME - PostgreSQL username (default: postgres)
• DB_PASSWORD - PostgreSQL password (required)
• DB_NAME - Database name (default: hiling)
• DB_PORT - External PostgreSQL port (default: 5432)

Backend

• BACKEND_PORT - Backend API external port (default: 8888)
• TOKEN_SYMMETRIC_KEY - JWT signing key (required, 32 chars)
• TOKEN_DURATION - Token validity period (default: 720h)
• COOKIE_DURATION - Cookie duration in seconds (default: 86400)
• REFRESH_TOKEN_DURATION - Refresh token duration (default: 720h)

Meilisearch

• MEILI_MASTER_KEY - Meilisearch master key (required)
• MEILI_PORT - External Meilisearch port (default: 7700)

OpenGraph

• OPENGRAPH_PORT - OpenGraph service port (default: 1234)

Frontend

• FRONTEND_PORT - Frontend external port (default: 80)

Production Hardening

Security Checklist

• Change all default passwords
• Use strong, randomly generated keys
• Configure firewall rules to restrict access
• Enable HTTPS with reverse proxy (Nginx/Caddy)
• Set up database backups
• Configure log rotation
• Review and restrict exposed ports
• Enable Docker security scanning
• Set resource limits for containers

Recommended: Add Reverse Proxy

For production, add a reverse proxy like Nginx or Caddy in front of the services:

# Add to docker-compose.yml
  nginx-proxy:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx-proxy.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - frontend
      - backend

Resource Limits

Add resource limits to prevent containers from consuming too much:

services:
  backend:
    # ... existing config
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Management Commands

Stop all services

docker-compose down

Stop and remove volumes (WARNING: Deletes data)

docker-compose down -v

Restart a specific service

docker-compose restart backend

View resource usage

docker stats

Rebuild a specific service

docker-compose up -d --build backend

Access service shell

docker-compose exec backend sh
docker-compose exec postgres psql -U postgres -d hiling

Backup and Restore

Database Backup

# Backup
docker-compose exec -T postgres pg_dump -U postgres hiling > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore
docker-compose exec -T postgres psql -U postgres hiling < backup_20260321_120000.sql

Meilisearch Backup

Meilisearch data is stored in the meilisearch_data volume.

# Create backup of volume
docker run --rm -v deployments_meilisearch_data:/data -v $(pwd):/backup alpine tar czf /backup/meilisearch_backup.tar.gz -C /data .

# Restore
docker run --rm -v deployments_meilisearch_data:/data -v $(pwd):/backup alpine tar xzf /backup/meilisearch_backup.tar.gz -C /data

Troubleshooting

Service won't start

Check logs:

docker-compose logs <service-name>

Database connection issues

Ensure PostgreSQL is healthy:

docker-compose ps postgres
docker-compose logs postgres

Test connection:

docker-compose exec postgres psql -U postgres -d hiling -c "SELECT 1"

Port conflicts

If you get port binding errors, check what's using the port:

lsof -i :8888  # or any conflicting port

Change ports in .env file.

Out of disk space

Check Docker disk usage:

docker system df

Clean up:

docker system prune -a

Reset everything

docker-compose down -v
docker system prune -a
docker-compose up -d --build

Monitoring

Health Checks

All services have health checks configured. Check status:

docker-compose ps

Logs

Centralized logging with Docker:

# Follow all logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific time range
docker-compose logs --since 30m

Metrics

For production monitoring, consider adding:

• Prometheus for metrics
• Grafana for visualization
• Loki for log aggregation

Scaling

To run multiple instances of a service:

docker-compose up -d --scale backend=3

Note: You'll need a load balancer (like Nginx) to distribute traffic.

Updates and Maintenance

Updating Services

1. Pull latest code
2. Rebuild images: docker-compose build
3. Restart services: docker-compose up -d

Rolling Updates

For zero-downtime updates:

1. Scale up new version
2. Wait for health check
3. Remove old version

docker-compose up -d --scale backend=2 --no-recreate
# Wait for new instance to be healthy
docker-compose up -d --scale backend=1

Support

For issues and questions:

• Check logs: docker-compose logs
• Review configuration in .env
• Ensure all required environment variables are set
• Verify Docker and Docker Compose versions

License

[Your License Here]