5.6 KiB

Raw Blame History

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:

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

# 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

# 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

docker compose up -d

5. Verify deployment

# 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

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

# Pull the latest image
docker compose pull portal

# Restart the portal service
docker compose up -d portal

Backup

Database backup

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

# 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

# Check logs for errors
docker compose logs

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

SSL certificate issues

# Check Traefik logs
docker compose logs traefik

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

Database connection errors

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

./setup.sh
docker compose restart kong

Portal not loading

# 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

Secure your .env file
```
chmod 600 .env
```

Enable dashboard authentication

# Generate password hash
htpasswd -nB admin
# Add to .env as STUDIO_AUTH and TRAEFIK_DASHBOARD_AUTH

Set up firewall

ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 22/tcp
ufw enable

Regular updates
- Keep Docker and host OS updated
- Regularly pull latest portal images
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

5.6 KiB Raw Blame History