2.9 KiB
Development Quick Reference
Last updated: 2025-12-13
This guide provides a quick reference for common development and administrative tasks.
Service Management
All services are managed with docker-compose. To manage a service, navigate to its directory in /mnt/docker-storage/appdata.
cd /mnt/docker-storage/appdata/<service-name>
Start a service
# Start in detached mode
docker-compose up -d
Stop a service
docker-compose down
Restart a service
docker-compose restart
View service status
docker-compose ps
Viewing Logs
Real-time logs
To view the logs for a service in real-time, use the -f flag.
docker-compose logs -f <service-name>
Last N lines
To view the last N lines of the logs, use the --tail flag.
# Last 100 lines
docker-compose logs --tail=100 <service-name>
Accessing Containers
To get a shell inside a running container, use docker exec.
# Get a bash shell
docker exec -it <container-name> /bin/bash
# Get a sh shell
docker exec -it <container-name> /bin/sh
You can find the <container-name> from the Service Inventory document or by running docker ps.
Building and Deploying Updates
To deploy updates for a service that is built from source (like books_webv2), you need to pull the latest changes and rebuild the Docker image.
# Navigate to the service directory
cd /mnt/docker-storage/appdata/<service-name>
# Pull the latest changes from git
git pull
# Rebuild and restart the service
docker-compose up -d --build
For services that use a pre-built Docker image, you can update the image by pulling the latest version and recreating the container.
# Navigate to the service directory
cd /mnt/docker-storage/appdata/<service-name>
# Pull the latest image
docker-compose pull <service-name>
# Recreate the container
docker-compose up -d --force-recreate <service-name>
Health Checks
To check the health status of a container, you can inspect the container's state.
docker inspect --format '{{.State.Health.Status}}' <container-name>
This will return healthy, unhealthy, or starting.
Database Migrations (for Books V2)
The books_webv2 application uses Alembic for database migrations.
Create a new migration
When you make changes to the SQLAlchemy models in backend/app/models, you need to create a new migration script.
# Navigate to the backend directory
cd /mnt/docker-storage/appdata/books_webv2/backend
# Run from within the virtual environment or with docker
docker-compose exec backend alembic revision --autogenerate -m "Your migration message"
Apply migrations
To apply all pending migrations to the database, run:
# Navigate to the backend directory
cd /mnt/docker-storage/appdata/books_webv2/backend
# Run from within the virtual environment or with docker
docker-compose exec backend alembic upgrade head