Deploy della Documentazione su Coolify con MkDocs e CodeCommit

Questa guida descrive come configurare e pubblicare il portale della documentazione di mdm_docs su Coolify dev (https://coolify.dev.bsqdev.uk), sincronizzato automaticamente con AWS CodeCommit tramite EventBridge.

---

1. Architettura del Servizio

flowchart LR
    DEV[git push su CodeCommit<br/>repository mdm_docs] --> EB[AWS EventBridge<br/>regola mdm-docs-deploy-dev]
    EB -- "POST /api/v1/deploy" --> AD[API Destination<br/>qalarm-coolify-dev-deploy]
    AD --> CO[Coolify Dev<br/>coolify.dev.bsqdev.uk]
    CO -- "git clone & docker build" --> MK[Container Nginx + MkDocs<br/>docs.dev.bsqdev.uk]
    MK -- "Serve HTML & Mermaid" --> BROWSER[Sistemisti e Operatori]

Hold "Ctrl" to enable pan & zoom

• Motore Documentale: Material for MkDocs (configurato in mkdocs.yml), con supporto nativo per diagrammi Mermaid, ricerca istantanea, tema Dark/Light e navigazione a schede.
• Runtime: Dockerfile multi-stage: compila i Markdown in file statici HTML/SVG e li serve con un'immagine nginx:alpine ultra-leggera (< 15 MB di RAM).
• Dominio e SSL: Gestiti automaticamente dal reverse proxy Traefik di Coolify con certificato Let's Encrypt gratuito.
• Aggiornamento Automatico: A ogni git push sul branch main, EventBridge notifica Coolify che ricostruisce il container e aggiorna il sito live senza intervento manuale.

---

2. Passo 1: Configurazione dell'Applicazione su Coolify

1. Accedere al pannello Coolify dev: https://coolify.dev.bsqdev.uk.
2. Selezionare il progetto (es. MDM o creare un nuovo progetto/ambiente dedicato).
3. Cliccare su + New Resource → Git Repository (Private / Custom).
4. Impostazioni Repository:
5. Se si usa la chiave SSH CodeCommit: ssh://<SSH_KEY_ID>@git-codecommit.eu-west-1.amazonaws.com/v1/repos/mdm_docs
6. Se si usano le credenziali HTTPS Git: https://<GIT_USER>:<GIT_PASSWORD>@git-codecommit.eu-west-1.amazonaws.com/v1/repos/mdm_docs
7. Branch: main.
8. Configurazione di Build:
9. Build Pack: Selezionare Dockerfile (Coolify userà il Dockerfile presente nella radice di mdm_docs).
10. Port: 3000. Il Dockerfile copia nginx.conf nella configurazione di Nginx: il server ascolta sulla porta 3000 sia su IPv4 sia su IPv6, in accordo con EXPOSE 3000 e con il setup Coolify esistente.
11. Domains (FQDN): Inserire il dominio desiderato, ad esempio https://docs.dev.bsqdev.uk.
12. Cliccare su Deploy per eseguire la prima compilazione.
13. Al termine, copiare l'UUID dell'applicazione (visibile nella barra degli indirizzi del browser, es. https://coolify.dev.bsqdev.uk/.../application/<UUID>).

---

3. Passo 2: Configurazione del Trigger Automatico su AWS (EventBridge)

Per fare in modo che a ogni git push su CodeCommit la documentazione si aggiorni da sola, si riusa l'API Destination qalarm-coolify-dev-deploy già attiva su AWS (account 407138933921, regione eu-west-1).

A. Creazione della Regola EventBridge

Eseguire da terminale con AWS CLI:

aws events put-rule \
  --name mdm-docs-deploy-dev \
  --description "Deploy automatico di mdm_docs su Coolify dev ad ogni push su main" \
  --region eu-west-1 \
  --event-pattern '{
    "source": ["aws.codecommit"],
    "detail-type": ["CodeCommit Repository State Change"],
    "resources": ["arn:aws:codecommit:eu-west-1:407138933921:mdm_docs"],
    "detail": {
      "event": ["referenceUpdated", "referenceCreated"],
      "referenceType": ["branch"],
      "referenceName": ["main"]
    }
  }'

B. Collegamento del Target con l'UUID di Coolify

Creare il file temporaneo target-docs.json (sostituire <UUID_RISORSA_COOLIFY> con l'UUID ottenuto al Passo 1):

[
  {
    "Id": "coolify-docs-deploy",
    "Arn": "arn:aws:events:eu-west-1:407138933921:api-destination/qalarm-coolify-dev-deploy/37a21a64-c726-42b5-b600-2f28a4141d42",
    "RoleArn": "arn:aws:iam::407138933921:role/service-role/Amazon_EventBridge_Invoke_Api_Destination_1696033803",
    "Input": "{\"uuid\": \"<UUID_RISORSA_COOLIFY>\", \"force\": false}"
  }
]

Applicare il target alla regola:

aws events put-targets \
  --rule mdm-docs-deploy-dev \
  --region eu-west-1 \
  --targets file://target-docs.json

---

4. Verifica e Collaudo

1. Eseguire un commit e push sul branch main di mdm_docs:

   git add .
   git commit -m "docs: setup mkdocs e guida sistemista"
   git push origin main
   

2. In Coolify, nella schermata Deployments della risorsa, apparirà automaticamente il nuovo job di build.
3. Al termine (circa 30-45 secondi), aprire l'URL configurato (es. https://docs.dev.bsqdev.uk) per verificare la navigazione a schede, i diagrammi Mermaid renderizzati e la ricerca full-text.