Deploying Cuenti Docker Stack
Before generating anything, collect these variables from the user (ask only for what's missing):
<nombre-servicio> e.g. "portal-clientes"
<dominio> e.g. "portal.cuenti.co"
<puerto-servidor> e.g. 3001 (3000-series frontend, 8000-series backend)
<tag-version> SemVer, e.g. v1.2.0
<arquitectura> amd64 (default) or arm64 (AWS Graviton, confirm via `uname -m` → aarch64)
Once known, generate all template files below with values substituted, then give exact commands for the user's OS.
Progress:
- Step 1: Ask/confirm service variables (name, domain, port, tag, server arch)
- Step 2: Generate repo templates (.npmrc, pnpm-workspace.yaml, Dockerfile, nginx.conf)
- Step 3: Give build + push commands for user's OS (amd64 default, arm64 if Graviton)
- Step 4: Verify server port availability (
sudo ss -tulnp) - Step 5: Create project dir on server, write compose.yml, set up Nginx vhost
- Step 6: Explain update flow (
docker compose pull && up -d) and rollback
Step 1 — Initial Checklist
Never assume values. If any are missing, ask directly:
- Nombre del servicio (used for image name, server dir, log files)
- Dominio del proyecto (used for Nginx vhost + Cloudflare)
- Puerto en el servidor (check conflicts with
sudo ss -tulnp) - Tag de versión (SemVer, e.g. v1.0.0 — never use
latestin production) - Arquitectura del servidor EC2: estándar (
amd64) o Graviton (arm64, verify withuname -m→aarch64)
Step 2 — Repository Templates
.npmrc (root of repo):
@cuenti-dna:registry=https://package-manager.cuenti.co/
pnpm-workspace.yaml (root, pnpm v11+):
YAMLignoredBuiltDependencies: - core-js
Dockerfile (multi-stage):
DOCKERFILE# Etapa 1: Build FROM node:22-slim AS builder # node:22-slim (not alpine) — glibc required by @rspack/binding native Rust bindings WORKDIR /app COPY . . RUN \ corepack enable && \ (pnpm install --frozen-lockfile --ignore-scripts || pnpm install --ignore-scripts) && \ pnpm build # Etapa 2: Runtime FROM nginx:alpine AS runner COPY /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]
nginx.conf (container-internal, SPA fallback):
NGINXserver { listen 80; server_name localhost; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } }
Step 3 — Build & Push Commands
Default target: --platform linux/amd64. Skip only if server is confirmed ARM64 Graviton and build machine is Apple Silicon (native arch match).
macOS / Linux:
Bashdocker login -u cuentihub docker build --platform linux/amd64 \ --secret id=npmrc,src=$HOME/.npmrc \ -t cuentihub/<nombre-servicio>:<tag-version> . docker push cuentihub/<nombre-servicio>:<tag-version>
Windows PowerShell:
POWERSHELLdocker login -u cuentihub docker build --platform linux/amd64 ` --secret id=npmrc,src=$env:USERPROFILE\.npmrc ` -t cuentihub/<nombre-servicio>:<tag-version> . docker push cuentihub/<nombre-servicio>:<tag-version>
ARM64 Graviton exception: if server uname -m → aarch64:
- Build from Apple Silicon Mac: omit
--platform(native build) - Build from Windows/Linux x86: use
--platform linux/arm64
Step 4 — Server Port Check
Bashsudo ss -tulnp | grep :<puerto-servidor>
If occupied, pick next free port in the correct series (3000s frontend / 8000s backend) and confirm with user before continuing.
Step 5 — Server Setup
Project dir: ~/Proyectos/<nombre-servicio> (never apps/).
compose.yml:
YAMLservices: <nombre-servicio>: image: cuentihub/<nombre-servicio>:<tag-version> container_name: <nombre-servicio> restart: unless-stopped ports: - "127.0.0.1:<puerto-servidor>:80"
Nginx Virtual Host (/etc/nginx/sites-available/<dominio>.conf):
NGINXserver { listen 80; server_name <dominio>; access_log /var/log/nginx/<nombre-servicio>.access.log; error_log /var/log/nginx/<nombre-servicio>.error.log; location / { proxy_pass http://127.0.0.1:<puerto-servidor>; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }
Enable + reload:
Bashsudo ln -s /etc/nginx/sites-available/<dominio>.conf /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx
SSL/DNS is handled at the edge by Cloudflare — never assume Certbot locally; server Nginx only serves port 80.
Step 6 — Update & Rollback
Zero-downtime update (after pushing a new tag):
Bashcd ~/Proyectos/<nombre-servicio> # edit compose.yml image tag to new <tag-version> docker compose pull docker compose up -d
Docker replaces the old container automatically once the new image is healthy.
Rollback (5 seconds):
Bash# revert image tag in compose.yml to previous <tag-version> docker compose up -d
Example 1: Input: "Necesito desplegar el frontend de facturación, dominio facturas.cuenti.co, servidor estándar" Output: Ask for puerto and tag-version → generate .npmrc, pnpm-workspace.yaml, Dockerfile, nginx.conf → give amd64 build/push commands → compose.yml with port 3xxx → vhost for facturas.cuenti.co → update/rollback instructions.
Example 2: Input: "Actualiza el servicio portal-clientes a v2.1.0" Output: Skip template generation (repo unchanged), go straight to Step 3 build/push with new tag, then Step 6 update flow only.
- Always use
node:22-slimin the builder stage, neveralpine(glibc requirement for Rspack native bindings). - Always tag images with SemVer; never deploy
latestto production. - Default to
--platform linux/amd64; only diverge after explicit arch confirmation. - Keep SSL/DNS termination at Cloudflare; server Nginx is plaintext on port 80 only.
- Bind container ports to
127.0.0.1for defense-in-depth unless a specific reason requires public exposure.
- Don't use Vite/CRA assumptions — this stack is Rsbuild only, output is always
dist/. - Don't skip
--ignore-scriptsfallback in pnpm install — needed for non-interactive builds with Cuenti DNA. - Don't assume Certbot/local SSL — Cloudflare handles it; adding Certbot config will conflict.
- Don't create a generic
apps/directory on the server — always~/Proyectos/<nombre-servicio>. - Don't skip the port-availability check — collisions cause silent container start failures.