# 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):

```env
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`:

```powershell
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`:

```powershell
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:

```bash
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:

```bash
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`:

```nginx
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:

```bash
nginx -t
systemctl reload nginx
```

## Health Checks

From VPS:

```bash
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:

```powershell
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`:

```powershell
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
```