dockerize-service

Skill: dockerize-service

Core position

This skill produces a local-development Docker Compose setup that reflects the project as-is. It does not introduce backing services the repo doesn't already use, and it does not create a second Docker pattern if one already exists.

---

Trigger

Use this skill when the user wants to:

• Containerize an existing Python project
• Add Docker Compose to a project
• Add a Dockerfile to a project
• "Dockerize" a service

---

Variables

• {pkg_name} — snake_case package name (matches the project directory and Python package)
• {PKG_NAME}_ — env var prefix, only used if a pydantic-settings env_prefix is detected in the repo (e.g., MY_SERVICE_); otherwise plain names are used

---

Step 1 — Inspect the repo

Inspect before asking. Work through each check in order and record findings.

1. Check for existing Docker artifacts

Look for Dockerfile, docker-compose.yml, docker-compose.yaml, .dockerignore. If any are present, extend them — do not create a competing setup. Note what was found.

2. Check for repo tooling

• uv.lock present → uv-native project; use uv base image in Dockerfile
• No uv.lock → pip-based project; use python:3.12-slim with pip install

3. Check for service signals

Inspect pyproject.toml dependencies and any settings/config files for:

• sqlalchemy + a non-sqlite database URL pattern, or psycopg, psycopg2, asyncpg in deps → Postgres
• redis in deps → Redis
• No signals → app-only (do not add Postgres as a default)

If Postgres is signaled, also note which driver is already present (psycopg2-binary, psycopg[binary], asyncpg, etc.) — this determines what to add in Step 6.

4. Check for an existing health endpoint

Grep routes for /health, /healthz, /ping, /api/v1/health, or similar. Record the exact path if found.

5. Detect app entrypoint

Look for the ASGI app object in {pkg_name}/main.py, {pkg_name}/app.py, or {pkg_name}/application.py. Record the module path (e.g., {pkg_name}.main:app). Also check [project.scripts] in pyproject.toml for any uvicorn/gunicorn invocations. This becomes the CMD in the Dockerfile — default to {pkg_name}.main:app only if no entrypoint is found elsewhere.