digiispy/gps

Docker Guide for Gps Data Fetcher

This guide explains how to run and manage the Gps Data Fetcher application using Docker and Docker Compose.

Prerequisites

• Docker
• Docker Compose
• Git (to clone the repository)

Environment Setup

1. Create a .env file in the docker directory with the following variables:

env
DB_TAG=11.5.2
DB_HOST=db
DB_PORT=3306
DB_NAME=gps
DB_USER=gps
DB_PASSWORD=your_secure_password
DB_ROOT_PASSWORD=your_secure_root_password
DB_VENDOR=mariadb

Running the Application

Using Docker Compose (Recommended)

1. Start the complete application stack:

bash
docker-compose -f docker/docker-compose.yml up --abort-on-container-exit ; docker-compose -f docker/docker-compose.yml down

This will start:

• MariaDB database (accessible on port 3306)
• FastAPI application (accessible on port 8000)
• HAProxy for routing (accessible on port 80)

2. View logs:

bash
# All services
docker compose -f docker/docker-compose.yml logs -f

# Specific service
docker compose -f docker/docker-compose.yml logs -f gps

3. Stop the application:

bash
docker compose -f docker/docker-compose.yml down

Database Migrations

The application uses Alembic for database migrations. To manage migrations:

1. Start the migrations testing database:

bash
docker compose -f docker/docker-compose.yml up -d db_migrations

2. Run migrations:

bash
alembic -c alembic-migrations.ini upgrade head

3. Create new migrations:

bash
alembic -c alembic-migrations.ini revision --autogenerate -m "description_of_changes"

Manual Docker Setup

If you need to run the application container manually:

bash
docker run \
  -e DB_TAG=11.5.2 \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=3306 \
  -e DB_NAME=gps \
  -e DB_USER=gps \
  -e DB_PASSWORD=gps \
  -p 8000:8000 \
  --add-host=host.docker.internal:host-gateway \
  digiispy/gps:latest

Docker Services

Database (db)

• MariaDB instance for production use
• Port: 3306
• Contains application data
• Automatically created with specified database and user

Migration Database (db_migrations)

• MariaDB instance for testing migrations
• Port: 3307
• Used to safely test database changes
• Identical configuration to production database

Application (gps)

• FastAPI application
• Port: 8000 (API)
• Port: 80 (HAProxy)
• Includes:
  • FastAPI application
  • HAProxy for routing
  • Automatic database migrations
  • Health checks

Development with Docker

Building the Image

If you need to build the image locally:

bash
# From project root
docker build -t digiispy/gps:latest .

Development Workflow

1. Start development stack:

bash
docker compose -f docker/docker-compose.yml up -d

2. Test database migrations:

bash
# Start only the migrations database
docker compose -f docker/docker-compose.yml up -d db_migrations

# Run migrations
alembic -c alembic-migrations.ini upgrade head

3. Access the application:

• API: http://localhost:8000
• HAProxy: http://localhost:80

Troubleshooting

Database Connection Issues

bash
# Check database logs
docker compose -f docker/docker-compose.yml logs db

# Check if database is healthy
docker compose -f docker/docker-compose.yml ps

Migration Issues

bash
# Check migrations database logs
docker compose -f docker/docker-compose.yml logs db_migrations

# Reset migrations database
docker compose -f docker/docker-compose.yml stop db_migrations
docker compose -f docker/docker-compose.yml rm -f db_migrations
docker compose -f docker/docker-compose.yml up -d db_migrations

Application Issues

bash
# Check application logs
docker compose -f docker/docker-compose.yml logs gps

# Restart application
docker compose -f docker/docker-compose.yml restart gps

Best Practices

1. Always test migrations on the migrations database before applying to production
2. Use the provided docker-compose setup for consistent environments
3. Keep your .env file secure and never commit it to version control
4. Regularly check logs for potential issues
5. Use health checks to ensure service availability

Maintenance

Backup Database

bash
docker compose -f docker/docker-compose.yml exec db \
  mysqldump -u${DB_USER} -p${DB_PASSWORD} ${DB_NAME} > backup.sql

Restore Database

bash
docker compose -f docker/docker-compose.yml exec -T db \
  mysql -u${DB_USER} -p${DB_PASSWORD} ${DB_NAME} < backup.sql