Makefile Commands Reference¶

Complete reference for all Makefile commands available in the Portugal Odyssey platform.

Development Commands¶

`make dev`¶

Start the full development environment (infrastructure + services + frontend).

make dev

What it does: - Creates Docker networks if needed - Starts all development services - Exposes services via Traefik

Access points: - Public frontend: https://public-fo-dev.portugalodyssey.pt - Strapi CMS: https://cms-dev.portugalodyssey.pt - API Gateway: https://api-dev.portugalodyssey.pt

`make dev-build`¶

Build and start development environment (rebuilds images).

make dev-build

`make dev-build-no-cache`¶

Build without using cache (clean build).

make dev-build-no-cache

`make dev-logs`¶

View logs from all development services.

make dev-logs

`make dev-stop`¶

Stop all development services.

make dev-stop

Qualification Commands¶

`make qual`¶

Start qualification environment.

make qual

`make qual-build`¶

Build and start qualification environment.

make qual-build

`make qual-build-no-cache`¶

Build qualification environment without cache.

make qual-build-no-cache

`make qual-logs`¶

View qualification environment logs.

make qual-logs

`make qual-stop`¶

Stop qualification environment.

make qual-stop

`make health-check-qual`¶

Run health checks for qualification environment.

make health-check-qual

Production Commands¶

`make prod`¶

Start production environment.

make prod

Warning: Only use with proper production configuration and secrets.

`make prod-build`¶

Build and start production environment (force rebuild).

make prod-build

`make prod-logs`¶

View production environment logs.

make prod-logs

`make prod-stop`¶

Stop production environment.

make prod-stop

`make health-check-prod`¶

Run health checks for production environment.

make health-check-prod

`make ssh-prod`¶

SSH into production server.

make ssh-prod

Infrastructure Commands¶

`make networks`¶

Create/verify Docker networks.

make networks

Creates: - po-traefik-public (development) - po-postgres-network - po-redis-network - po-rabbitmq-network - po-internal (development) - traefik-public (qual/prod) - po-shared-network (qual/prod) - po-internal-qual / po-internal-prod

Note: Traefik network must exist externally for qual/prod.

`make traefik-check`¶

Verify Traefik network exists.

make traefik-check

`make infrastructure`¶

Start only infrastructure services (Postgres, Redis, RabbitMQ, etc.).

make infrastructure

Maintenance Commands¶

`make clean`¶

Clean up containers, networks, and volumes for current environment.

make clean

`make clean-all`¶

Clean everything including images.

make clean-all

`make clean-all-force`¶

Force clean everything (use with caution).

make clean-all-force

`make logs ENV=dev`¶

Show logs for specific environment.

make logs ENV=dev    # Development
make logs ENV=qual   # Qualification
make logs ENV=prod   # Production

`make status`¶

Show status of all services.

make status

`make health`¶

Check health of Traefik and services.

make health

Backup & Restore¶

`make backup ENV=qual`¶

Backup databases and volumes for environment.

make backup ENV=qual
make backup ENV=prod

`make restore ENV=qual`¶

List available backups for restore.

make restore ENV=qual

`make restore-date ENV=qual DATE=YYYYMMDD_HHMMSS`¶

Restore from specific backup.

make restore-date ENV=qual DATE=20251125_120000

Smoke Tests¶

`make smoke-gateway`¶

Run API Gateway smoke test.

make smoke-gateway

`make smoke-user`¶

Run User Management smoke test (requires TOKEN).

TOKEN=your-token make smoke-user

`make smoke-all`¶

Run both smoke tests.

make smoke-all

Image Management¶

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

Build and push Docker image(s) to registry.

# Build and push all services
make build-push

# Build and push specific service
make build-push SERVICE=notification-service

# Build and push with specific tag
make build-push SERVICE=notification-service TAG=v1.2.3

# Build for specific environment
make build-push SERVICE=notification-service ENV=prod

Credentials: Uses .env.deploy file (copy from .env.deploy.example)

VPS Deployment¶

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

Deploy service(s) to qualification VPS.

# Deploy all services
make deploy-vps-qual

# Deploy specific service
make deploy-vps-qual SERVICE=notification-service

# Deploy with specific tag
make deploy-vps-qual SERVICE=notification-service TAG=v1.2.3

Credentials: Uses .env.deploy file

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

Deploy service(s) to production VPS.

make deploy-vps-prod SERVICE=notification-service TAG=v1.2.3

Warning: Production deployment requires extra caution.

Quick Deployment (Script-based)¶

`make secrets`¶

Generate environment secrets.

make secrets

`make stop-shared`¶

Stop shared infrastructure.

make stop-shared

`make deploy-dev`¶

Quick deploy development environment (local). Alias for make dev.

make deploy-dev

Retired: `make deploy-{shared,qual,prod}`¶

Removed in Riff #50 (2026-04-30). They wrapped infrastructure/scripts/ci-deploy.sh (also deleted) which used the 5-month-stale infrastructure/compose/.env.{qualification,production} env files instead of the canonical CI path's /opt/po-platform/.env.qual on the VPS. Anyone running them after 2025-11 would have deployed with stale Stripe / AWS / OpenAI / SMTP keys.

The current deploy paths:

Qual: push to main triggers GitLab CI auto-deploy via .gitlab-ci/infrastructure.yml's ssh_deploy_template, which uses /opt/po-platform/.env.qual and runs migrate.sh before docker compose up -d.
Prod: manual GitLab CI job (deploy-prod, gated). See Riff #10 for the prod first-deployment cutover playbook.
Hotfix without rebuild: make remote-restart-{qual,prod} SERVICE=… or make remote-pull-{qual,prod} — both use the canonical .env.qual / .env.prod paths.

Environment Variables¶

Makefile respects these environment variables:

ENV - Environment (dev, qual, prod)
SERVICE - Service name for targeted operations
TAG - Docker image tag
TOKEN - Authentication token for smoke tests

Examples¶

Complete Development Workflow¶

# First time setup
make networks
make dev-build

# Daily development
make dev
make dev-logs

# Stop when done
make dev-stop

Deploying a Service Update¶

# Build and push image
make build-push SERVICE=notification-service TAG=latest

# Deploy to qualification
make deploy-vps-qual SERVICE=notification-service TAG=latest

# Verify deployment
make health-check-qual

Production Deployment¶

# Build production image
make build-push SERVICE=notification-service ENV=prod TAG=v1.2.3

# Deploy to production
make deploy-vps-prod SERVICE=notification-service TAG=v1.2.3

# Health check
make health-check-prod

Makefile Commands Reference¶

Development Commands¶

make dev¶

make dev-build¶

make dev-build-no-cache¶

make dev-logs¶

make dev-stop¶

Qualification Commands¶

make qual¶

make qual-build¶

make qual-build-no-cache¶

make qual-logs¶

make qual-stop¶

make health-check-qual¶

Production Commands¶

make prod¶

make prod-build¶

make prod-logs¶

make prod-stop¶

make health-check-prod¶

make ssh-prod¶

Infrastructure Commands¶

make networks¶

make traefik-check¶

make infrastructure¶