You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide collects practical recommendations for using Dockform safely and effectively across development, staging, and production.
8
+
9
+
## Core principles
10
+
11
+
- Treat the manifest file as *the* source of truth; avoid imperative Docker commands.
12
+
- Scope everything with a clear `docker.identifier` (e.g., `server-name`).
13
+
- Prefer small, focused changes and review with `dockform plan` before `apply`.
14
+
15
+
## Volumes
16
+
17
+
- Declare named volumes in the manifest under `volumes:` and reference them as `external` in Compose. ***Avoid defining named volumes directly in Compose***.
18
+
- Back up volumes regularly. Dockform’s `destroy` (and `prune`) can remove labeled volumes. Consider a backup solution like [docker-volume-backup](https://offen.github.io/docker-volume-backup/).
19
+
- If a fileset targets a volume, you may omit it from `volumes:` (it will be created), but listing it explicitly improves readability.
20
+
21
+
## Networks
22
+
23
+
- Declare networks in the manifest and reference them as `external` in Compose. Avoid creating ad-hoc networks via Compose.
24
+
- Use environment-specific names if you need strict isolation per environment.
25
+
26
+
## Filesets
27
+
28
+
- Use filesets for configs and static assets (not for very large, frequently-changing data).
29
+
- Keep `target_path` specific (never `/`), and use `exclude` to avoid syncing build artifacts, VCS metadata, and OS files.
30
+
- Set `restart_services` only for services that actually need a restart.
31
+
32
+
Example excludes:
33
+
34
+
```yaml [dockform.yaml]
35
+
filesets:
36
+
app-config:
37
+
source: ./config
38
+
target_volume: app-config
39
+
target_path: /etc/app
40
+
exclude:
41
+
- ".git/"
42
+
- "**/*.tmp"
43
+
- "**/.DS_Store"
44
+
```
45
+
46
+
## Applications and Compose
47
+
48
+
- Set a stable `project.name` for predictable container and network names. See https://docs.docker.com/compose/how-tos/project-name/
49
+
- Keep Compose files close to each app’s `root` folder; avoid cross-tree paths.
50
+
- Use Compose profiles for environment-specific toggles (e.g., `prod` vs `dev`).
51
+
- Let Dockform inject its identifier label; do not hardcode `io.dockform.identifier` in Compose.
52
+
53
+
## Environment and secrets
54
+
55
+
- Use root `environment.files` for shared files and app-level `environment.files` for overrides; Dockform rebases root paths to the app `root`.
56
+
- Prefer SOPS-encrypted `.env` files for secrets. Keep keys outside of the repo and load via `${AGE_KEY_FILE}`.
57
+
- If not using SOPS, inject secrets via CI as environment variables and pass them through Compose `environment:`.
58
+
59
+
<!-- ## CI/CD recommendations
60
+
61
+
- Use `dockform plan` in PRs to preview changes; require approval before `apply`.
62
+
- Pin the Docker context and set a clear `docker.identifier` per environment.
63
+
- Provide required env vars (including SOPS keys if used) via CI secrets.
64
+
- For ephemeral tests, set `DOCKFORM_RUN_ID` to isolate resources, then run `dockform destroy` or `prune` at the end. -->
65
+
66
+
## Safety and destructive operations
67
+
68
+
Always ensure you have recent backups for stateful volumes before destructive commands.
69
+
70
+
::: warning
71
+
72
+
`destroy`removes all labeled resources for the active identifier (containers, networks, volumes). Use with care.
73
+
74
+
:::
75
+
76
+
## Performance and determinism
77
+
78
+
- Limit fileset sizes and use `exclude` aggressively for large repos.
79
+
- Keep Compose and manifest changes minimal per deployment for faster diffs.
80
+
- Prefer stable project and resource names to minimize churn and restarts.
81
+
82
+
## Suggested project structure
83
+
84
+
- Dockform is unopinionated, but grouping applications by folder is effective.
85
+
86
+
```text
87
+
repo/
88
+
dockform.yaml
89
+
traefik/
90
+
docker-compose.yaml
91
+
config/
92
+
app/
93
+
docker-compose.yaml
94
+
.env
95
+
db/
96
+
docker-compose.yaml
97
+
```
98
+
99
+
## Troubleshooting tips
100
+
101
+
- If Compose fails, run `docker compose -f <file> config` to validate YAML.
102
+
- If a service doesn’t update, check labels and config-hash drift; then run `dockform plan`.
103
+
- If a volume/network is “missing” in Compose, ensure it is declared in the manifest and referenced as `external` with the correct name.
Reference the encrypted dotenv file inside your manifest.
59
59
Secrets can be defined globally or scoped to a specific application.
60
60
61
-
```yaml
61
+
```yaml [dockform.yaml]
62
62
secrets:
63
63
sops:
64
64
- app/secrets.env
65
65
```
66
66
67
67
For application-specific secrets:
68
68
69
-
```yaml
69
+
```yaml [dockform.yaml]
70
70
applications:
71
71
web:
72
72
secrets:
73
73
sops:
74
74
- web/secrets.env
75
75
```
76
76
77
-
---
77
+
## Using secrets without SOPS (CI-managed)
78
+
79
+
If you prefer not to use SOPS, you can manage sensitive values via your CI/CD system’s secret store (e.g., GitHub Actions). Provide secrets as environment variables at runtime and reference them from Compose or the manifest.
80
+
81
+
- Set CI environment variables from your secret store.
82
+
- Add them to Dockform `environment.inline` to ensure Compose receives them during planning and apply.
83
+
84
+
::: code-group
85
+
86
+
```yaml [dockform.yaml]
87
+
docker:
88
+
context: default
89
+
identifier: production
90
+
91
+
environment:
92
+
inline:
93
+
# These values are interpolated from CI-provided env vars at load time
94
+
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
95
+
- OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
78
96
79
-
## Summary
97
+
applications:
98
+
app:
99
+
root: ./app
100
+
files: [docker-compose.yaml]
101
+
```
102
+
103
+
```yaml [app/docker-compose.yaml]
104
+
services:
105
+
api:
106
+
image: ghcr.io/example/api:latest
107
+
environment:
108
+
# Compose reads values from the process environment (provided by CI or Dockform inline env)
109
+
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
110
+
OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
111
+
```
112
+
113
+
```yaml [ .github/workflows/deploy.yml ]
114
+
name: Deploy
115
+
on:
116
+
workflow_dispatch:
117
+
push:
118
+
branches: [ main ]
119
+
120
+
jobs:
121
+
deploy:
122
+
runs-on: ubuntu-latest
123
+
env:
124
+
# Provide secrets from GitHub Actions to the process environment
0 commit comments