QUICKSTART.md

Squirrel Backend - Quick Start Guide

Get the backend running in 2 minutes!

Prerequisites

• Docker and Docker Compose installed
• (Optional) Python 3.11+ for local development

Option 1: Docker Compose (Fastest)

1. Configure EPICS Networking

If you need to connect to EPICS servers:

# Copy the example environment file
cp docker/.env.example docker/.env

# The example .env file has EPICS_CA_AUTO_ADDR_LIST set to YES by default.
# This should be sufficient to find any test PVs you are running locally without any modifications.
#
# If you need to point to specific IP addresses to locate PVs, uncomment EPICS_CA_ADDR_LIST or
# EPICS_PVA_ADDR_LIST as needed and specify the IP address needed.
#
# If pointing to a hostname, ensure that a DNS entry is created for it by specifying either EPICS_HOST_PROD 
# or EPICS_HOST_DMZ

2. Start everything

cd docker
docker compose up --build

That's it! The backend is now running:

• API: http://localhost:8080
• Swagger docs: http://localhost:8080/docs
• Health: http://localhost:8080/v1/health/summary

What's Running?

• squirrel-api - REST/WebSocket API server (port 8080)
• squirrel-db - PostgreSQL database (port 5432)
• squirrel-redis - Redis cache/queue (port 6379)
• squirrel-monitor - EPICS PV monitoring service
• squirrel-worker-1 & squirrel-worker-2 - Background job processors

Load Test Data

# In a new terminal
docker compose exec api python -m scripts.seed_pvs --count 100

This creates 100 test PVs with tags. Now you can test snapshots!

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api
docker compose logs -f monitor
docker compose logs -f worker

Stop Everything

docker compose down

# Or to also delete the database
docker compose down -v

Option 2: Local Development

Better for active development with hot-reload:

# 1. Start infrastructure only
cd docker
docker compose up -d db redis

# 2. Run setup script
cd ..
./setup.sh

# 3. Run migrations
alembic upgrade head

# 4. Load test data
python -m scripts.seed_pvs --count 100

# 5. Start services (each in a separate terminal)
uvicorn app.main:app --reload --port 8000      # Terminal 1: API
python -m app.monitor_main                      # Terminal 2: Monitor
arq app.worker.WorkerSettings                   # Terminal 3: Worker

Access at: http://localhost:8000

Common Commands

# Check service status
docker compose ps

# Restart a service
docker compose restart api

# Scale workers
docker compose up -d --scale worker=4

# Access database
docker exec -it squirrel-db psql -U squirrel

# Access Redis CLI
docker exec -it squirrel-redis redis-cli

# Run migrations in Docker
docker exec -it squirrel-api alembic upgrade head

Troubleshooting

Snapshots are empty

This is normal! Test PVs don't exist on a real EPICS network. To test with real data:

1. Upload real PV addresses via CSV: python -m scripts.upload_csv your_pvs.csv
2. Make sure your EPICS network is accessible from Docker

Worker not running

Snapshots will hang if the worker isn't running:

docker compose ps worker           # Check status
docker compose up -d worker        # Start if stopped
docker compose logs -f worker      # View logs

Port 8080 already in use

Edit docker/docker-compose.yml and change the port:

api:
  ports:
    - "8081:8000"  # Change 8080 to 8081

Monitor not connecting

Check Redis connection:

docker compose logs monitor
docker exec -it squirrel-redis redis-cli PING

Next Steps

• Read the full README.md for detailed documentation
• Check out ARCHITECTURE.md for system design
• See API documentation after starting the backend

Need Help?

• Check logs: docker compose logs -f [service]
• Verify all services are running: docker compose ps
• Restart everything: docker compose restart
• Reset database: docker compose down -v && docker compose up -d

Happy snapshoting! 🐿️