dokku-compose 0.11.1 → 0.13.0

package/README.md

@@ -101,9 +101,43 @@ Running `up` again produces no changes — every step checks current state befor
 | `--dry-run` | Print commands without executing |
 | `--sensitive` | Show sensitive values in output (masked by default) |
 | `--fail-fast` | Stop on first error (default: continue to next app) |
+| `--prune` | `up` only: also reset settings the file no longer declares (read `diff` first) |
 | `--remove-orphans` | Destroy services and networks not in config |
 | `--verbose` | Show git-style +/- diff (diff command only) |
 
+### Settings removed from the file
+
+`diff` marks with a red `-` every setting the server still has that the file no longer declares
+(managed env keys, nginx, logs, registry, scheduler, checks, `ps` and network properties, build
+args, and entries missing from a declared list), including when the whole block is gone. Only
+settable keys count, never read-only report lines, and a `-` counts as drift. It also warns when
+an app has no `links:` but has services linked on the server, because `up` unlinks them.
+
+`up` always unsets env keys removed from the file. For every other removal it leaves the setting in place and prints a one-line count per app of the leftovers it noticed in the blocks you declare; it does not look at removed whole blocks or checks. Run `dokku-compose diff` for the full list.
+
+**`up --prune`** resets those leftovers. Read `diff` first: every `-` it shows for the resources below is what `--prune` will reset, and there is no prompt (`diff` is the preview, the flag is the consent). Add `--dry-run` to print the reset commands without running them.
+
+| Resource | Reset command |
+|----------|---------------|
+| `nginx`, `logs`, `registry`, `ps` | `<plugin>:set <app> <key>` with no value (Dokku's default); nginx then rebuilds the proxy config |
+| `scheduler` | `scheduler:set <app> selected` |
+| `network` properties | `network:set <app> <key>` with no value (`attach_post_create` becomes `attach-post-create`, and so on) |
+| `checks` | `checks:enable <app> <types>` for the process types of a removed `disabled`/`skipped` list that the file declares in no list (a type the file does declare is left, with a warning naming the command to run by hand), `checks:set <app> wait-to-retire` |
+| `build.args` | `docker-options:remove <app> build "--build-arg KEY=VALUE"` for each stale key, by the exact option text (every occurrence); other build options stay |
+
+It covers a block that is gone from the file as well as keys removed from a declared block, and it reads the app once more for a block the file no longer has. `--prune` never destroys an app, service or network, never uninstalls a plugin, never changes `scale`, and does not clear whole `domains`, `ports`, `storage` or `networks` lists because their key is missing (those already prune inside a block the file declares). `proxy` is not a removal. `networks:` owns `attach-post-deploy`: `--prune` does not touch it, and a missing `networks:` key does not clear it (that could detach a running app from its network on the next deploy); `networks: []` does. After `up --prune`, `diff` shows no `-` for the resources above, except for checks that were skipped with a warning (their `-` lines stay).
+
+### Errors
+
+A failing Dokku command (mutation) is never reported as a success. On `up` and `down`, a
+global-phase failure (plugins, docker auth, global config, networks, services) aborts the whole
+run immediately. A per-app failure is printed with the command and Dokku's error output, and by
+default the run continues to the next app, exiting non-zero at the end with a summary of which
+apps failed; pass `--fail-fast` to stop at the first failure instead. `diff` never reports a
+resource as missing when it could not actually read server state — it falls back to a per-app
+read and, if that's unreadable too, marks the resource `unknown` and exits non-zero with a
+warning naming what it couldn't read.
+
 ## Features
 
 All features are idempotent — running `up` twice produces no changes.
@@ -112,7 +146,7 @@ All features are idempotent — running `up` twice produces no changes.
 |---------|-------------|-----------|
 | Apps | Create and destroy Dokku apps | [apps](docs/reference/apps.md) |
 | Dokku Version | Warn when the server's Dokku version is older than the pinned floor | [dokku](docs/reference/dokku.md) |
-| Environment Variables | Set config vars per app or globally, with full convergence | [config](docs/reference/config.md) |
+| Environment Variables | Set config vars per app or globally, with full convergence (keys removed from the YAML are unset) | [config](docs/reference/config.md) |
 | Build | Dockerfile path, build context, app.json, build args | [builder](docs/reference/builder.md) |
 | Docker Options | Custom Docker options per phase (build/deploy/run) | [docker_options](docs/reference/docker_options.md) |
 | Networks | Create shared Docker networks, attach to apps | [network](docs/reference/network.md) |
@@ -120,16 +154,29 @@ All features are idempotent — running `up` twice produces no changes.
 | Port Mappings | Map external ports to container ports | [ports](docs/reference/ports.md) |
 | SSL Certificates | Add or remove SSL certs | [certs](docs/reference/certs.md) |
 | Proxy | Enable/disable proxy, select implementation | [proxy](docs/reference/proxy.md) |
-| Storage | Persistent bind mounts with full convergence | [storage](docs/reference/storage.md) |
+| Storage | Persistent bind mounts with full convergence (keys removed from the YAML are unset) | [storage](docs/reference/storage.md) |
 | Nginx | Set any nginx property per app or globally | [nginx](docs/reference/nginx.md) |
 | Zero-Downtime Checks | Configure deploy checks, disable per process type | [checks](docs/reference/checks.md) |
 | Log Management | Log retention and vector sink configuration | [logs](docs/reference/logs.md) |
-| Plugins | Install Dokku plugins declaratively | [plugins](docs/reference/plugins.md) |
+| Plugins | Install Dokku plugins at pinned versions, updating forward only | [plugins](docs/reference/plugins.md) |
+| Process Scale & ps | Declare process counts (`ps:scale`) and ps properties (`ps:set`) | [scale](docs/reference/scale.md) |
 | Docker Auth | Authenticate the host docker daemon to private registries (e.g. ghcr.io) for `git:from-image` flows | [docker_auth](docs/reference/docker_auth.md) |
 | Postgres | Postgres services with optional S3 backups | [postgres](docs/reference/postgres.md) |
 | Redis | Redis service instances | [redis](docs/reference/redis.md) |
 | Service Links | Link postgres/redis services to apps | [plugins](docs/reference/plugins.md#linking-services-to-apps-appsapplinks) |
 
+## Variable interpolation
+
+`${VAR}` in a string value is replaced with the environment variable `VAR`. The file is parsed as YAML first and substituted afterwards, value by value, so a secret can contain any character (`"`, `'`, `#`, `\`, `:`, newlines) and arrives in the value unchanged; it can never change the file's structure. Keys and comments are never substituted. Every unset or empty variable is collected and reported together:
+
+```
+Unset environment variable(s) referenced in config: R2_HOST, GITHUB_TOKEN
+```
+
+To write a literal `${`, use `$${`: `"$${NOT_A_VAR}"` loads as `${NOT_A_VAR}`.
+
+Because substitution happens after parsing, a value that is a bare `${VAR}` is always a string, and a variable cannot inject YAML (extra keys, lists, quoting). Earlier versions substituted into the raw text, so anything that relied on that must now be written in the file.
+
 ## Execution Modes
 
 ```bash
@@ -186,7 +233,7 @@ dokku-compose/
 │   │   └── validate.ts       # validate command (offline)
 │   └── tests/
 │       ├── fixtures/         # Test YAML configs
-│       └── *.test.ts         # Unit tests per module
+│       └── *.test.ts         # Unit tests, beside src/modules and src/resources
 └── dokku-compose.yml.example
 ```
 
@@ -204,8 +251,8 @@ bun install
 # Run all tests
 bun test
 
-# Run a specific module's tests
-bun test src/modules/postgres.test.ts
+# Run a specific file's tests
+bun test src/resources/config.test.ts
 ```
 
 Tests use [Bun's test runner](https://bun.sh/docs/cli/test) with a mocked `Runner` — no real Dokku server needed.