Skip to main content

Common Tasks

This page covers common operational tasks for managing FOVEA services.

Starting and Stopping Services​

Start All Services​

CPU mode (default):

docker compose up -d

GPU mode:

docker compose --profile gpu up -d

With logs visible:

docker compose up

Specific services only:

docker compose up -d frontend backend postgres redis

Stop Services​

Stop all:

docker compose down

Stop GPU services:

docker compose --profile gpu down

Stop and remove volumes (WARNING: deletes all data):

docker compose down -v

Restart Services​

Restart specific service:

docker compose restart backend

Restart all:

docker compose restart

Switch Between CPU and GPU​

Switch from CPU to GPU:

docker compose down
docker compose --profile gpu up -d

Switch from GPU to CPU:

docker compose --profile gpu down
docker compose up -d

Check Service Status​

docker compose ps

Shows running status and health for all services.

Viewing Logs​

All Services​

docker compose logs -f

Specific Service​

docker compose logs -f backend
docker compose logs -f model-service

Last N Lines​

docker compose logs --tail=100 backend

Without Following​

docker compose logs backend

Database Operations​

Run Migrations​

docker compose exec backend npx prisma migrate deploy

Access PostgreSQL Shell​

docker compose exec postgres psql -U fovea fovea

Backup Database​

docker compose exec postgres pg_dump -U fovea fovea > backup.sql

With timestamp:

docker compose exec postgres pg_dump -U fovea fovea > backup_$(date +%Y%m%d_%H%M%S).sql

Restore Database​

cat backup.sql | docker compose exec -T postgres psql -U fovea fovea

Open Prisma Studio​

docker compose exec backend npx prisma studio

Access at http://localhost:5555

Reset Database​

WARNING: This deletes all data.

docker compose exec backend npx prisma migrate reset

Video Management​

Add Videos​

Copy video files to the /data directory:

cp /path/to/video.mp4 data/

Add Video Metadata​

Create .info.json file alongside video:

cat > data/video.info.json <<EOF
{
  "title": "Video Title",
  "description": "Video description"
}
EOF

Scan for New Videos​

Restart backend to detect new videos:

docker compose restart backend

List Videos​

ls -lh data/*.mp4

Updating Services​

Pull Latest Images​

docker compose pull

Rebuild Services​

Rebuild all:

docker compose build

Rebuild specific service:

docker compose build backend

Rebuild without cache:

docker compose build --no-cache frontend

Update and Restart​

docker compose up -d --build

Cleaning Up​

Remove Stopped Containers​

docker compose down

Remove Unused Docker Resources​

docker system prune

Remove all (including volumes):

docker system prune -a --volumes

View Disk Usage​

docker system df

Clean Specific Volume​

WARNING: Deletes data in volume.

docker volume rm fovea_model-cache

Monitoring and Health​

Check Container Resource Usage​

docker stats

View Service Health​

docker compose ps

Look for "(healthy)" status.

Test Health Endpoints​

Backend:

curl http://localhost:3001/health

Model Service:

curl http://localhost:8000/health

Access Monitoring Dashboards​

Shell Access​

Backend Shell​

docker compose exec backend sh

Model Service Shell​

CPU mode:

docker compose exec model-service bash

GPU mode:

docker compose exec model-service-gpu bash

PostgreSQL Shell​

docker compose exec postgres psql -U fovea fovea

Redis Shell​

docker compose exec redis redis-cli

Configuration​

View Environment Variables​

In container:

docker compose exec backend env

Edit Configuration​

Edit .env file in project root, then restart:

docker compose restart

View Compose Configuration​

docker compose config

Shows resolved configuration with environment variable substitution.

Troubleshooting​

Service Won't Start​

Check logs for errors:

docker compose logs <service-name>

Port Conflicts​

Find process using port:

lsof -i :5173

Kill process or change port in docker-compose.yml.

Out of Disk Space​

Clean Docker resources:

docker system prune -a --volumes

Check disk usage:

df -h

Database Connection Issues​

Ensure PostgreSQL is running:

docker compose ps postgres

Check logs:

docker compose logs postgres

GPU Not Detected​

Ensure using GPU profile:

docker compose --profile gpu ps

Test GPU in container:

docker compose exec model-service-gpu nvidia-smi

Backup Strategy​

Critical Data​

Database (daily recommended):

docker compose exec postgres pg_dump -U fovea fovea | gzip > backup_$(date +%Y%m%d).sql.gz

Videos (as needed):

tar -czf videos_backup_$(date +%Y%m%d).tar.gz data/

Configuration (before changes):

cp .env .env.backup
cp docker-compose.yml docker-compose.yml.backup

Automated Backup Script​

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/path/to/backups

# Backup database
docker compose exec postgres pg_dump -U fovea fovea | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Backup Redis
docker compose exec redis redis-cli SAVE
docker cp fovea-redis-1:/data/dump.rdb $BACKUP_DIR/redis_$DATE.rdb

# Backup configuration
cp .env $BACKUP_DIR/env_$DATE

echo "Backup completed: $DATE"

Next Steps​