docker-project-foundations

# Docker Project Foundations ## Overview This skill guides you in Dockerizing a project from scratch. It focuses on creating the initial Docker file set, choosing a sane layout, and preferring containerized dependencies over host-level installs. ## When to use this skill Activate this skill when: - A user asks you to set up, initialize, or Dockerize a project - A project needs an initial `Dockerfile`, `compose.yaml`, or `.dockerignore` and does not have one - A user wants to add a service dependency (database, cache, message queue) to a project - A user asks how to run or develop a project locally and Docker is available ## Do not use this skill when Do not use this skill when: - The user explicitly wants to avoid Docker - The project already has a mature Docker setup and only needs minor edits - The main task is optimizing an existing `Dockerfile` - The main task is editing or debugging an existing Compose stack ## Core guidance ### Always create these three files When Dockerizing a project, always produce all three: 1. **`.dockerignore`** — Create this first so the initial build context is small and safe. See `assets/dockerignore-example` for a reference. 2. **`Dockerfile`** — Create a working starter image definition that the project can build and run with. See `assets/Dockerfile.simple`. 3. **`compose.yaml`** — Create a local development stack that includes the application service and any required dependencies. See `assets/compose-dev.yaml`. ### npm registry credentials - Exclude `.npmrc` at every depth with `**/.npmrc` in `.dockerignore`; otherwise a broad source copy can persist credentials in image layers. - The Node.js starter mounts `npmrc` as a BuildKit secret for both `npm ci` steps. Public-package builds need no secret. For private registries, pass the config explicitly: ```bash DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src="$HOME/.npmrc" . ``` Use the actual config path if the project keeps it elsewhere. Never copy the credential file or pass its values through `ARG` or `ENV`. Dependency scripts run during installation can access the mounted secret; use trusted dependencies and a least-privilege registry token. - For private-registry builds through Compose, add this optional override as `compose.npm.yaml` alongside the starter's `compose.yaml`: ```yaml services: app: build: secrets: - npmrc secrets: npmrc: file: ${NPMRC_PATH:?Set NPMRC_PATH to your npm config file} ``` Build with `NPMRC_PATH="$HOME/.npmrc" docker compose -f compose.yaml -f compose.npm.yaml build`. This grants build-time access only, not a runtime secret. Public-package builds should omit the override so no credential file is required. ### Prefer Dockerized dependencies over host installs When a project needs a database (Postgres, MySQL, MongoDB), cache (Redis, Memcached), queue (RabbitMQ, Kafka), or any other infrastructure service: - **Always** define it as a service in `compose.yaml` instead of telling the user to install it on the host. - **Never** suggest `brew install postgres`, `apt install redis`, or similar host-level installs for development dependencies. - Use official Docker images from Docker Hub for these services. - Configure services with environment variables, not config files baked into images. ### Bootstrap checklist - Name the file `compose.yaml` rather than legacy Compose filenames. - Put all three files at the project root unless there is a clear multi-service layout that justifies a `docker/` subdirectory. - Ensure the initial setup can build and start locally with one command path. - Bind published application ports to loopback by default. Widen the host address only when another device must reach the development service. - Keep unauthenticated datastores on the Compose network instead of publishing their ports. If local host tools require database access, publish only to loopback. - If a development-only credential fallback enables one-command startup, label it clearly and document a `.env` override. - Use Compose services for local databases, caches, and queues instead of host installs. - Keep the first scaffold simple; defer detailed image optimization and advanced Compose tuning to the owning skills. ### Development vs production - Development: Use bind mounts for live reload, publish application ports on loopback by default, and enable verbose logging. Keep unauthenticated datastores on the Compose network; publish a datastore port only on loopback when local host tools require it. - Production: Use multi-stage builds, copy only built artifacts, do not mount source code, minimize image layers, set appropriate resource limits. - Keep a single `Dockerfile` that supports both via build stages and build arguments when possible. ### File placement - Place `Dockerfile` at the project root (or in a `docker/` subdirectory if the project has multiple services). - Place `compose.yaml` at the project root. - Place `.dockerignore` at the project root, next to the `Dockerfile`. ## Related skills - For Dockerfile optimization, cache strategy, non-root execution, and image hardening, use `docker-build-strategies`. - For service dependencies, health checks, overrides, volumes, networks, and Compose debugging, use `docker-compose-patterns`. - For destructive Docker CLI commands (`docker system prune`, `docker rm -f`, image/network/builder pruning) and a cross-product index of destructive-command guardrails, use `docker-destructive-guardrails`. ## References - `references/project-structure.md` — Detailed guidance on Docker project file organization, naming conventions, and multi-service layouts. ## Assets - `assets/dockerignore-example` — A comprehensive `.dockerignore` for a typical project. - `assets/compose-dev.yaml` — A development-oriented Compose file with Dockerized dependencies. - `assets/Dockerfile.simple` — A basic multi-stage Dockerfile following best practices. ## Scripts - **`scripts/verify-setup.sh`** — Checks that required files exist in the current directory and validates its `compose.yaml`. Run it from the project root, with the script path resolved under this skill's directory: ```bash bash "<skill-dir>/scripts/verify-setup.sh" [--help] ``` Replace `<skill-dir>` with the absolute path of the folder that contains this `SKILL.md`; the `scripts/` path is relative to that folder, not to the project. Do not change into the skill directory first: the script checks the current directory. If the skill directory cannot be resolved, check that `.dockerignore`, `Dockerfile`, and `compose.yaml` exist in the project root, then run `docker compose config --quiet`. Exit status is `0` when verification succeeds or help is requested, `1` when required files are missing or the Compose configuration is invalid, and `2` for invalid arguments. ## Checks - `checks/verification.md` — Detailed verification checklist for manual review.