{"id":"repo/readme","source":"repo","sourceLabel":"repository root","sourcePath":"README.md","routePath":"/fastapp/public-docs/page/repo/readme","rawPath":"/fastapp/public-docs/raw/repo/readme","slug":["repo","readme"],"slugPath":"repo/readme","title":"FastApp Engine (lead nuxt)","description":"Nuxt 4 app for FastApp Engine. This repository now includes both Docker development and production deployment flows.","headings":["FastApp Engine (lead nuxt)","Deployment Target (Current)","Docker Files in This Repo","Required Runtime Environment","Local Docker (Development)","Local Docker (Nuxt + Laravel API)","VPS Production Paths","VPS Production Deploy Commands","update code here (git pull or rsync/scp)","Nginx Reverse Proxy (creator.fastapp.cloud)","Health Checks","Issues Fixed During Deploy","GitHub Actions CI/CD","Git Push Commands (Docker Changes)"],"wordCount":369,"markdown":"# FastApp Engine (lead-nuxt)\r\n\r\nNuxt 4 app for FastApp Engine. This repository now includes both Docker development and production deployment flows.\r\n\r\n## Deployment Target (Current)\r\n\r\n- Frontend domain: `https://creator.fastapp.cloud`\r\n- Nuxt app: Docker container `lead-nuxt-app`\r\n- Backend API (kept external): `https://core.fastapp.cloud`\r\n- Reverse proxy: Nginx on VPS\r\n\r\n## Docker Files in This Repo\r\n\r\n- `Dockerfile`: development image (`nuxt dev`)\r\n- `Dockerfile.prod`: production build and runtime (`node .output/server/index.mjs`)\r\n- `docker-compose.prod.yml`: production container settings and host port bindings\r\n- `DOCKER_RUN.md`: local dev run commands\r\n\r\n## Required Runtime Environment\r\n\r\nSet these in `.env` (or via environment overrides):\r\n\r\n```env\r\nDATABASE_URL=postgresql://...\r\nDIRECT_URL=postgresql://...\r\nNUXT_PUBLIC_API_BASE_URL=https://core.fastapp.cloud\r\nNUXT_PUBLIC_SOCKET_URL=/\r\nSOCKET_IO_PORT=3001\r\n```\r\n\r\nImportant: Prisma requires `DATABASE_URL` and `DIRECT_URL` to start with `postgresql://` (or `postgres://`).\r\n\r\n## Local Docker (Development)\r\n\r\nRun from `g:\\FastApp`:\r\n\r\n```powershell\r\ndocker build -t fastapp-nuxt ./lead-nuxt\r\ndocker run -d --name lead-nuxt -p 3000:3000 -p 3001:3001 --env-file ./lead-nuxt/.env fastapp-nuxt\r\n```\r\n\r\nApp URL:\r\n\r\n- `http://localhost:3000`\r\n\r\n## Local Docker (Nuxt + Laravel API)\r\n\r\nRun from `g:\\FastApp`:\r\n\r\n```powershell\r\ndocker build -t fastapp-laravel-api ./laravel-api\r\ndocker build -t fastapp-nuxt ./lead-nuxt\r\n\r\ndocker network create fastapp-net\r\n\r\ndocker run -d --name laravel-api --network fastapp-net -p 8000:8000 --env-file ./laravel-api/.env fastapp-laravel-api\r\ndocker 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\r\n```\r\n\r\n## VPS Production Paths\r\n\r\n- Stack root: `/home/docker/lead-stack`\r\n- Nuxt project directory: `/home/docker/lead-stack/lead-nuxt`\r\n- Nginx vhost: `/etc/nginx/sites-enabled/creator.fastapp.cloud.conf`\r\n\r\n## VPS Production Deploy Commands\r\n\r\nRun on VPS:\r\n\r\n```bash\r\ncd /home/docker/lead-stack/lead-nuxt\r\n# update code here (git pull or rsync/scp)\r\n\r\ndocker compose -f docker-compose.prod.yml up -d --build\r\ndocker compose -f docker-compose.prod.yml ps\r\ndocker logs --tail 200 lead-nuxt-app\r\n```\r\n\r\nStop/restart:\r\n\r\n```bash\r\ndocker compose -f docker-compose.prod.yml down\r\ndocker compose -f docker-compose.prod.yml up -d --build\r\n```\r\n\r\n## Nginx Reverse Proxy (creator.fastapp.cloud)\r\n\r\nUse this routing in `/etc/nginx/sites-enabled/creator.fastapp.cloud.conf`:\r\n\r\n```nginx\r\nlocation @reverse_proxy {\r\n  proxy_pass http://127.0.0.1:3010;\r\n  proxy_http_version 1.1;\r\n  proxy_set_header Host $host;\r\n  proxy_set_header X-Real-IP $remote_addr;\r\n  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\r\n  proxy_set_header X-Forwarded-Proto $scheme;\r\n  proxy_set_header Upgrade $http_upgrade;\r\n  proxy_set_header Connection Upgrade;\r\n}\r\n\r\nlocation ^~ /socket.io/ {\r\n  proxy_pass http://127.0.0.1:3011/socket.io/;\r\n  proxy_http_version 1.1;\r\n  proxy_set_header Upgrade $http_upgrade;\r\n  proxy_set_header Connection Upgrade;\r\n  proxy_set_header Host $host;\r\n  proxy_set_header X-Real-IP $remote_addr;\r\n  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\r\n  proxy_set_header X-Forwarded-Proto $scheme;\r\n}\r\n\r\nlocation / {\r\n  try_files $uri @reverse_proxy;\r\n}\r\n```\r\n\r\nValidate and reload Nginx:\r\n\r\n```bash\r\nnginx -t\r\nsystemctl reload nginx\r\n```\r\n\r\n## Health Checks\r\n\r\nFrom VPS:\r\n\r\n```bash\r\ncurl -sS -I http://127.0.0.1:3010/landing\r\ncurl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/landing\r\ncurl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/login\r\ncurl -skI --resolve creator.fastapp.cloud:443:127.0.0.1 https://creator.fastapp.cloud/_nuxt/entry.zysWB1TI.css\r\n```\r\n\r\nExpected:\r\n\r\n- `/landing` and `/login`: `HTTP/2 200`\r\n- Nuxt CSS: `content-type: text/css`\r\n- Nuxt JS: `content-type: text/javascript`\r\n\r\n## Issues Fixed During Deploy\r\n\r\n1. Container crash loop due malformed Docker `CMD`\r\n\r\n- Wrong: `CMD [node, .output/server/index.mjs]`\r\n- Correct: `CMD [\"node\", \".output/server/index.mjs\"]`\r\n\r\n2. Frontend served as Vite dev build in production (module/MIME errors)\r\n\r\n- Fixed by using `Dockerfile.prod` and running production output.\r\n\r\n3. API should stay on external backend\r\n\r\n- Set `NUXT_PUBLIC_API_BASE_URL=https://core.fastapp.cloud`\r\n\r\n4. Browser-side extension errors can mask app behavior\r\n\r\n- `webpage_content_reporter.js` errors are not generated by Nuxt.\r\n\r\n## GitHub Actions CI/CD\r\n\r\nWorkflows included:\r\n\r\n- `.github/workflows/ci.yml`: PR/push CI (`npm ci`, `prisma generate`, `nuxt build`)\r\n- `.github/workflows/deploy.yml`: build `Dockerfile.prod`, push image to GHCR, deploy on VPS via SSH (only on published GitHub Releases)\r\n\r\nRequired GitHub secrets:\r\n\r\n- `VPS_HOST`: VPS IP or hostname\r\n- `VPS_USER`: SSH user (example: `root`)\r\n- `VPS_PORT`: SSH port (example: `22`)\r\n- `VPS_SSH_KEY`: private SSH key content used by Actions\r\n- `VPS_APP_DIR`: app path on VPS (default fallback: `/home/docker/lead-stack/lead-nuxt`)\r\n- `VPS_COMPOSE_FILE`: optional absolute compose path on VPS (example: `/home/docker/lead-stack/lead-nuxt/docker-compose.prod.yml`)\r\n- `VPS_ENV_FILE`: env file path on VPS (default fallback: `/home/docker/lead-stack/lead-nuxt/.env`)\r\n- `GHCR_USERNAME`: required GitHub username for package pull on VPS\r\n- `GHCR_PAT`: required GitHub personal access token with at least `read:packages` on VPS side\r\n\r\nGHCR auth behavior:\r\n\r\n- Deploy requires `GHCR_USERNAME` + `GHCR_PAT` for `docker login ghcr.io` on VPS.\r\n\r\nProduction deploy behavior:\r\n\r\n- Deploy triggers only when a GitHub Release is published\r\n- Image tags pushed: `ghcr.io/<owner>/<repo>:sha-<commit>` and `:<release-tag>`\r\n- Deploy supports both compose styles:\r\n  - explicit `image:` (uses `LEAD_NUXT_IMAGE=<tag>`)\r\n  - `build:` only (retags pulled image to the compose default local image tag)\r\n- Health check: `http://127.0.0.1:3010/login`\r\n- Auto-rollback to previous image if health check fails\r\n\r\nRelease deploy command:\r\n\r\n```powershell\r\ngit tag v1.0.0\r\ngit push origin v1.0.0\r\ngh release create v1.0.0 --generate-notes\r\n```\r\n\r\n## Git Push Commands (Docker Changes)\r\n\r\nRun from `g:\\FastApp\\lead-nuxt`:\r\n\r\n```powershell\r\ngit add README.md Dockerfile.prod docker-compose.prod.yml .github/workflows/ci.yml .github/workflows/deploy.yml\r\ngit commit -m \"ci: add GitHub Actions CI/CD for Docker deploy to VPS\"\r\ngit push origin main\r\n```\r\n"}