Add Docker and Docker Compose support for development and deployment

[Bhup-GitHUB]

Description

Issue #139

Add Docker and Docker Compose support to make it easier for developers to get started with the project and to simplify deployment. This provides a consistent development environment across different platforms and streamlines the deployment process.

Changes Made

New Files

• Dockerfile - Multi-stage production build (Go 1.24 + Alpine 3.21)
• Dockerfile.dev - Development image with Air live reload and Delve debugger
• .dockerignore - Excludes unnecessary files from Docker build context
• docker-compose.yml - Production configuration with volumes and health check
• docker-compose.dev.yml - Development setup with source mounting
• config.docker.json - Docker-specific config with /app/data/gtfs.db path for persistence
• .air.docker.toml - Air configuration for Docker development environment

Modified Files

• Makefile - Added Docker targets (docker-build, docker-run, docker-compose-up, etc.)
• README.markdown - Added comprehensive Docker documentation
• CLAUDE.md - Added Docker commands reference

Testing & Verification

All acceptance criteria from the issue have been verified:

Test 1: docker build -t maglev . completes successfully

Test 2: docker run -p 4000:4000 maglev starts the server

Test 3: docker-compose up works correctly

Test 4: API accessible at http://localhost:4000/api/where/current-time.json?key=test

Test 5: Configuration can be modified via mounted volumes

Test 6: GTFS database persists across container restarts

Test 7: Health check returns healthy status

Test 8: Logs output to stdout/stderr correctly

Test 9: Image size is optimized (multi-stage build)

How to Use

Quick Start (Production)

docker-compose up### Development with Live Reload
docker-compose -f docker-compose.dev.yml up### Manual Docker Commands
docker build -t maglev .
docker run -p 4000:4000 -v $(pwd)/config.docker.json:/app/config.json:ro -v maglev-data:/app/data maglev## Checklist

• Dockerfile created with multi-stage build
• .dockerignore file created
• docker-compose.yml created for production
• docker-compose.dev.yml created for development
• README.markdown updated with Docker instructions
• CLAUDE.md updated with Docker information
• Makefile includes Docker targets
• Docker build completes successfully
• Application runs correctly in Docker container
• Health check works properly
• Volumes are properly configured for data persistence
• Documentation is clear and complete

[CLAassistant]

All committers have signed the CLA.

[Bhup-GitHUB]

hey @aaronbrethorst can you review the PR and let me know if you need any changes?

[aaronbrethorst]

Hey! Thanks for putting together this Docker support PR — this is a really valuable addition to the project. The overall architecture is solid: the multi-stage build, non-root user setup, and volume configuration in docker-compose.yml all follow best practices. Nice work on the comprehensive documentation too!

I did find a few issues that we'll need to address before merging. Nothing major conceptually, but they would cause problems for users trying to follow the documented workflows.

---

Issues to Fix

1. make docker-run has a few problems

In Makefile, the docker-run target needs some adjustments:

docker-run: docker-build
	docker run -p 4000:4000 -v $(PWD)/config.json:/app/config.json:ro maglev

What needs to change:

• Add --name maglev — Without this, the docker-stop target won't work since it tries to stop a container named maglev
• Use config.docker.json instead of config.json — The docker-compose.yml correctly uses config.docker.json which has the right data-path setting (/app/data/gtfs.db). Using config.json would write the database to /app/gtfs.db which the non-root user may not have permission to write to
• Add the data volume — Without -v maglev-data:/app/data, the database won't persist when the container is removed

Here's what it should look like:

docker-run: docker-build
	docker run --name maglev -p 4000:4000 \
		-v $(PWD)/config.docker.json:/app/config.json:ro \
		-v maglev-data:/app/data maglev

---

2. Default command in Dockerfile.dev uses wrong Air config

In Dockerfile.dev, the CMD uses .air.toml:

CMD ["air", "-c", ".air.toml"]

This should be .air.docker.toml instead. The docker-compose.dev.yml overrides this correctly, but if someone runs the Dockerfile directly without compose, they'll get errors because .air.toml doesn't include the -f config.docker.json flag.

---

3. README references a Makefile target that doesn't exist

In README.markdown, there's a reference to make schema:

`make schema` - Dump the DB's SQL schema to a file for sqlc.

The Makefile doesn't have a schema target — I think this line should either be removed or changed to reference make models.

4. Health check API key

The health checks in the Dockerfile and both docker-compose files assume key=test is a valid API key. If someone changes their API keys and forgets to update the health check, their container will restart indefinitely.

Maybe add a note in the README about this? Something like: "Note: The health check uses key=test. If you change your API keys, update the health check command accordingly."

5. config.docker.json ships with production mode

The file has "env": "production" but "api-keys": ["test"]. This is fine for getting started, but might be worth a comment in the file or docs reminding users to change the API keys before deploying.

---

Once the issues above are fixed, this PR is good to go! The core Docker setup is well done — these are just some small gaps in the Makefile and Dockerfile.dev that would trip up users.

Thanks again for the contribution!