name: documentos-vps-recovery

description: Debug and recover DocCorretor (documentos.rochasalesseguros.com.br) on VPS — zombie processes, 404 assets, build/sync/restart patterns for TanStack Start app.

trigger: "documentos VPS 404 assets zombie process restart not working"

DocCorretor VPS Recovery — Build, Sync & Restart Pattern

Symptoms

• - Assets return 404 (e.g. index-D460w22x.js, styles-DeG0GZJ2.css)
• - Page loads old code / button doesn't work
• - curl localhost:3010/api/public/generate-upload-link works but browser gets 404
• - systemctl restart documentos doesn't fix it

Root Causes

1. Zombie Process (most common)

systemd restart doesn't always kill the old Node process. The old process keeps serving stale HTML/assets on port 3010 while the new one fails to bind (EADDRINUSE) or returns 500.

2. Missing Asset Sync

TanStack Start builds put assets in dist/server/assets/. nginx serves dist/client/assets/. After every build you MUST run:

`bash

cp -r dist/server/assets/* dist/client/assets/

`

3. Stale TanStack Manifest

The _tanstack-start-manifest_v-*.js references hash-named assets. If these don't exist in dist/server/assets/, manifests from old builds cause 404s.

---

Full Recovery Procedure

`bash

cd /var/www/documentos2/app

1. STOP service

sudo systemctl stop documentos

2. Kill ANY processes still on port 3010

lsof -i :3010 # find PIDs

sudo kill -9 # kill all of them

3. Clean all caches

rm -rf dist .tanstack node_modules/.vite .vite

4. BUILD

PATH="/root/.nvm/versions/node/v20.20.2/bin:$PATH" npm run build

5. Sync assets to nginx-served directory

mkdir -p dist/client/assets

rm -rf dist/client/assets/*

cp -r dist/server/assets/* dist/client/assets/

6. Verify manifest and assets match

MANIFEST=$(ls dist/server/assets/_tanstack-start-manifest_v-*.js | head -1)

echo "Manifest: $MANIFEST"

grep "clientEntry" "$MANIFEST"

ls dist/server/assets/ | grep "index-D"

The index file named in manifest MUST exist in dist/server/assets/

7. START service

sudo systemctl start documentos

sleep 2

8. VERIFY

curl -s http://localhost:3010/ | grep -o 'assets/index-[^"]*\.js' | head -3

ls dist/server/assets/ | grep "index-D"

`

Key Files

• - Service: sudo systemctl restart documentos
• - Build: npm run build (TanStack Start)
• - Server start: start-server.mjs (port 3010)
• - Assets source: dist/server/assets/
• - Assets nginx: dist/client/assets/

Critical Env Vars (systemd)

`

PORT=3010

HOST=0.0.0.0

NODE_ENV=production

SUPABASE_PAT=sbp_REDACTED

VITE_SUPABASE_URL=https://dauftiqcvgaydddoxqhh.supabase.co

`

Supabase Tables for Upload Links

• - client_upload_links: id, token, client_id (NULL initially), folder_id, expires_at, used_at
• - client_folders: id, client_id (NULL initially), name, created_by, created_at
• - System user: 00000000-0000-0000-0000-000000000001

Common Fixes

• - 404 on static assets → sync dist/server/assets/* → dist/client/assets/
• - Button not working → rebuild (old code running)
• - 500 from server → check node_modules (h3-v2 may be missing, reinstall)
• - Port EADDRINUSE → zombie process, kill -9
• - Browser shows old HTML → old process still on port