docker-project-foundations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Project Foundations

Docker项目基础

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.

本技能指导你从零开始Docker化项目。重点在于创建初始Docker文件集、选择合理的布局，并优先使用容器化依赖而非主机级安装。

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

在以下情况激活此技能：

用户要求你设置、初始化或Docker化一个项目
项目需要初始的
```
Dockerfile
```
、
```
compose.yaml
```
或
```
.dockerignore
```
，但尚未有这些文件
用户想为项目添加服务依赖（数据库、缓存、消息队列）
用户询问如何在本地运行或开发项目，且Docker可用

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

在以下情况不要使用此技能：

用户明确希望避免使用Docker
项目已有成熟的Docker配置，只需小幅修改
主要任务是优化现有的
```
Dockerfile
```
主要任务是编辑或调试现有的Compose栈

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. See
```
assets/dockerignore-example
```
for a reference.
Dockerfile
— Create a working starter image definition that the project can build and run with. See
```
assets/Dockerfile.simple
```
.
compose.yaml
— Create a local development stack that includes the application service and any required dependencies. See
```
assets/compose-dev.yaml
```
.

Docker化项目时，始终生成全部三个文件：

.dockerignore
— 首先创建它，使初始构建上下文小而安全。参考
```
assets/dockerignore-example
```
。
Dockerfile
— 创建一个可用的起始镜像定义，项目可以据此构建和运行。参考
```
assets/Dockerfile.simple
```
。
compose.yaml
— 创建一个本地开发栈，包含应用服务和任何必需的依赖。参考
```
assets/compose-dev.yaml
```
。

npm registry credentials

npm registry凭据

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.

在
```
.dockerignore
```
中使用
```
**/.npmrc
```
排除所有层级的
```
.npmrc
```
；否则，广泛的源文件复制可能会将凭据持久化在镜像层中。
Node.js起始模板将
```
npmrc
```
作为BuildKit secret挂载，用于两个
```
npm ci
```
步骤。公共包构建不需要secret。对于私有registry，显式传递配置：
bash
```
DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src="$HOME/.npmrc" .
```
如果项目将配置文件放在其他地方，请使用实际的配置路径。切勿复制凭据文件或通过
```
ARG
```
或
```
ENV
```
传递其值。安装期间运行的依赖脚本可以访问挂载的secret；请使用受信任的依赖和最小权限的registry令牌。

对于通过Compose进行的私有registry构建，可在起始模板的

compose.yaml

旁添加此可选覆盖文件

compose.npm.yaml

：

yaml

services:
  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

构建。这仅授予构建时访问权限，而非运行时secret。公共包构建应省略此覆盖文件，这样就不需要凭据文件。

Prefer Dockerized dependencies over host installs

优先使用Dockerized依赖而非主机安装

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.

当项目需要数据库（Postgres、MySQL、MongoDB）、缓存（Redis、Memcached）、队列（RabbitMQ、Kafka）或任何其他基础设施服务时：

始终将其定义为
```
compose.yaml
```
中的服务，而不是告诉用户在主机上安装它。
切勿推荐
```
brew install postgres
```
、
```
apt install redis
```
或类似的主机级开发依赖安装。
对这些服务使用来自Docker Hub的官方Docker镜像。
使用环境变量配置服务，而不是烘焙到镜像中的配置文件。

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.

将文件命名为
```
compose.yaml
```
，而不是旧的Compose文件名。
将三个文件放在项目根目录，除非有明确的多服务布局证明
```
docker/
```
子目录合理。
确保初始设置可以通过一条命令路径在本地构建和启动。
默认将已发布的应用端口绑定到loopback。仅当其他设备需要访问开发服务时才放宽主机地址。
将未认证的数据存储保留在Compose网络上，而不是发布其端口。如果本地主机工具需要访问数据库，仅发布到loopback。
如果仅开发时使用的凭据回退机制支持一键启动，请明确标记并记录
```
.env
```
覆盖。
使用Compose服务来运行本地数据库、缓存和队列，而不是主机安装。
保持初始脚手架简单；将详细的镜像优化和高级Compose调优留给对应的技能。

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.

开发环境：使用绑定挂载实现实时重载，默认在loopback上发布应用端口，并启用详细日志。将未认证的数据存储保留在Compose网络上；仅当本地主机工具需要时，才在loopback上发布数据存储端口。
生产环境：使用多阶段构建，只复制构建产物，不挂载源代码，最小化镜像层数，设置适当的资源限制。
尽可能保持一个支持开发和生产环境的
```
Dockerfile
```
，通过构建阶段和构建参数实现。

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
```
.

将
```
Dockerfile
```
放在项目根目录（如果项目有多个服务，则放在
```
docker/
```
子目录）。
将
```
compose.yaml
```
放在项目根目录。
将
```
.dockerignore
```
放在项目根目录，与
```
Dockerfile
```
相邻。

Related skills

References

参考资料

```
references/project-structure.md
```
— Detailed guidance on Docker project file organization, naming conventions, and multi-service layouts.

```
references/project-structure.md
```
— 关于Docker项目文件组织、命名约定和多服务布局的详细指导。

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.

assets/dockerignore-example

— 一个典型项目的完整

.dockerignore

。

```
assets/compose-dev.yaml
```
— 一个面向开发的Compose文件，包含Docker化依赖。
```
assets/Dockerfile.simple
```
— 一个遵循最佳实践的基础多阶段Dockerfile。

Scripts

脚本

scripts/verify-setup.sh
— Checks required files exist and validates
```
compose.yaml
```
.
bash
```
bash scripts/verify-setup.sh [--help]
```
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.

scripts/verify-setup.sh
— 检查必需文件是否存在并验证
```
compose.yaml
```
。
bash
```
bash scripts/verify-setup.sh [--help]
```
验证成功或请求帮助时退出状态为
```
0
```
，必需文件缺失或Compose配置无效时为
```
1
```
，参数无效时为
```
2
```
。

Checks

检查清单

```
checks/verification.md
```
— Detailed verification checklist for manual review.

```
checks/verification.md
```
— 供手动审查的详细验证检查清单。