docker-project-foundations
Use this skill when setting up, initializing, or Dockerizing a project, even if the user doesn't explicitly mention Docker but describes a need for containerized local development, adding a database or cache dependency, or running services without host-level installs. Covers Dock
Install
npx skills add https://github.com/docker/skills/tree/main/skills/docker-project-foundations
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install docker-skills@llmmart
git clone https://github.com/docker/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole docker/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.dockerignoreand 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:
.dockerignore— Create this first so the initial build context is small and safe. Seeassets/dockerignore-examplefor a reference.Dockerfile— Create a working starter image definition that the project can build and run with. Start fromassets/Dockerfile.simpleand keep its baseline, even for a first scaffold:- multi-stage build (dependencies, build, and a separate runtime stage) whenever the project has a build or dependency-install step;
- base image pinned to a specific version (e.g.
node:22-slim), neverlatest; - dependency manifests (
package.json+ lockfile) copied before the source for layer caching; - a non-root
USERset in the final stage beforeCMD/ENTRYPOINT.
compose.yaml— Create a local development stack that includes the application service and any required dependencies. Seeassets/compose-dev.yaml.
npm registry credentials
- Exclude
.npmrcat every depth with**/.npmrcin.dockerignore; otherwise a broad source copy can persist credentials in image layers. - The Node.js starter mounts
npmrcas a BuildKit secret for bothnpm cisteps. Public-package builds need no secret. For private registries, pass the config explicitly:
Use the actual config path if the project keeps it elsewhere. Never copy the credential file or pass its values throughDOCKER_BUILDKIT=1 docker build --secret id=npmrc,src="$HOME/.npmrc" .ARGorENV. 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.yamlalongside the starter'scompose.yaml:
Build withservices: app: build: secrets: - npmrc secrets: npmrc: file: ${NPMRC_PATH:?Set NPMRC_PATH to your npm config file}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.yamlinstead 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.yamlrather 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
.envoverride. - 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. "Simple" never means dropping the Dockerfile baseline above (multi-stage, pinned base, non-root
USER).
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
Dockerfilethat supports both via build stages and build arguments when possible.
File placement
- Place
Dockerfileat the project root (or in adocker/subdirectory if the project has multiple services). - Place
compose.yamlat the project root. - Place
.dockerignoreat the project root, next to theDockerfile.
Related skills
- For Dockerfile optimization, cache strategy, advanced non-root hardening, and image hardening, use
docker-build-strategies. The starter baseline above (including a non-rootUSER) still applies here. - 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, usedocker-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.dockerignorefor 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 itscompose.yaml. Run it from the project root, with the script path resolved under this skill's directory:
Replacebash "<skill-dir>/scripts/verify-setup.sh" [--help]<skill-dir>with the absolute path of the folder that contains thisSKILL.md; thescripts/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, andcompose.yamlexist in the project root, then rundocker compose config --quiet. Exit status is0when verification succeeds or help is requested,1when required files are missing or the Compose configuration is invalid, and2for invalid arguments.
Checks
checks/verification.md— Detailed verification checklist for manual review.
Files (skills)
-
agents
-
openai.yaml 269 B
Loading…
-
-
assets
-
compose-dev.yaml 1.5 KB
Loading… -
Dockerfile.simple 959 B · in bundle
-
dockerignore-example 654 B · in bundle
-
-
checks
-
verification.md 4.1 KB
Loading…
-
-
evals
-
docker-project-foundations.md 6.8 KB
Loading…
-
-
references
-
project-structure.md 3.3 KB
Loading…
-
-
scripts
-
verify-setup.sh 1.1 KB
Loading…
-
-
SKILL.md 7.9 KB
--- name: docker-project-foundations description: Use this skill when setting up, initializing, or Dockerizing a project, even if the user doesn't explicitly mention Docker but describes a need for containerized local development, adding a database or cache dependency, or running services without host-level installs. Covers Dockerfile, compose.yaml, and .dockerignore creation with Docker best practices. license: Apache-2.0 compatibility: Requires Docker 20.10+ and Docker Compose v2. --- # 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. Start from `assets/Dockerfile.simple` and keep its baseline, even for a first scaffold: - multi-stage build (dependencies, build, and a separate runtime stage) whenever the project has a build or dependency-install step; - base image pinned to a specific version (e.g. `node:22-slim`), never `latest`; - dependency manifests (`package.json` + lockfile) copied before the source for layer caching; - a non-root `USER` set in the final stage before `CMD`/`ENTRYPOINT`. 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. "Simple" never means dropping the Dockerfile baseline above (multi-stage, pinned base, non-root `USER`). ### 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, advanced non-root hardening, and image hardening, use `docker-build-strategies`. The starter baseline above (including a non-root `USER`) still applies here. - 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. -
skill.yaml 853 B
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.