hilingin/deployments/README.md

# 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:

```bash
cd deployments
cp .env.example .env
```

Edit `.env` and set the following required variables:

```bash
# 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

```bash
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:

```bash
docker-compose ps
```

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

View logs:

```bash
# 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:

```bash
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:

```yaml
# 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:

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

## Management Commands

### Stop all services
```bash
docker-compose down
```

### Stop and remove volumes (WARNING: Deletes data)
```bash
docker-compose down -v
```

### Restart a specific service
```bash
docker-compose restart backend
```

### View resource usage
```bash
docker stats
```

### Rebuild a specific service
```bash
docker-compose up -d --build backend
```

### Access service shell
```bash
docker-compose exec backend sh
docker-compose exec postgres psql -U postgres -d hiling
```

## Backup and Restore

### Database Backup

```bash
# 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.

```bash
# 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:
```bash
docker-compose logs <service-name>
```

### Database connection issues

Ensure PostgreSQL is healthy:
```bash
docker-compose ps postgres
docker-compose logs postgres
```

Test connection:
```bash
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:
```bash
lsof -i :8888  # or any conflicting port
```

Change ports in `.env` file.

### Out of disk space

Check Docker disk usage:
```bash
docker system df
```

Clean up:
```bash
docker system prune -a
```

### Reset everything

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

## Monitoring

### Health Checks

All services have health checks configured. Check status:

```bash
docker-compose ps
```

### Logs

Centralized logging with Docker:

```bash
# 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:

```bash
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

```bash
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]