f3-dev-servers

name: f3-dev-servers description: Start and manage f3-nation development servers (Caddy, API, Map). Use when the user wants to start dev servers, check if services are running, or troubleshoot the local development environment.

F3 Nation Development Servers

Start the three dev servers needed for local f3-nation development.

Starting All Services (Agent Method)

The agent CAN start all three services by running Shell commands with block_until_ms: 0 to background them immediately.

Run these in parallel with block_until_ms: 0 and working_directory set to the repo root:

# 1. Caddy
caddy run --config Caddyfile

# 2. API
PORT=3001 pnpm -F f3-api dev

# 3. Map
PORT=3000 pnpm -F f3-map dev

Note: nvm/rbenv/jenv should be auto-loaded via ~/.zshenv so no prefix needed.

Agent workflow:

Run check-status.sh first to see what's already running
Start only the services that aren't running (use block_until_ms: 0 for each)
Wait 5 seconds for services to initialize
Run check-status.sh again to verify all services are up
Optionally read terminal output files to check for startup errors

Quick Check: Are Services Running?

Run the status check script from the repo root:

.cursor/skills/f3-dev-servers/scripts/check-status.sh

This script uses nc (netcat) for fast port checking (~1 second). It checks ports 443, 3000, and 3001.

Or check manually:

# Fast check with netcat
nc -z localhost 443 && echo "Caddy OK" || echo "Caddy DOWN"
nc -z localhost 3000 && echo "Map OK" || echo "Map DOWN"
nc -z localhost 3001 && echo "API OK" || echo "API DOWN"

Note: Avoid using lsof for port checks on macOS - it takes 30+ seconds.

Manual Startup (User Method)

If the user prefers to start manually in named terminals:

1. Caddy (reverse proxy) - in `caddy` terminal

caddy run --config Caddyfile

Caddy proxies:

https://map.f3nation.test → localhost:3000
https://api.f3nation.test → localhost:3001

2. API Server - in `api` terminal

PORT=3001 pnpm -F f3-api dev

3. Map App - in `map` terminal

PORT=3000 pnpm -F f3-map dev

Startup Order

Start in this order for best results:

Caddy first (handles HTTPS)
API second (the map app depends on API endpoints)
Map app last

Verifying Startup Success

After starting, check terminal outputs for these success indicators:

Caddy: Look for "msg":"serving initial configuration"
API: Look for ✓ Ready in X.Xs
Map: Look for ✓ Ready in X.Xs

Stopping Services

To stop services, use pkill (faster than lsof):

pkill -f "caddy run"
pkill -f "f3-api dev"
pkill -f "f3-map dev"

Or kill by port (slower, lsof takes 30+ seconds on macOS):

kill -9 $(lsof -t -i :3000)  # Map
kill -9 $(lsof -t -i :3001)  # API
sudo kill -9 $(lsof -t -i :443)   # Caddy (needs sudo for port 443)

For user-started services in IDE terminals, press Ctrl+C in the terminal.

Troubleshooting

Port already in use

# Find what's using the port
lsof -i :3000

# Kill it
kill -9 <PID>

Node version warning

If you see this warning:

WARN  Unsupported engine: wanted: {"node":">=20.19.0"} (current: {"node":"v18.20.4"...})

The ~/.zshenv file may be missing or misconfigured. It should contain:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

This ensures nvm is loaded for all zsh shells, including non-interactive ones from Cursor.

Caddy certificate issues

Ensure the certificate files exist in the project root:

map.f3nation.test+1-cert.pem
map.f3nation.test+1-key.pem

If missing, regenerate with mkcert:

mkcert map.f3nation.test api.f3nation.test

Database not running

If you see database connection errors, ensure PostgreSQL/Docker is running:

docker ps  # Check if postgres container is running