# ☁️ DevOps & Infrastructure - GoHorseJobs

This document maps out the comprehensive DevOps lifecycle, the server topologies, the container orchestrations, and CI/CD operations powering GoHorseJobs.

---

## 🏗️ Architecture Diagrams

### 1. Global Infrastructure Overview (DEV / HML Environments)
A look into how our development environment handles requests through Cloudflare down to the Coolify-managed `Redbull` VPS.

```mermaid
graph TB
    subgraph Clients ["Public Clients"]
        Browser["Web Browser / Mobile App"]
    end

    subgraph CF ["Cloudflare (DNS + Proxy + CDN)"]
        DNS["DNS Zone: gohorsejobs.com"]
        WAF["Web Application Firewall (WAF)"]
    end

    subgraph Redbull ["Redbull VPS (185.194.141.70) — Ubuntu"]
        TraefikR("Traefik (Reverse Proxy + Let's Encrypt)")
        
        subgraph CoolifyApps ["Coolify Application Containers"]
            FE_C["Frontend (Next.js)"]
            BE_C["Backend API (Go)"]
            BO_C["Backoffice (NestJS)"]
            SE_C["Seeder API (Node.js)"]
        end

        subgraph CoolifyData ["Coolify Data Containers"]
            PG_C[("PostgreSQL 16")]
            MQ_C["LavinMQ / RabbitMQ"]
            Redis_C[("Redis (Caching/Sessions)")]
        end
    end

    Browser -->|HTTPS| DNS
    DNS --> WAF
    WAF -->|Proxy/Cache| TraefikR
    TraefikR -->|local.gohorsejobs.com| FE_C
    TraefikR -->|api-local.gohorsejobs.com| BE_C
    TraefikR -->|b-local.gohorsejobs.com| BO_C

    FE_C -.->|REST /api/v1| BE_C
    BO_C -.->|Queries| PG_C
    BE_C <-->|Queries| PG_C
    BE_C -.->|AMQP Pub| MQ_C
    MQ_C -.->|AMQP Sub| BO_C
```

### 2. CI/CD Operations (Forgejo -> VPS)
How code travels from a `git push` on `dev` to the live container.

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub (Origin)
    participant Forgejo as Pipe / Forgejo (CI)
    participant Coolify as Coolify Webhook
    participant VPS as Redbull (VPS)

    Dev->>Git: git push origin dev
    Dev->>Forgejo: git push pipe dev
    Note over Forgejo: Trigger Action (.forgejo/workflows/)
    Forgejo->>Coolify: POST Deploy Webhook
    Coolify-->>VPS: Fetch latest dev branch
    Note over VPS: Coolify builds Nixpacks/Dockerfile
    Coolify-->>VPS: docker stop <old_containers>
    Coolify-->>VPS: docker run <new_containers>
    Coolify-->>Forgejo: Deployment Success
    Forgejo-->>Dev: Pipeline Green/Passed
```

---

## 🛠️ Environments Topology

| Environment | Branch | Use Case | Server Host | Reverse Proxy | Config Manager | Domains |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Local (Host)** | N/A | Developer Sandbox | Laptop / PC | None | `start.sh` (Bare metal) | `localhost:8963` |
| **DEV** | `dev` | Continuous Integration | `Redbull` VPS | Traefik | Coolify v4 | `local.`, `api-local.`, `b-local.` |
| **HML** | `hml` | QA / Staging Testing | `Apolo` VPS | Nginx proxy | Podman (Quadlet) | `hml.`, `api-hml.`, `b-hml.` |
| **PRD** | `main` | Production Live | `Zeus`/`Poseidon` | Traefik Ingress | Kubernetes (K3s) | `gohorsejobs.com`, `api.` |

---

## 🔧 Coolify Instance (Redbull) 

The `dev` branch automatically mirrors to the Redbull server (185.194.141.70) managed by Coolify. 
*   **Coolify Interface:** `https://redbull.rede5.com.br`
*   **GitHub Integration:** Relies on an SSH deployment key injected into the Forgejo actions.

### Container Rules
*   Never manually `docker run` on Redbull. Use the Coolify interface to add environment variables or alter build commands.
*   **Secrets:** Managed via Coolify Environment Variables. (e.g., `PASSWORD_PEPPER`, `JWT_SECRET`).

---

## 💡 Troubleshooting & Known Faultlines

### 1. `Invalid Credentials` Right After DB Seed 
If the Backend Go server complains about invalid passwords right after you run `npm run seed`:
1. Check the `PASSWORD_PEPPER` inside the Coolify instance for the `seeder-api`.
2. It **must exactly match** the pepper configured for the Backend API.
3. If they matched, rerun `npm run seed` via the Coolify interface to force hash recalculation over the raw DB rows.

### 2. Out of Memory (OOMKilled) on Build
Node.js (for Next.js and NestJS) and Go can eat a lot of RAM during concurrent Coolify builds.
*   **Fix:** Ensure the Server Actions inside Coolify are set to stagger deployments, preventing out-of-memory cascading crashes on Redbull.

### 3. SSH Connectivity
```bash
# Connecting to Redbull
ssh root@185.194.141.70 -p 22
```
If access is denied, ensure your local public key is registered in `~/.ssh/authorized_keys` or injected via the VPS admin panel.