Deployment

Deployment Guide - Portainer Setup

This guide walks you through deploying the TrueHour using Portainer with automated updates.

Prerequisites

✅ Portainer installed and accessible ✅ Docker Hub account (ryakel) ✅ GitHub repository access ✅ Nginx reverse proxy configured (optional for production)

---

Initial Deployment

Option 1: Deploy via Portainer Git Repository (Recommended)

1. Navigate to Stacks

   • In Portainer, go to Stacks → Add stack

2. Configure Stack

   • Name: flight-budget
   • Build method: Select Git Repository
   • Repository URL: https://github.com/ryakel/flight-budget
   • Repository reference: refs/heads/main
   • Compose path: docker-compose.yml

3. Environment Variables (optional)

   APP_PORT=8181
   TIMEZONE=UTC
   

4. Deploy

   • Click Deploy the stack
   • Wait for deployment to complete

5. Verify

   • Navigate to http://your-server:8181
   • You should see the TrueHour

Option 2: Deploy via Portainer Web Editor

1. Navigate to Stacks

   • In Portainer, go to Stacks → Add stack

2. Configure Stack

   • Name: flight-budget
   • Build method: Select Web editor

3. Paste Docker Compose

   • Copy contents from docker-compose.yml
   • Paste into the web editor

4. Set Environment Variables (optional)

   APP_PORT=8181
   TIMEZONE=UTC
   

5. Deploy

   • Click Deploy the stack

---

Setting Up Automated Updates

Step 1: Create Portainer Webhook

1. Access Your Stack

   • In Portainer, navigate to Stacks
   • Click on your flight-budget stack

2. Create Webhook

   • Scroll down to the Webhooks section
   • Click Add webhook

3. Configure Webhook

   • Service: Select flight-budget (or leave empty for entire stack)
   • Action: Select Repull image and redeploy

4. Copy Webhook URL

   • Click the webhook you just created
   • Copy the webhook URL
   • Format: https://your-portainer.com/api/webhooks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   • Keep this URL secure! Anyone with this URL can trigger your deployment

Step 2: Configure GitHub Secrets

1. Navigate to Repository Settings

   • Go to https://github.com/ryakel/flight-budget
   • Click Settings → Secrets and variables → Actions

2. Add Docker Hub Credentials

   • Click New repository secret
   • Name: DOCKER_USERNAME
   • Value: ryakel
   • Click Add secret

