feat(new tools): Docker Compose/file/Swarm Cheatsheet

Fix #170
This commit is contained in:
ShareVB committed 2025-08-18 22:32:39 +02:00
1 parent acc5ab5f13
commit e20b284fba
9 files changed
+1058

No files matched your search

@@ -0,0 +1,32 @@
<script setup lang="ts">
import { useThemeVars } from 'naive-ui';
import Memo from './docker-compose.md';
const themeVars = useThemeVars();
</script>
<template>
<div>
<Memo style="overflow-x: auto;" />
</div>
</template>
<style lang="less" scoped>
::v-deep(pre) {
margin: 0;
padding: 15px 22px;
background-color: v-bind('themeVars.cardColor');
border-radius: 4px;
overflow: auto;
}
::v-deep(table) {
border-collapse: collapse;
}
::v-deep(table), ::v-deep(td), ::v-deep(th) {
border: 1px solid v-bind('themeVars.textColor1');
padding: 5px;
}
::v-deep(a) {
color: v-bind('themeVars.textColor1');
}
</style>
@@ -0,0 +1,465 @@
Docker Compose is a powerful tool for defining and running multi-container Docker applications. It uses a YAML file (`docker-compose.yml`) to configure application services, networks, volumes, and more. This file allows developers to declaratively describe infrastructure and dependencies, making it easier to manage complex environments.
Whether you're building a local dev stack or deploying to production, Compose simplifies orchestration and keeps your configuration readable and version-controlled.
## 📁 File Name
```yaml
docker-compose.yml
```
### ✅ YAML Formatting Rules
- Use **2 spaces** for indentation (not tabs)
- Keys and values are **case-sensitive**
- Lists use `-` for each item
- Strings with special characters should be quoted
- Environment variables can be defined inline or via `.env` files
## 🧱 Basic Structure
```yaml
version: '3.8' # Compose file version
services:
service_name:
image: image_name:tag
build:
context: .
dockerfile: Dockerfile
ports:
- "host_port:container_port"
volumes:
- ./host_path:/container_path
environment:
- VAR_NAME=value
depends_on:
- other_service
networks:
- custom_network
networks:
custom_network:
driver: bridge
volumes:
custom_volume:
```
## ⚙️ Services
Each service defines a container.
### Common Service Options
```yaml
services:
web:
image: nginx:latest
build:
context: ./app
dockerfile: Dockerfile
command: ["nginx", "-g", "daemon off;"]
container_name: custom_name
ports:
- "8080:80"
expose:
- "80"
environment:
- DEBUG=true
env_file:
- .env
volumes:
- ./data:/data
restart: always
depends_on:
- db
networks:
- frontend
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 10s
retries: 5
```
## 🏗️ Build Options
```yaml
build:
context: ./dir
dockerfile: Dockerfile
args:
build_arg: value
target: build-stage
```
- **`build:`** Tells Compose how to build the image.
- `context:` is the directory containing the Dockerfile and source code.
- `dockerfile:` lets you specify a custom Dockerfile name or path.
## 📦 Volumes
```yaml
volumes:
data_volume:
driver: local
driver_opts:
type: none
device: /path/on/host
o: bind
```
### Mounting Volumes
```yaml
volumes:
- data_volume:/app/data
- ./local:/container/path
```
- **`volumes:`** Mounts host directories or named volumes into the container.
- `./src:/app/src` mounts the local `src` folder into the container at `/app/src`.
## 🌐 Networks
```yaml
networks:
frontend:
driver: bridge
backend:
driver: overlay
```
- **`networks:`** Connects the service to one or more custom networks. Enables service discovery and isolation.
### Assigning Networks to Services
```yaml
services:
app:
networks:
- frontend
- backend
```
## 🌐 Ports
```yaml
ports:
- "3000:3000"
```
- **`ports:`** Maps container ports to host ports. Format is `"host:container"`. Useful for exposing services to your local machine.
## 🔐 Secrets (Docker Swarm only)
```yaml
secrets:
db_password:
file: ./db_password.txt
services:
db:
secrets:
- db_password
```
## 🔑 Configs (Docker Swarm only)
```yaml
configs:
my_config:
file: ./config.txt
services:
app:
configs:
- source: my_config
target: /etc/config.txt
```
## 🧪 Healthcheck
```yaml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 10s
retries: 3
start_period: 5s
```
- **`healthcheck:`** Defines how Docker checks if the container is healthy.
- `test:` is the command to run
- `interval:` how often to run the check
- `timeout:` how long to wait for a response
- `retries:` how many failures before marking unhealthy
## 🔄 Restart Policies
```yaml
restart: no # Never restart
restart: always # Always restart
restart: on-failure # Restart on failure
restart: unless-stopped
```
## 🧬 Environment Variables
```yaml
environment:
- VAR1=value1
- VAR2=value2
env_file:
- .env
```
- **`environment:`** Sets environment variables inside the container. Useful for configuration.
- **`env_file:`** Loads environment variables from a file. Keeps secrets and config separate from the Compose file.
## Command
```yaml
command: npm start
```
- **`command:`** Overrides the default command defined in the Dockerfile. Useful for customizing container behavior.
## Dependencies
```yaml
depends_on:
- db
```
- **`depends_on:`** Specifies service startup order. In Compose, this does not wait for the service to be "ready"—just started.
## 🧹 Clean Up
```bash
docker-compose down # Stop and remove containers, networks, volumes
docker-compose down -v # Also remove named volumes
```
## 🚀 Commands
| Command | Description |
|--------|-------------|
| `docker-compose up` | Start services |
| `docker-compose up -d` | Start in detached mode |
| `docker-compose down` | Stop and remove services |
| `docker-compose build` | Build images |
| `docker-compose ps` | List containers |
| `docker-compose logs` | View logs |
| `docker-compose exec <service> <cmd>` | Run command in container |
| `docker-compose config` | Validate and view config |
## 🧠 Mounting GPU / iGPU
Docker Compose supports GPU access via the `device_requests` field (Compose v3.8+ and Docker 19.03+).
### ✅ NVIDIA GPU Example
```yaml
services:
gpu-app:
image: nvidia/cuda:11.0-base
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
```
### ✅ Intel iGPU (via VAAPI or OpenCL)
```yaml
services:
igpu-app:
image: intel/openvino
devices:
- /dev/dri:/dev/dri
```
> 🔧 Make sure your host has the necessary drivers and runtime (e.g., NVIDIA Container Toolkit or Intel Media SDK).
## 🔄 Compose vs Swarm YAML Differences
| Feature | Docker Compose (`docker-compose.yml`) | Docker Swarm (`stack.yml`) |
|--------------------|----------------------------------------|-----------------------------|
| `restart` | ✅ Supported | ❌ Not supported |
| `depends_on` | ✅ Supported | ❌ Not supported |
| `deploy` | ❌ Ignored | ✅ Required for replicas |
| `build` | ✅ Supported | ❌ Not supported |
| `volumes` (bind) | ✅ Supported | ✅ Supported |
| `configs`/`secrets`| ❌ Ignored | ✅ Supported |
| `healthcheck` | ✅ Supported | ✅ Supported |
> 🧠 **Tip:** Use `docker-compose.yml` for local development and `stack.yml` for Swarm deployments.
## 🧬 Profiles (Compose v3.9+)
Profiles allow conditional inclusion of services based on the active profile. This is useful for separating dev/test/staging environments.
### ✅ Defining Profiles
```yaml
services:
web:
image: nginx
profiles:
- default
debug:
image: busybox
command: top
profiles:
- debug
```
### ✅ Activating Profiles
```bash
docker compose --profile debug up
```
### ✅ Notes
- Services without a `profiles` key are always included.
- Multiple profiles can be activated simultaneously.
- Useful for feature toggles, optional services, or environment-specific setups.
## ⚔️ YAML Differences: Docker Compose vs Docker Swarm Mode
Docker Compose and Docker Swarm both use YAML files to define services, but they serve different purposes and support different features. Compose is optimized for local development and testing, while Swarm is designed for production-grade orchestration across clusters.
### 🧭 Purpose
| Mode | Use Case |
|-------------|-----------------------------------|
| Compose | Local development, testing |
| Swarm | Cluster deployment, scaling |
### 🧩 Key Differences in YAML Structure
| Feature | Compose (`docker-compose.yml`) | Swarm (`stack.yml`) |
|----------------------|-------------------------------|----------------------|
| `version:` | ✅ Required (e.g. `3.8`) | ❌ Optional / Ignored |
| `build:` | ✅ Supported | ❌ Ignored |
| `restart:` | ✅ Supported | ❌ Ignored |
| `depends_on:` | ✅ Supported | ❌ Ignored |
| `deploy:` | ❌ Ignored | ✅ Required for scaling, placement |
| `configs:` | ❌ Ignored | ✅ Supported |
| `secrets:` | ❌ Ignored | ✅ Supported |
| `healthcheck:` | ✅ Supported | ✅ Supported |
| `volumes:` (bind) | ✅ Supported | ✅ Supported |
| `networks:` | ✅ Supported | ✅ Supported |
| `profiles:` | ✅ Supported (v3.9+) | ❌ Not supported |
### 🔧 Compose-Only Features
These features are useful for local development but are ignored in Swarm:
#### `build:`
```yaml
services:
app:
build:
context: .
dockerfile: Dockerfile
```
- Compose builds images locally.
- Swarm requires pre-built images pushed to a registry.
#### `restart:`
```yaml
restart: unless-stopped
```
- Compose uses this to auto-restart containers.
- Swarm uses `deploy.restart_policy` instead.
#### `depends_on:`
```yaml
depends_on:
- db
```
- Compose starts services in order.
- Swarm ignores this; use healthchecks and wait-for-it scripts.
### 🛡️ Swarm-Only Features
These features are exclusive to Swarm and ignored by Compose:
#### `deploy:`
```yaml
services:
app:
deploy:
replicas: 3
placement:
constraints:
- node.role == manager
restart_policy:
condition: on-failure
```
- Controls scaling, placement, and restart behavior in a cluster.
#### `configs:` and `secrets:`
```yaml
configs:
app_config:
file: ./config.yml
secrets:
db_password:
file: ./password.txt
```
- Used to securely distribute configuration and secrets across nodes.
#### `placement:` (inside `deploy`)
```yaml
placement:
constraints:
- node.labels.env == production
```
- Assigns services to specific nodes based on labels.
### 🧪 Healthchecks (Supported in Both)
```yaml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 10s
retries: 3
```
- Works in both Compose and Swarm.
- In Swarm, health status can influence service rescheduling.
### 📦 Volume Differences
| Type | Compose | Swarm |
|-------------|---------|-------|
| Bind mount | ✅ | ✅ |
| Named volume| ✅ | ✅ |
| External volume | ✅ | ✅ |
| Volume driver options | ✅ | ✅ |
Swarm requires external volumes to be pre-created on all nodes.
### 🧠 Summary
| Feature Category | Compose | Swarm |
|----------------------|---------|-------|
| Local builds | ✅ | ❌ |
| Cluster scaling | ❌ | ✅ |
| Secrets/configs | ❌ | ✅ |
| Profiles | ✅ | ❌ |
| Restart policies | ✅ | ✅ (via `deploy`) |
| Service dependencies | ✅ | ❌ |
> 🧭 **Tip:** Use `docker-compose.yml` for development and `stack.yml` for Swarm. You can split your configuration into multiple files or use tools like `kompose` to convert Kubernetes manifests.
## 📚 Resources
- [Compose File Reference](https://docs.docker.com/compose/compose-file/)
- [Docker CLI Reference](https://docs.docker.com/engine/reference/commandline/compose/)
- [NVIDIA GPU Support](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
- [Intel GPU Support](https://github.com/intel/media-driver)
+13
View File
@@ -0,0 +1,13 @@
import { BrandDocker } from '@vicons/tabler';
import { defineTool } from '../tool';
export const tool = defineTool({
name: 'Docker Compose cheatsheet',
path: '/docker-compose-memo',
description: 'Docker Compose format cheatsheet',
keywords: ['docker', 'compose', 'memo', 'cheatsheet'],
component: () => import('./docker-compose-memo.vue'),
icon: BrandDocker,
createdAt: new Date('2025-08-17'),
category: 'Cheatsheets',
});
@@ -0,0 +1,32 @@
<script setup lang="ts">
import { useThemeVars } from 'naive-ui';
import Memo from './docker-swarm.md';
const themeVars = useThemeVars();
</script>
<template>
<div>
<Memo style="overflow-x: auto;" />
</div>
</template>
<style lang="less" scoped>
::v-deep(pre) {
margin: 0;
padding: 15px 22px;
background-color: v-bind('themeVars.cardColor');
border-radius: 4px;
overflow: auto;
}
::v-deep(table) {
border-collapse: collapse;
}
::v-deep(table), ::v-deep(td), ::v-deep(th) {
border: 1px solid v-bind('themeVars.textColor1');
padding: 5px;
}
::v-deep(a) {
color: v-bind('themeVars.textColor1');
}
</style>
+200
View File
@@ -0,0 +1,200 @@
**Docker Swarm Mode** is Docker’s native clustering and orchestration solution. It allows you to manage a group of Docker nodes as a single virtual system, enabling high availability, load balancing, and simplified deployment of containerized applications.
Key features:
- Built-in orchestration
- Declarative service model
- Rolling updates
- Auto-scaling and self-healing
- Secure node communication via TLS
## 📌 Swarm Initialization
- **Initialize Swarm**
```bash
docker swarm init
```
- **Join Swarm (on worker/manager node)**
```bash
docker swarm join-token worker
```
- **Leave Swarm**
```bash
docker swarm leave
```
- **Force Leave (on manager)**
```bash
docker swarm leave --force
```
## 👥 Node Management
- **List nodes**
```bash
docker node ls
```
- **Promote node to manager**
```bash
docker node promote <node-name>
```
- **Demote node to worker**
```bash
docker node demote <node-name>
```
- **Inspect node**
```bash
docker node inspect <node-name> --pretty
```
- **Drain node (prevent scheduling)**
```bash
docker node update --availability drain <node-name>
```
- **Activate node**
```bash
docker node update --availability active <node-name>
```
## 🧠 Manager Nodes
Manager nodes are responsible for:
- Orchestrating tasks and services
- Maintaining cluster state
- Handling API requests
You can have multiple managers for high availability, but only one is the **leader** at any time.
- **Check manager status**
```bash
docker node ls
```
- **View Raft consensus info**
```bash
docker swarm inspect
```
## 📦 Service Management
- **Create service**
```bash
docker service create --name <service-name> <image>
```
- **Create service with replicas**
```bash
docker service create --name <service-name> --replicas <n> <image>
```
- **List services**
```bash
docker service ls
```
- **Inspect service**
```bash
docker service inspect <service-name> --pretty
```
- **Scale service**
```bash
docker service scale <service-name>=<n>
```
- **Update service**
```bash
docker service update --image <new-image> <service-name>
```
- **Remove service**
```bash
docker service rm <service-name>
```
## 🔁 Replicas
Replicas define how many instances of a service should run across the swarm.
- **Set replicas when creating a service**
```bash
docker service create --replicas 5 --name myapp myimage
```
- **Scale replicas**
```bash
docker service scale myapp=10
```
Swarm automatically distributes replicas across available nodes and restarts them if they fail.
## 🐝 Task & Container Management
- **List tasks of a service**
```bash
docker service ps <service-name>
```
- **List all tasks**
```bash
docker node ps <node-name>
```
- **List containers**
```bash
docker container ls
```
- **Inspect container**
```bash
docker container inspect <container-id>
```
## 🌐 Networking
### 🧠 What Is an Overlay Network?
An overlay network is a virtual network that spans across multiple Docker hosts. It allows containers running on different nodes
### Commands
- **Create overlay network**
```bash
docker network create --driver overlay <network-name>
```
- **List networks**
```bash
docker network ls
```
- **Attach service to network**
```bash
docker service create --name <service-name> --network <network-name> <image>
```
## 🛠 Useful Flags
| Flag | Description |
|------|-------------|
| `--replicas` | Number of service instances |
| `--publish` | Port mapping (`<host>:<container>`) |
| `--mount` | Volume mounting |
| `--constraint` | Node placement rules |
| `--update-delay` | Delay between updates |
| `--limit-cpu` / `--limit-memory` | Resource limits |
## 📄 Example: Create a Web Service
```bash
docker service create \
--name web \
--replicas 3 \
--publish 80:80 \
--network webnet \
nginx
```
+13
View File
@@ -0,0 +1,13 @@
import { BrandDocker } from '@vicons/tabler';
import { defineTool } from '../tool';
export const tool = defineTool({
name: 'Docker SWARM cheatsheet',
path: '/docker-swarm-memo',
description: 'Docker Swarm mode cheatsheet',
keywords: ['docker', 'swarm', 'memo', 'cheatsheet'],
component: () => import('./docker-swarm-memo.vue'),
icon: BrandDocker,
createdAt: new Date('2025-08-17'),
category: 'Cheatsheets',
});
@@ -0,0 +1,32 @@
<script setup lang="ts">
import { useThemeVars } from 'naive-ui';
import Memo from './dockerfile.md';
const themeVars = useThemeVars();
</script>
<template>
<div>
<Memo style="overflow-x: auto;" />
</div>
</template>
<style lang="less" scoped>
::v-deep(pre) {
margin: 0;
padding: 15px 22px;
background-color: v-bind('themeVars.cardColor');
border-radius: 4px;
overflow: auto;
}
::v-deep(table) {
border-collapse: collapse;
}
::v-deep(table), ::v-deep(td), ::v-deep(th) {
border: 1px solid v-bind('themeVars.textColor1');
padding: 5px;
}
::v-deep(a) {
color: v-bind('themeVars.textColor1');
}
</style>
+258
View File
@@ -0,0 +1,258 @@
A **Dockerfile** is a script composed of instructions to build a Docker image. Each instruction creates a layer in the image.
## 📦 Basic Structure
```Dockerfile
# Comment
INSTRUCTION arguments
```
## 🚀 Core Instructions
### `FROM`
Specifies the base image.
```Dockerfile
FROM ubuntu:20.04
FROM node:18-alpine
```
### `LABEL`
Adds metadata to the image.
```Dockerfile
LABEL maintainer="you@example.com"
LABEL version="1.0" description="My App"
```
### `ENV`
Sets environment variables.
```Dockerfile
ENV NODE_ENV=production
ENV PATH="/app/bin:$PATH"
```
### `RUN`
Executes commands in a shell during build.
```Dockerfile
RUN apt-get update && apt-get install -y curl
RUN npm install
```
Use `RUN ["executable", "param1", "param2"]` for JSON array form.
### `COPY`
Copies files from host to image.
```Dockerfile
COPY . /app
COPY config.json /app/config.json
```
### `ADD`
Similar to `COPY`, but supports remote URLs and auto-extracts archives.
```Dockerfile
ADD https://example.com/file.tar.gz /app/
ADD archive.zip /app/
```
### `CMD`
Sets default command to run when container starts.
```Dockerfile
CMD ["node", "server.js"] # Preferred exec form
CMD node server.js # Shell form
```
Only one `CMD` allowed; later ones override earlier.
### `ENTRYPOINT`
Configures a container to run as an executable.
```Dockerfile
ENTRYPOINT ["python", "app.py"]
```
Use with `CMD` to pass default arguments.
### `WORKDIR`
Sets the working directory for subsequent instructions.
```Dockerfile
WORKDIR /app
```
### `EXPOSE`
Documents the port the container listens on.
```Dockerfile
EXPOSE 80
EXPOSE 443
```
Note: This does not publish the port.
### `VOLUME`
Creates a mount point for persistent or shared data.
```Dockerfile
VOLUME ["/data"]
```
### `USER`
Sets the user to run subsequent instructions.
```Dockerfile
USER appuser
```
### `ARG`
Defines build-time variables.
```Dockerfile
ARG VERSION=1.0
RUN echo $VERSION
```
Use `--build-arg VERSION=2.0` during `docker build`.
### `ONBUILD`
Triggers instructions when the image is used as a base.
```Dockerfile
ONBUILD COPY . /app
```
## 🧠 Best Practices
- Use minimal base images (e.g., `alpine`) for smaller size.
- Combine `RUN` commands to reduce layers.
- Use `.dockerignore` to exclude unnecessary files.
- Prefer `COPY` over `ADD` unless you need archive extraction.
- Use `ENTRYPOINT` for fixed commands and `CMD` for arguments.
- Avoid hardcoding secrets or credentials.
## 🧪 Example Dockerfile
```Dockerfile
FROM node:18-alpine
LABEL maintainer="guillaume@example.com"
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
ENV NODE_ENV=production
CMD ["node", "index.js"]
```
## 🛠️ Build & Run
```bash
# Build image
docker build -t my-app .
# Run container
docker run -p 3000:3000 my-app
```
## 📁 .dockerignore Example
```plaintext
node_modules
*.log
Dockerfile
.git
```
## 🏗️ Multistage Builds
**Multistage builds** allow you to use multiple `FROM` statements in one Dockerfile to optimize image size and separate build dependencies from runtime.
### 🎯 Why Use Multistage Builds?
- Reduce final image size by excluding build tools and intermediate files.
- Improve security by minimizing attack surface.
- Keep Dockerfiles clean and maintainable.
### 🧱 Basic Syntax
```Dockerfile
# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Stage 2: Production
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
```
### 🏷️ Named Stages
You can name each stage using `AS <name>` and reference it later with `--from=<name>`.
```Dockerfile
FROM golang:1.21 AS build
WORKDIR /src
COPY . .
RUN go build -o myapp
FROM alpine:latest
COPY --from=build /src/myapp /usr/local/bin/myapp
ENTRYPOINT ["myapp"]
```
### 📦 Copying Artifacts
Use `COPY --from=<stage>` to copy files from one stage to another.
```Dockerfile
COPY --from=builder /app/output /app/output
```
You can copy:
- Files
- Directories
- Binaries
- Configs
### 🧼 Clean Final Image
Multistage builds help you avoid bloated images:
```Dockerfile
# Without multistage: includes compilers, source code, etc.
# With multistage: only includes runtime essentials
```
### 🧪 Real-World Example: React App
```Dockerfile
# Build stage
FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Serve stage
FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
+13
View File
@@ -0,0 +1,13 @@
import { BrandDocker } from '@vicons/tabler';
import { defineTool } from '../tool';
export const tool = defineTool({
name: 'Dockerfile cheatsheet',
path: '/dockerfile-memo',
description: 'Dockerfile syntax and build cheatsheet',
keywords: ['dockerfile', 'memo', 'cheatsheet'],
component: () => import('./dockerfile-memo.vue'),
icon: BrandDocker,
createdAt: new Date('2025-08-17'),
category: 'Cheatsheets',
});