What is startstop-app?

This Claude skill provides comprehensive lifecycle management for the Orchestra application and its microservices. It automates the orchestration of backend FastAPI services, frontend React environments, and Docker-based infrastructure (Postgres, MinIO, Ollama), significantly reducing manual setup time and ensuring consistent development environments through intelligent process monitoring and health checks.

When should I use startstop-app?

startstop-app is useful in the following scenarios: • One-Click Environment Initialization: Automatically start the entire full-stack suite, including infrastructure, backend, and frontend, in the correct dependency order. • Automated Troubleshooting: Identify and resolve port conflicts or orphaned processes (like uvicorn or vite) that prevent services from starting. • Infrastructure Orchestration: Manage Docker containers for databases, object storage, and AI services without requiring manual CLI commands. • Environment Switching: Seamlessly transition between standard development modes and production-simulated environments using specific configuration scripts. • Health and Status Monitoring: Real-time verification of service availability and API endpoint health to ensure the system is ready for testing or development.

name	Start/Stop App
description	Start, stop, and manage the Orchestra application and its services.

Start/Stop App

Start, stop, and manage the Orchestra application including backend API, frontend UI, and supporting infrastructure services (database, storage, AI services).

Instructions

Prerequisites

Backend: Python 3.12+, uv package manager, dependencies installed (uv sync)
Frontend: Node.js, npm, dependencies installed (npm install)
Docker: For running infrastructure services (Postgres, MinIO, Ollama, etc.)
Environment files: .env for backend, .env.docker for Docker services

Application Architecture

Frontend (Vite/React) → Backend (FastAPI) → Services (Postgres, MinIO, Ollama)
Port 5173 (dev)          Port 8000           Ports 5432, 9000, 11434

Workflow

Assess what needs to be started based on user request
Check if services are already running to avoid conflicts
Start services in the correct order:
- Infrastructure first (database, storage)
- Backend API second
- Frontend UI last
Use background processes for long-running services
Report status and URLs to the user
Provide stop/restart commands when needed

Starting Services

Backend API (Development)

Option 1: Using Make (Recommended)

cd backend && make dev

Runs: uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000 --log-level debug --env-file .env
Auto-reload on code changes
API docs: http://localhost:8000/docs

Option 2: Using Script (Interactive)

cd backend && bash scripts/dev.sh

Prompts for environment (.env vs .env.production)
Sets API version from git tags
Good for connecting to prod database locally

Background Mode:

cd backend && uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000 --log-level debug --env-file .env

Use run_in_background: true with Bash tool

Frontend UI (Development)

cd frontend && npm run dev

Vite dev server with HMR (Hot Module Replacement)
Usually runs on http://localhost:5173
Auto-reload on code changes

Background Mode: Use run_in_background: true with Bash tool

Infrastructure Services (Docker)

Start Database (Postgres + PgAdmin)

docker compose up postgres pgadmin -d

Postgres: localhost:5432 (user: admin, password: test1234)
PgAdmin: http://localhost:4040 (admin@example.com / test1234)

Start File Storage (MinIO)

docker compose up minio -d

API: http://localhost:9000
Console: http://localhost:9001
Credentials in docker-compose.yml

Start AI Service (Ollama)

docker compose up ollama -d

API: http://localhost:11434
Requires NVIDIA GPU runtime

Start Full Stack (Docker)

docker compose up orchestra postgres -d

Runs backend in Docker container
Uses .env.docker configuration

Start All Services

docker compose up -d

Starts all defined services in background

Stopping Services

Stop Backend/Frontend (Development)

If running in foreground: Ctrl+C

If running in background:

# Find the process
ps aux | grep uvicorn  # for backend
ps aux | grep vite     # for frontend

# Kill by PID
kill <PID>

# Or kill all
pkill -f uvicorn
pkill -f vite

Stop Docker Services

Stop specific services:

docker compose stop postgres pgadmin
docker compose stop minio
docker compose stop ollama
docker compose stop orchestra

Stop and remove containers:

docker compose down

Stop and remove with volumes (CAUTION: destroys data):

docker compose down -v

Checking Status

Check Running Processes

# Backend
ps aux | grep uvicorn

# Frontend
ps aux | grep vite

# Docker services
docker compose ps

Check Ports

# See what's listening on ports
lsof -i :8000  # Backend
lsof -i :5173  # Frontend
lsof -i :5432  # Postgres

Check Service Health

# Backend API
curl http://localhost:8000/health

# Frontend
curl http://localhost:5173

# Postgres
docker compose exec postgres pg_isready

Common Scenarios

Example 1: Start Full Development Environment

User: "Start the app for development" Assistant: I'll start the development environment.

Starting infrastructure services [Executes: docker compose up postgres pgadmin -d]
Starting backend API [Executes: cd backend && make dev in background]
Starting frontend UI [Executes: cd frontend && npm run dev in background]

Services running:

Backend API: http://localhost:8000/docs
Frontend UI: http://localhost:5173
Database: localhost:5432
PgAdmin: http://localhost:4040

Example 2: Stop Everything

User: "Stop the app" Assistant: I'll stop all services.

Stopping development servers [Kills uvicorn and vite processes]
Stopping Docker services [Executes: docker compose down]

All services stopped.

Example 3: Restart Backend Only

User: "Restart the backend" Assistant: I'll restart the backend API.

Stopping backend [Kills uvicorn process]
Starting backend [Executes: cd backend && make dev in background]

Backend restarted at http://localhost:8000/docs

Example 4: Start with Production Database

User: "Start backend connected to production database" Assistant: I'll start the backend with production configuration. [Executes: cd backend && bash scripts/dev.sh with "yes" input]

Backend started with production database connection.

Example 5: Check What's Running

User: "What services are running?" Assistant: Let me check the status. [Executes: docker compose ps and ps aux | grep -E "uvicorn|vite"]

Currently running:

Backend: Yes (PID: 12345, http://localhost:8000)
Frontend: Yes (PID: 12346, http://localhost:5173)
Postgres: Yes (container: postgres)
PgAdmin: Yes (container: pgadmin)

Important Notes

Port Conflicts

If you get "address already in use" errors:

Check what's using the port: lsof -i :<port>
Stop the conflicting process: kill <PID>
Or use a different port

Background Processes

When running services in background:

Always save the task ID for monitoring
Use TaskOutput to check logs
Provide stop commands to the user

Environment Variables

Backend dev: Uses .env by default
Backend Docker: Uses .env.docker
Frontend: Uses Vite's env files (.env, .env.local)

Database Migrations

Before starting backend for the first time:

cd backend
alembic upgrade head

Seeding Data

To seed default users:

cd backend
make seeds.user

URLs Reference

Development:

Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs
Frontend: http://localhost:5173
Postgres: localhost:5432
PgAdmin: http://localhost:4040
MinIO API: http://localhost:9000
MinIO Console: http://localhost:9001
Ollama: http://localhost:11434

Production:

startstop-app

When & Why to Use This Skill

Use Cases