3. Add Docker Hub Token

   • Click New repository secret
   • Name: DOCKER_PASSWORD
   • Value: Your Docker Hub access token (create at https://hub.docker.com/settings/security)
   • Click Add secret

4. Add Portainer Webhook

   • Click New repository secret
   • Name: PORTAINER_WEBHOOK_URL
   • Value: The webhook URL you copied from Portainer
   • Click Add secret

Step 3: Verify Automated Workflow

Your repository now has two automated workflows:

1. Docker Build & Deploy (.github/workflows/docker-build.yml)

Triggers:

• Push to main branch
• Manual trigger via GitHub Actions UI

Steps:

1. Builds multi-architecture Docker image (amd64, arm64)
2. Pushes to Docker Hub (ryakel/flight-budget:latest)
3. Triggers Portainer webhook
4. Portainer automatically redeploys with new image

Test It:

# Make a small change and push
git add .
git commit -m "test: trigger automated deployment"
git push origin main

Monitor Progress:

1. GitHub: Actions tab → Watch the workflow run
2. Docker Hub: Check for new image push
3. Portainer: Watch stack redeploy automatically

2. Update CDN Dependencies (.github/workflows/update-dependencies.yml)

Triggers:

• Weekly schedule: Sundays at 2 AM UTC
• Manual trigger via GitHub Actions UI

Steps:

1. Downloads latest versions of JavaScript libraries
2. Creates a Pull Request if updates are found
3. Review and merge the PR to deploy updates

---

Deployment Flow Diagram

Developer pushes to main
         ↓
GitHub Actions triggered
         ↓
    Build Docker image
    (multi-arch: amd64, arm64)
         ↓
  Push to Docker Hub
  (ryakel/flight-budget:latest)
         ↓
  Trigger Portainer webhook
         ↓
Portainer pulls new image
         ↓
  Stack redeployed automatically
         ↓
      Live! 🎉

Total time: ~2-5 minutes from push to live deployment

---

Nginx Reverse Proxy Configuration

For production deployment with SSL:

Nginx Configuration

Create /etc/nginx/sites-available/flight-budget:

server {
    listen 80;
    server_name budget.yourdomain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name budget.yourdomain.com;

    # SSL certificates (managed by Certbot)
    ssl_certificate /etc/letsencrypt/live/budget.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/budget.yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Proxy to Docker container
    location / {
        proxy_pass http://localhost:8181;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Optional: Increase timeouts for large CSV uploads
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    # Health check endpoint
    location /health {
        proxy_pass http://localhost:8181/health;
        access_log off;
    }
}

Enable the site:

ln -s /etc/nginx/sites-available/flight-budget /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

SSL Certificate (Let's Encrypt)

# Install Certbot
apt install certbot python3-certbot-nginx

# Generate certificate
certbot --nginx -d budget.yourdomain.com

# Auto-renewal is configured automatically
# Test renewal:
certbot renew --dry-run

---

Maintenance

Manual Update

If you need to manually update the stack:

# Pull latest image
docker pull ryakel/flight-budget:latest

# Redeploy via Portainer UI or CLI
docker-compose up -d --force-recreate

View Logs

In Portainer:

1. Navigate to Containers
2. Click on flight-budget-app
3. Click Logs

Or via CLI:

docker logs -f flight-budget-app

Backup Persistent Data

Aircraft configurations are stored in a volume. To backup:

# Create backup directory
mkdir -p ~/backups

# Backup volume
docker run --rm \
  -v flight-budget_flight-budget-data:/data \
  -v ~/backups:/backup \
  alpine tar czf /backup/flight-budget-data-$(date +%Y%m%d).tar.gz -C /data .

Restore from Backup

# Restore volume
docker run --rm \
  -v flight-budget_flight-budget-data:/data \
  -v ~/backups:/backup \
  alpine tar xzf /backup/flight-budget-data-YYYYMMDD.tar.gz -C /data

---

Troubleshooting

Webhook Not Triggering

Check GitHub Actions logs:

1. Go to Actions tab in GitHub
2. Click on the latest workflow run
3. Check the "Trigger Portainer webhook" step

Common issues:

• PORTAINER_WEBHOOK_URL secret not set or incorrect
• Portainer webhook deleted or expired
• Network connectivity issues

Stack Not Updating

1. Verify webhook URL is correct in GitHub secrets
2. Check Portainer webhook exists in stack settings
3. Manually trigger update in Portainer:
   • Go to Stacks → flight-budget
   • Click Update the stack
   • Enable Re-pull image
   • Click Update

Port Already in Use

If port 8181 is already in use:

1. Edit .env file or Portainer environment variables
2. Change APP_PORT to another port (e.g., 8282)
3. Update your nginx proxy configuration
4. Redeploy the stack

---

Security Best Practices

✅ Keep webhook URL secret (it's in GitHub secrets, don't share it) ✅ Use SSL/TLS in production (Let's Encrypt) ✅ Restrict Portainer access with strong passwords ✅ Enable two-factor authentication on Docker Hub ✅ Regularly update the base image (automated via GitHub Actions) ✅ Monitor container logs for suspicious activity

---

Next Steps

1. ✅ Deploy stack in Portainer
2. ✅ Create and configure webhook
3. ✅ Add GitHub secrets
4. ✅ Test automated deployment
5. ✅ Configure nginx reverse proxy (production)
6. ✅ Set up SSL certificate
7. ⏭️ Fix aircraft persistence logic (see TODO)

---

Support

For issues:

• Check container logs: docker logs flight-budget-app
• Review GitHub Actions runs: Repository → Actions tab
• Verify webhook status in Portainer
• Check nginx logs: tail -f /var/log/nginx/error.log

Need help? Create an issue in the GitHub repository.