Skip to content

docker-workflow.md

Latest commit

 

History

History
222 lines (145 loc) · 3.5 KB

docker-workflow.md

File metadata and controls

222 lines (145 loc) · 3.5 KB
Raw

Docker Workflow

This guide describes how to use Docker and Docker Compose for development with DocGen.

Why Use Docker?

Docker provides:

  • Consistent development environment
  • Isolation from local system
  • Easy to reproduce issues
  • Same environment as CI/CD

Docker Images

The project builds multiple Docker images:

Make resolves the reviewed version from app/doc_gen/__version__.py before a local development or production build and supplies it to setuptools-scm as a Docker build argument. This is required because .git is intentionally absent from the Docker build context. You can override the value for a reviewed build, for example make c-build-prod DOC_GEN_BUILD_VERSION=1.0.2.

Image Description
doc-gen:latest Base image
doc-gen-dev:latest Development image
doc-gen-prod:latest Production image

Building Images

Build Base Image

make d-build-base

Build Development Image

make d-build-dev

Build Production Image

make d-build-prod

Build All Images

make d-build-all

Running Containers

Run Tests in Docker

make d-test

Run Structure Generate in Docker

make d-generate
make d-generate-smart

Run Structure Print in Docker

make d-print
make d-print-smart

Run Analysis in Docker

make d-analyze

Docker Compose

Start Development Environment

make c-up

Start in Background

make c-up-detached

Stop Environment

make c-down

View Logs

make c-logs

Common Compose Commands

Run Commands via Compose

# Initialize
make c-init

# Generate
make c-generate

# Print
make c-print

# Analyze
make c-analyze

Quality Assurance

# Run formatting
make c-format

# Run linter
make c-lint

# Run tests
make c-test

# Run full check
make c-check

Full CI Workflow

make c-ci

Using Makefile

The Makefile provides convenient shortcuts:

# See all available commands
make help

See make-workflow.md for grouped local, Docker, Compose, and published utility image commands.

Troubleshooting

Published release tags

Stable production releases publish four coordinated references to the same image: exact v1.0.2, minor v1.0, major v1, and latest. Pin CI and reproducible automation to the immutable exact tag. The other aliases move only when a compatible stable release is published. Prereleases such as v1.0.0-rc.1 publish only their exact tag.

GitHub and GitLab enforce the same alias and prerelease policy. See the CI/CD and release contract for publication safeguards.

Docker not installed

Install Docker Desktop from https://www.docker.com/products/docker-desktop

Container not running

Check Docker is running:

docker info

Build fails

Try rebuilding:

docker compose build --no-cache

Related Documentation