compor-academy/PORTAINER.md

Portainer deployment

Use docker-compose.yml as a Portainer Stack from this repository. It deploys the frontend, API, and PostgreSQL as one internal Docker network. Only the web container exposes a port; it proxies /api to the API container.

This is a Docker Swarm stack: Portainer pulls prebuilt API and web images from the Gitea Container Registry. It never builds Dockerfiles itself.

Gitea Actions registry secrets

Create these repository-level Action secrets in Gitea before pushing to main:

• REGISTRY_USERNAME: the Gitea username that owns a package-write token.
• REGISTRY_TOKEN: a Gitea personal access token for that user with package read/write permission.

The built-in Actions job token can be disabled or lack registry scope on self-hosted Gitea instances, so the image publishing job intentionally uses these explicit secrets.

Required Portainer environment variables

• POSTGRES_PASSWORD: a long, unique database password. Avoid characters that are not URL-safe because it is used in DATABASE_URL.
• JWT_SECRET: a unique random string of at least 32 characters.
• FRONTEND_ORIGIN: the exact public application URL, for example https://hub.example.com.
• SUPERADMIN_EMAIL: email address for the initial platform administrator.
• SUPERADMIN_PASSWORD: password for that administrator (at least 12 characters).
• AUTH_RATE_LIMIT_MAX and AUTH_RATE_LIMIT_WINDOW_SECONDS are optional login and public-auth throttling controls (defaults: 10 attempts per 900 seconds per source IP).

Optional variables:

• POSTGRES_DB (default compor_hub)
• POSTGRES_USER (default compor)
• WEB_PORT (default 8080)
• IMAGE_TAG (default latest; set a specific release tag when available)
• API_IMAGE and WEB_IMAGE only if the Gitea registry namespace differs from the defaults.

Before publishing

1. Push to main and wait for Gitea Actions to publish gitea.blyzer.com.br/blyzer/compor-academy-api:latest and gitea.blyzer.com.br/blyzer/compor-academy-web:latest.
2. Ensure the Portainer endpoint can pull from the Gitea Container Registry. If the images are private, add Gitea registry credentials to the endpoint/stack deployment configuration.
3. Deploy the stack with a temporary WEB_PORT and verify /api/v1/health through the public domain. A healthy response is {"status":"ok","database":"connected"}; Portainer also runs this check automatically for the API service.
4. Set SUPERADMIN_EMAIL, SUPERADMIN_PASSWORD, and optionally SUPERADMIN_NAME. The API creates or updates this superadmin automatically when it starts. Keep these values in Portainer only; changing the password and redeploying resets that account's password.
5. Place the web service behind HTTPS, normally through your existing reverse proxy (Traefik, Nginx Proxy Manager, or Cloudflare Tunnel), and set FRONTEND_ORIGIN to that HTTPS address.
6. Back up the compor_postgres_data volume before updates.

Do not expose port 5432 or port 3001 publicly.