gohorsejobs/docs/DEVOPS.md

DevOps - GoHorseJobs (Development Environment)

Infraestrutura, CI/CD e deploy do projeto GoHorseJobs no servidor apolo.

Last Updated: 2026-01-03 Server: Apolo VPS Tech Stack: Podman, Systemd (Quadlet), Traefik, PostgreSQL (Local)

---

🏗️ Architecture Diagram

Simplified view of the container hierarchy, networking, and storage.

graph TD
    subgraph Host ["Apolo VPS (Host)"]
        
        subgraph FS ["File System (/mnt/data)"]
            EnvBE["/gohorsejobs/backend/.env"]
            EnvBO["/gohorsejobs/backoffice/.env"]
            EnvSE["/gohorsejobs/seeder-api/.env"]
            DBData[("postgres-general")]
        end

        subgraph Net ["Network: web_proxy"]
            Traefik("Traefik")
            
            subgraph App ["Application Containers"]
                BE["Backend API (:8521)"]
                BO["Backoffice (:3001)"]
                SE["Seeder API (:8080)"]
                FE["Frontend (:3000)"]
            end
            
            PG[("postgres-main (:5432)")]
        end
    end

    %% Ingress
    Internet((Internet)) --> Traefik
    
    %% Routing
    Traefik -- "dev.gohorsejobs.com" --> FE
    Traefik -- "api-tmp.gohorsejobs.com" --> BE
    Traefik -- "b-tmp.gohorsejobs.com" --> BO
    Traefik -- "seeder.gohorsejobs.com" --> SE

    %% Config Mounts
    EnvBE -.-> BE
    EnvBO -.-> BO
    EnvSE -.-> SE

    %% Data Persistence
    PG -.-> DBData

    %% Database Connections
    BE --> PG
    BO --> PG
    SE --> PG

    style PG fill:#336791,stroke:#fff,color:#fff
    style Traefik fill:#f5a623,stroke:#fff,color:#fff

---

💾 Storage & Persistence (/mnt/data)

All persistent data and configuration files are stored in /mnt/data on the host.

Host Path	Container Path	Purpose	Type
/mnt/data/gohorsejobs/backend/.env	(Injected Env)	Backend Config: Secrets, DB URL, Port settings.	File
/mnt/data/gohorsejobs/backoffice/.env	(Injected Env)	Backoffice Config: Secrets, DB URL.	File
/mnt/data/gohorsejobs/seeder-api/.env	(Injected Env)	Seeder Config: Secrets, DB URL.	File
/mnt/data/postgres-general	/var/lib/postgresql/data	Database Storage: Main storage for postgres-main container. Contains gohorsejobs_dev DB.	Directory

Backup Note: To backup the environment, ensure /mnt/data/gohorsejobs and /mnt/data/postgres-general are included in snapshots.

---

🌍 Service Maps & Networking

🚦 Traefik Routing

Services are exposed via Traefik labels defined in the Quadlet .container files.

Domain	Service	Internal Port	Host Port (Debug)
dev.gohorsejobs.com	gohorsejobs-frontend-dev	3000	8523
api-tmp.gohorsejobs.com	gohorsejobs-backend-dev	8521	8521
b-tmp.gohorsejobs.com	gohorsejobs-backoffice-dev	3001	-
seeder.gohorsejobs.com	gohorsejobs-seeder-dev	8080	8522

🛑 Security

• Backend/Seeder/Frontend expose ports to the Host (85xx) for debugging/direct access if needed.
• Backoffice is only accessible via Traefik (internal network).
• PostgreSQL is only accessible internally via web_proxy network (no host port binding).

---

🛠️ Operational Guide

1. View & Manage Configs

Configurations are not inside containers. Edit them on the host:

# Edit Backend Config
vim /mnt/data/gohorsejobs/backend/.env

# Apply changes
systemctl restart gohorsejobs-backend-dev

2. Full Environment Restart

To restart all GoHorseJobs related services (excluding Database):

systemctl restart gohorsejobs-backend-dev gohorsejobs-backoffice-dev gohorsejobs-seeder-dev gohorsejobs-frontend-dev

3. Database Access

Access the local database directly via the postgres-main container:

# Internal Connection
docker exec -it postgres-main psql -U yuki -d gohorsejobs_dev

---

🚀 Deployment Pipeline (Manual)

Current workflow uses Local Build -> Forgejo Registry -> Server Pull.

1. Build & Push (Local Machine)

# Login
podman login forgejo-gru.rede5.com.br

# Build
cd backend
podman build -t forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest .

# Push
podman push forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest

2. Deploy (On Apolo Server)

ssh root@apolo

# Pull new image
podman pull forgejo-gru.rede5.com.br/rede5/gohorsejobs-backend:latest

# Restart service (Systemd handles container recreation)
systemctl restart gohorsejobs-backend-dev