137 lines
2.9 KiB
Markdown
137 lines
2.9 KiB
Markdown
# 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
|
|
```
|