FastApp Engine (lead-nuxt)

Nuxt 4 app for FastApp Engine. This repository now includes both Docker development and production deployment flows.

Deployment Target (Current)

• Frontend domain: https://creator.fastapp.cloud
• Nuxt app: Docker container lead-nuxt-app
• Backend API (kept external): https://core.fastapp.cloud
• Reverse proxy: Nginx on VPS

Docker Files in This Repo

• Dockerfile: development image (nuxt dev)
• Dockerfile.prod: production build and runtime (node .output/server/index.mjs)
• docker-compose.prod.yml: production container settings and host port bindings
• DOCKER_RUN.md: local dev run commands

Required Runtime Environment

Set these in .env (or via environment overrides):

DATABASE_URL=postgresql://...
DIRECT_URL=postgresql://...
NUXT_PUBLIC_API_BASE_URL=https://core.fastapp.cloud
NUXT_PUBLIC_SOCKET_URL=/
SOCKET_IO_PORT=3001

Important: Prisma requires DATABASE_URL and DIRECT_URL to start with postgresql:// (or postgres://).

Local Docker (Development)

Run from g:\FastApp:

docker build -t fastapp-nuxt ./lead-nuxt
docker run -d --name lead-nuxt -p 3000:3000 -p 3001:3001 --env-file ./lead-nuxt/.env fastapp-nuxt

App URL:

• http://localhost:3000

Local Docker (Nuxt + Laravel API)

Run from g:\FastApp:

docker build -t fastapp-laravel-api ./laravel-api
docker build -t fastapp-nuxt ./lead-nuxt

docker network create fastapp-net

docker run -d --name laravel-api --network fastapp-net -p 8000:8000 --env-file ./laravel-api/.env fastapp-laravel-api
docker run -d --name lead-nuxt --network fastapp-net -p 3000:3000 -p 3001:3001 --env-file ./lead-nuxt/.env -e NUXT_PUBLIC_API_BASE_URL=http://laravel-api:8000 -e NUXT_PUBLIC_SOCKET_URL=http://localhost:3001 fastapp-nuxt

VPS Production Paths

• Stack root: /home/docker/lead-stack
• Nuxt project directory: /home/docker/lead-stack/lead-nuxt
• Nginx vhost: /etc/nginx/sites-enabled/creator.fastapp.cloud.conf

VPS Production Deploy Commands

Run on VPS:

cd /home/docker/lead-stack/lead-nuxt
# update code here (git pull or rsync/scp)

docker compose -f docker-compose.prod.yml up -d --build
docker compose -f docker-compose.prod.yml ps
docker logs --tail 200 lead-nuxt-app

Stop/restart:

docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d --build

Nginx Reverse Proxy (creator.fastapp.cloud)

Use this routing in /etc/nginx/sites-enabled/creator.fastapp.cloud.conf:

location @reverse_proxy {
  proxy_pass http://127.0.0.1:3010;
  proxy_http_version 1.1;
  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;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection Upgrade;
}

location ^~ /socket.io/ {
  proxy_pass http://127.0.0.1:3011/socket.io/;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection Upgrade;
  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;
}

location / {
  try_files $uri @reverse_proxy;
}

Validate and reload Nginx:

nginx -t
systemctl reload nginx

Health Checks

From VPS:

curl -sS -I http://127.0.0.1:3010/landing
curl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/landing
curl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/login
curl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/_nuxt/entry.zysWB1TI.css

Expected:

• /landing and /login: HTTP/2 200
• Nuxt CSS: content-type: text/css
• Nuxt JS: content-type: text/javascript

Issues Fixed During Deploy

1. Container crash loop due malformed Docker CMD

• Wrong: CMD [node, .output/server/index.mjs]
• Correct: CMD ["node", ".output/server/index.mjs"]

2. Frontend served as Vite dev build in production (module/MIME errors)

• Fixed by using Dockerfile.prod and running production output.

3. API should stay on external backend

• Set NUXT_PUBLIC_API_BASE_URL=https://core.fastapp.cloud

4. Browser-side extension errors can mask app behavior

• webpage_content_reporter.js errors are not generated by Nuxt.

GitHub Actions CI/CD

Workflows included:

• .github/workflows/ci.yml: PR/push CI (npm ci, prisma generate, nuxt build)
• .github/workflows/deploy.yml: build Dockerfile.prod, push image to GHCR, deploy on VPS via SSH (only on published GitHub Releases)

Required GitHub secrets:

• VPS_HOST: VPS IP or hostname
• VPS_USER: SSH user (example: root)
• VPS_PORT: SSH port (example: 22)
• VPS_SSH_KEY: private SSH key content used by Actions
• VPS_APP_DIR: app path on VPS (default fallback: /home/docker/lead-stack/lead-nuxt)
• VPS_COMPOSE_FILE: optional absolute compose path on VPS (example: /home/docker/lead-stack/lead-nuxt/docker-compose.prod.yml)
• VPS_ENV_FILE: env file path on VPS (default fallback: /home/docker/lead-stack/lead-nuxt/.env)
• GHCR_USERNAME: required GitHub username for package pull on VPS
• GHCR_PAT: required GitHub personal access token with at least read:packages on VPS side

GHCR auth behavior:

• Deploy requires GHCR_USERNAME + GHCR_PAT for docker login ghcr.io on VPS.

Production deploy behavior:

• Deploy triggers only when a GitHub Release is published
• Image tags pushed: ghcr.io/<owner>/<repo>:sha-<commit> and :<release-tag>
• Deploy supports both compose styles:
  • explicit image: (uses LEAD_NUXT_IMAGE=<tag>)
  • build: only (retags pulled image to the compose default local image tag)
• Health check: http://127.0.0.1:3010/login
• Auto-rollback to previous image if health check fails

Release deploy command:

git tag v1.0.0
git push origin v1.0.0
gh release create v1.0.0 --generate-notes

Git Push Commands (Docker Changes)

Run from g:\FastApp\lead-nuxt:

git add README.md Dockerfile.prod docker-compose.prod.yml .github/workflows/ci.yml .github/workflows/deploy.yml
git commit -m "ci: add GitHub Actions CI/CD for Docker deploy to VPS"
git push origin main