monacousa-portal/deploy/README.md

# Monaco USA Portal - Standalone Production Deployment

This is a standalone deployment package for the Monaco USA Portal. No source code cloning required.

## Prerequisites

- Linux server (Ubuntu 22.04+ recommended)
- Docker Engine 24.0+
- Docker Compose v2.20+
- Domain name with DNS pointing to your server
- Ports 80 and 443 open

## Quick Start

### 1. Download the deployment files

Create a directory and download the deployment files:

```bash
mkdir -p /opt/monacousa
cd /opt/monacousa

# Download files from your deployment source
# Example: scp, git clone, or direct download
```

You need these files:
- `docker-compose.yml`
- `.env.example`
- `init.sql`
- `kong.yml.template`
- `setup.sh`

### 2. Configure environment

```bash
# Copy the example environment file
cp .env.example .env

# Edit with your settings
nano .env
```

At minimum, configure:
- `DOMAIN` - Your domain name (e.g., `portal.monacousa.org`)
- `ACME_EMAIL` - Email for SSL certificates
- SMTP settings (optional but recommended for emails)

### 3. Run setup script

```bash
# Make setup script executable
chmod +x setup.sh

# Run setup - this generates secrets and kong.yml
./setup.sh
```

The setup script will:
- Generate secure random passwords and JWT tokens
- Create `kong.yml` from the template with your API keys
- Validate your configuration

### 4. Start the services

```bash
docker compose up -d
```

### 5. Verify deployment

```bash
# Check all containers are running
docker compose ps

# Check database initialization
docker compose logs db

# Check for any errors
docker compose logs -f
```

### 6. Access the portal

Open `https://your-domain.com` in your browser. On first visit, you'll be redirected to `/setup` to create the initial admin account.

## Architecture

```
Internet
    │
    ├─► :80/:443 ──► Traefik (SSL/Reverse Proxy)
    │                    │
    │                    ├─► portal.domain.com ──► Portal (SvelteKit)
    │                    ├─► api.domain.com ──► Kong ──► Auth/REST/Storage
    │                    └─► studio.domain.com ──► Studio (Dashboard)
    │
Internal Network
    │
    ├─► Kong API Gateway
    │       ├─► Auth (GoTrue)
    │       ├─► REST (PostgREST)
    │       ├─► Storage API
    │       └─► Realtime
    │
    └─► PostgreSQL Database
```

## Files Description

| File | Purpose |
|------|---------|
| `docker-compose.yml` | All service definitions |
| `.env` | Your configuration (from .env.example) |
| `init.sql` | Database schema and migrations |
| `kong.yml.template` | API gateway config template |
| `kong.yml` | Generated API gateway config (created by setup.sh) |
| `setup.sh` | Setup script for secrets and validation |

## Management Commands

```bash
# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f

# View specific service logs
docker compose logs -f portal
docker compose logs -f db

# Restart a specific service
docker compose restart portal

# Check resource usage
docker stats

# Enter database shell
docker compose exec db psql -U postgres
```

## Updating

To update the portal to a new version:

```bash
# Pull the latest image
docker compose pull portal

# Restart the portal service
docker compose up -d portal
```

## Backup

### Database backup

```bash
# Create backup
docker compose exec db pg_dump -U postgres postgres > backup_$(date +%Y%m%d).sql

# Restore backup
docker compose exec -T db psql -U postgres postgres < backup_YYYYMMDD.sql
```

### Full backup (including storage)

```bash
# Stop services first for consistent backup
docker compose stop

# Backup volumes
docker run --rm -v monacousa_db-data:/data -v $(pwd):/backup alpine \
    tar czf /backup/db-data-backup.tar.gz -C /data .

docker run --rm -v monacousa_storage-data:/data -v $(pwd):/backup alpine \
    tar czf /backup/storage-data-backup.tar.gz -C /data .

# Start services
docker compose up -d
```

## Troubleshooting

### Containers not starting

```bash
# Check logs for errors
docker compose logs

# Check if ports are in use
netstat -tlnp | grep -E ':(80|443)'
```

### SSL certificate issues

```bash
# Check Traefik logs
docker compose logs traefik

# Verify DNS is pointing to server
dig +short your-domain.com
```

### Database connection errors

```bash
# Check database is healthy
docker compose ps db

# Check database logs
docker compose logs db

# Verify database is accepting connections
docker compose exec db pg_isready -U postgres
```

### API 401 Unauthorized errors

This usually means the API keys don't match. Run setup again:

```bash
./setup.sh
docker compose restart kong
```

### Portal not loading

```bash
# Check portal logs
docker compose logs portal

# Verify kong is routing correctly
docker compose exec portal wget -qO- http://kong:8000/rest/v1/ || echo "Kong not reachable"
```

## Security Recommendations

1. **Secure your .env file**
   ```bash
   chmod 600 .env
   ```

2. **Enable dashboard authentication**
   ```bash
   # Generate password hash
   htpasswd -nB admin
   # Add to .env as STUDIO_AUTH and TRAEFIK_DASHBOARD_AUTH
   ```

3. **Set up firewall**
   ```bash
   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw allow 22/tcp
   ufw enable
   ```

4. **Regular updates**
   - Keep Docker and host OS updated
   - Regularly pull latest portal images

5. **Monitor logs**
   - Set up log rotation (configured in docker-compose.yml)
   - Consider centralized logging (ELK, Loki, etc.)

## Support

For issues and questions:
- Check logs: `docker compose logs -f`
- GitHub issues: [Project Repository]
- Email: support@monacousa.org