# 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`.

```bash
cd /mnt/docker-storage/appdata/<service-name>
```

### Start a service

```bash
# Start in detached mode
docker-compose up -d
```

### Stop a service

```bash
docker-compose down
```

### Restart a service

```bash
docker-compose restart
```

### View service status

```bash
docker-compose ps
```

## Viewing Logs

### Real-time logs

To view the logs for a service in real-time, use the `-f` flag.

```bash
docker-compose logs -f <service-name>
```

### Last N lines

To view the last N lines of the logs, use the `--tail` flag.

```bash
# Last 100 lines
docker-compose logs --tail=100 <service-name>
```

## Accessing Containers

To get a shell inside a running container, use `docker exec`.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
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.

```bash
# 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:

```bash
# 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
```