Skip to content

Deployment Guide

Complete guide to deploying the Portugal Odyssey platform across different environments.

Overview

The platform supports deployment to three environments: - Development - Local development - Qualification - Staging/testing environment - Production - Live production environment

Quick Start

Development Deployment

make dev

Qualification Deployment

make deploy-vps-qual SERVICE=service-name TAG=latest

Production Deployment

make deploy-vps-prod SERVICE=service-name TAG=latest

Deployment Methods

1. Local Development

Purpose: Local development with hot reload

Commands: 

make dev          # Start development stack
make dev-build    # Rebuild and start
make dev-logs     # View logs
make dev-stop     # Stop services

See: Local Setup Guide

2. VPS Deployment (SSH-based)

Purpose: Deploy to remote VPS servers

Prerequisites: - .env.deploy file configured (see .env.deploy.example) - SSH access to VPS - Docker installed on VPS

Commands: 

# Qualification
make deploy-vps-qual SERVICE=service-name TAG=latest

# Production
make deploy-vps-prod SERVICE=service-name TAG=latest

See: VPS Deployment Guide

3. CI/CD Pipeline

Purpose: Automated deployment via GitLab CI/CD

Triggers: - Push to main → Automatic qualification deployment - Manual trigger → Production deployment (requires approval)

See: CI/CD Pipeline Guide

Environment Configuration

Each environment requires specific configuration:

  • Development: .env.dev
  • Qualification: .env.qual (on VPS)
  • Production: .env.prod (on VPS)

See: Environment Configuration

Deployment Workflow

Standard Deployment

  1. Build Images 

    make build-push SERVICE=service-name ENV=qual TAG=latest

  2. Deploy to Qualification 

    make deploy-vps-qual SERVICE=service-name TAG=latest

  3. Verify Deployment 

    make health-check-qual

  4. Deploy to Production (after qualification testing) 

    make deploy-vps-prod SERVICE=service-name TAG=latest

Rollback Procedure

  1. Identify Previous Tag 

    # Check Git history or registry tags

  2. Deploy Previous Version 

    make deploy-vps-qual SERVICE=service-name TAG=previous-tag

  3. Verify Rollback 

    make health-check-qual

Health Checks

Qualification

make health-check-qual

Production

make health-check-prod

Monitoring Deployments

View Logs

# Qualification
make qual-logs

# Production
make prod-logs

# Specific service
ssh root@qual.portugalodyssey.pt "docker logs po-service-name-qual --tail=50"

Check Service Status

ssh root@qual.portugalodyssey.pt "docker ps | grep qual"

Troubleshooting

Deployment Failures

  1. Check SSH Access 

    ssh root@qual.portugalodyssey.pt

  2. Verify Environment File 

    ssh root@qual.portugalodyssey.pt "ls -la /opt/po-platform/.env.qual"

  3. Check Docker Resources 

    ssh root@qual.portugalodyssey.pt "docker system df"

Service Not Starting

  1. Check Logs 

    ssh root@qual.portugalodyssey.pt "docker logs po-service-name-qual"

  2. Verify Environment Variables 

    ssh root@qual.portugalodyssey.pt "docker exec po-service-name-qual env | grep KEY"

  3. Check Dependencies 

    ssh root@qual.portugalodyssey.pt "docker ps | grep postgres"

Best Practices

  1. Always test in qualification first
  2. Monitor deployments - Watch logs during deployment
  3. Verify health checks - Ensure services are healthy after deployment
  4. Keep backups - Backup databases before major deployments
  5. Document changes - Note any configuration changes

See Also