# Kapvoe Portfoli - Deployment i produccio

## Objectiu

Aquest projecte publica el portfolio d'ulleres Kapvoe al domini de produccio:

https://kapvoe-portfoli.treblarella.org

El flux correcte de treball es:

VS Code / PowerShell
-> git commit
-> git push
-> Gitea
-> Webhook
-> Coolify API
-> Docker build/deploy
-> Produccio

## Arquitectura

Internet
-> Cloudflare / DNS
-> Synology Reverse Proxy
-> Coolify a 192.168.1.80
-> Aplicacio Docker kapvoe-portfoli-web
-> PHP Apache
-> Apps Script / Google Sheets
-> Stripe Checkout

## Domini de produccio

Domini public:

https://kapvoe-portfoli.treblarella.org

Aquest domini apunta a Synology, i Synology fa reverse proxy cap a Coolify.

Configuracio recomanada del reverse proxy de Synology:

Origen:
- Protocol: HTTPS
- Host: kapvoe-portfoli.treblarella.org
- Port: 443

Desti:
- Protocol: HTTP
- Host: 192.168.1.80
- Port: 80

## Coolify

Aplicacio:

kapvoe-portfoli-web

Projecte:

Portfoli Ulleres / production

Build pack:

Dockerfile

Dockerfile location:

/Dockerfile

Domini configurat a Coolify:

https://kapvoe-portfoli.treblarella.org

## Git Source

Repositori Gitea:

Albert/portfoli-ulleres

URL SSH interna usada per Coolify:

ssh://git@10.0.0.1:22222/Albert/portfoli-ulleres.git

Branca de produccio:

main

## Deploy automatic

El deploy automatic funciona amb:

Gitea webhook -> Coolify API

Webhook a Gitea:

coolify-production-deploy

URL del webhook:

http://10.0.0.1:8000/api/v1/deploy?uuid=f11x5rza9srzo6pkgqcnl0ph&force=false

Metode:

POST

Content type:

application/json

Header d'autoritzacio:

Bearer <COOLIFY_API_TOKEN>

Important: el token no s'ha de guardar mai al repo.

## Configuracio Gitea necessaria

Gitea ha de permetre webhooks cap a la IP interna de Docker/Coolify.

Fitxer:

/data/gitea/conf/app.ini

Bloc necessari:

[webhook]
ALLOWED_HOST_LIST = external,private,loopback,10.0.0.1

Despres de modificar aquest fitxer cal reiniciar el contenidor de Gitea.

## Coolify API

A Coolify cal tenir API Access activat.

Allowed IPs recomanats:

10.0.0.0/8,127.0.0.1/32,192.168.1.0/24

Token recomanat:

gitea-production-deploy

Permisos minims:

- read
- deploy

## Persistent Storage

La carpeta de dades runtime es persistent:

/var/www/html/data

Aquesta carpeta conte:

- orders.csv
- analytics.log
- mail.log
- internal-notifications.log

Aquesta carpeta no ha d'anar al repositori Git.

.gitignore ha d'incloure:

data/
data/*.csv
data/*.log
data/*.json
data/*.txt

## Stripe

Checkout Stripe funciona amb:

/checkout/create-checkout-session.php

Webhook live de Stripe:

https://kapvoe-portfoli.treblarella.org/checkout/stripe-webhook.php

Event minim necessari:

checkout.session.completed

El webhook processa:

- payment_status = paid
- payment_intent_id
- stock update
- email client
- email admin

## Variables d'entorn critiques a Coolify

No guardar secrets al repo.

Variables importants:

STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
KAPVOE_PUBLIC_BASE_URL
KAPVOE_CATALOG_API_URL
KAPVOE_STOCK_SYNC_URL
KAPVOE_STOCK_SYNC_TOKEN
KAPVOE_ANALYTICS_SYNC_URL
KAPVOE_ANALYTICS_SYNC_TOKEN
KAPVOE_SMTP_HOST
KAPVOE_SMTP_PORT
KAPVOE_SMTP_ENCRYPTION
KAPVOE_SMTP_USERNAME
KAPVOE_SMTP_PASSWORD
KAPVOE_ADMIN_NOTIFICATION_EMAIL
KAPVOE_ADMIN_TOOLS_TOKEN

Valor intern recomanat per evitar problemes SSL dins del contenidor:

KAPVOE_CATALOG_API_URL=http://127.0.0.1/api/products.php

## Com desplegar canvis

Des del PC:

git status
git add .
git commit -m "Missatge del canvi"
git push

Despres anar a Coolify -> kapvoe-portfoli-web -> Deployments.

El deploy ha d'apareixer amb etiqueta:

API

No hauria de ser necessari premer Redeploy manualment.

## Com validar produccio

Productes:

https://kapvoe-portfoli.treblarella.org/api/products.php?refresh=1

Ha de retornar JSON amb:

"ok": true

I count amb el nombre de productes visibles.

Web:

https://kapvoe-portfoli.treblarella.org

Checkout:

Fer una prova amb producte de prova i verificar:

- Stripe checkout obre correctament
- Stripe webhook retorna 200
- orders.csv passa a paid
- stock_updated = 1
- customer_email_sent = 1
- admin_email_sent = 1

## Comprovar dades persistents al servidor

Al servidor Coolify:

CONTAINER=$(docker ps --format "{{.Names}}" | grep f11x5 | head -n 1)
docker exec "$CONTAINER" ls -la /var/www/html/data
docker exec "$CONTAINER" sh -c 'tail -n 5 /var/www/html/data/orders.csv'

## Notes importants de seguretat

S'han de rotar tots els secrets que s'hagin enganxat accidentalment en converses, logs o terminals compartits.

Secrets a rotar:

- Stripe secret key
- Stripe webhook secret
- SMTP password
- KAPVOE_STOCK_SYNC_TOKEN
- KAPVOE_ANALYTICS_SYNC_TOKEN
- KAPVOE_ADMIN_TOOLS_TOKEN
- Tokens interns de Gitea si s'han exposat
- Coolify API token si s'ha exposat

## Estat final validat

Validat:

- Web en produccio funcional
- Productes carregant
- Imatges carregant
- Stripe Checkout funcional
- Stripe webhook funcional
- Emails client i admin funcionals
- Persistent storage funcional
- Deploy automatic Gitea -> Coolify funcional