serve

name: serve description: Start, stop, or check the Ghostfolio development environment (Docker services, API server, Angular client) disable-model-invocation: true allowed-tools: Bash argument-hint: '[start|stop|status|restart]'

Ghostfolio Dev Environment Manager

Manage the full Ghostfolio development stack: Docker infrastructure (PostgreSQL + Redis), NestJS API server, and Angular client.

Current Environment State

Check what's running before taking action: !docker compose -f /home/james-allen/Projects/ghostfolio/docker/docker-compose.dev.yml ps --format '{{.Name}}: {{.Status}}' 2>/dev/null || echo "Docker services: not running"

Commands

Based on the argument $ARGUMENTS:

start (default if no argument)

1. Start Docker services (PostgreSQL on port 5432, Redis on port 6379):

   docker compose -f /home/james-allen/Projects/ghostfolio/docker/docker-compose.dev.yml up -d
   

2. Wait for PostgreSQL to be healthy (check with pg_isready)
3. If this is first run or database needs setup, run:

   cd /home/james-allen/Projects/ghostfolio && npm run database:setup
   

4. Start the NestJS API server in background on port 3333:

   cd /home/james-allen/Projects/ghostfolio && npm run start:server
   

5. Wait for the API to be ready — poll http://localhost:3333/api/v1/health until it returns HTTP 200 (up to 90 seconds, checking every 3 seconds). Report progress while waiting.
6. Start the Angular client in background on port 4200:

   cd /home/james-allen/Projects/ghostfolio && npm run start:client
   

7. Report status of all services with URLs:
   • API: http://localhost:3333/api/v1/health
   • Client: http://localhost:4200/en

stop

1. Kill API server and Angular client processes (the actual process names use nx, not npm):

   pkill -f "nx run api:serve" 2>/dev/null; pkill -f "nx run client:serve" 2>/dev/null; kill $(lsof -ti :3333) 2>/dev/null; sleep 2; pkill -9 -f "nx run api:serve" 2>/dev/null; pkill -9 -f "nx run client:serve" 2>/dev/null; kill -9 $(lsof -ti :3333) 2>/dev/null; true
   

   Then verify port 3333 is free before proceeding.
2. Stop Docker services:

   docker compose -f /home/james-allen/Projects/ghostfolio/docker/docker-compose.dev.yml down
   

status

1. Check Docker services: docker compose -f docker/docker-compose.dev.yml ps
2. Check if API is responding: curl -s http://localhost:3333/api/v1/health
3. Check if client is responding: curl -s http://localhost:4200/en
4. Report status of each service

restart

1. Run stop sequence
2. Run start sequence

Important Notes

• The .env file must exist (copy from .env.dev if missing)
• First user created via the UI becomes ADMIN
• API server uses Webpack watch mode for hot reload
• Client uses Angular HMR (Hot Module Replacement)
• PostgreSQL data persists across restarts via Docker volumes