From dd87b006858d32399c43d57ffd8d1ccac0db0436 Mon Sep 17 00:00:00 2001 From: Albert Date: Fri, 1 May 2026 00:43:30 +0200 Subject: [PATCH] Document production deployment pipeline --- deploy-test.txt | 1 - docs/DEPLOYMENT.md | 296 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 296 insertions(+), 1 deletion(-) delete mode 100644 deploy-test.txt create mode 100644 docs/DEPLOYMENT.md diff --git a/deploy-test.txt b/deploy-test.txt deleted file mode 100644 index 7c045e1..0000000 --- a/deploy-test.txt +++ /dev/null @@ -1 +0,0 @@ -deploy-test final 20260501-003635 diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..bb37f12 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,296 @@ +# 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 + +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