dokku-compose 0.13.0 → 0.14.0

package/README.md

@@ -30,7 +30,7 @@ Like Docker Compose, but for Dokku.
 npm install -g dokku-compose
 ```
 
-Requires Node.js >= 20. See the [Installation Reference](docs/reference/install.md) for details.
+Requires Node.js >= 20 and a server running Dokku >= 0.38.29 (every server command stops on an older one; dokku-compose never installs or upgrades Dokku). See the [Installation Reference](docs/reference/install.md) for details.
 
 ### 1. Export your existing server
 
@@ -58,6 +58,8 @@ dokku-compose diff
   1 resource(s) out of sync.
 ```
 
+When `diff` says a box is in sync, `up` runs no command on it. `diff` also covers the top-level `domains:`, `logs:` and `nginx:` (under `global`; log sinks are masked), shared networks missing on the server, and a replaced `ssl.certfile` (compared with the installed certificate). `diff --verbose` prints `Everything in sync.` when nothing differs. `diff` also notes, by name only, each app env key the file does not declare (a key set by hand or by a script); a note is not drift and never changes the exit code. List the keys something else sets under the app's `env_external:` and `diff` stops noting them ([config](docs/reference/config.md#keys-set-elsewhere-appsappenv_external)).
+
 ### 3. Preview changes
 
 ```bash
@@ -81,6 +83,29 @@ dokku-compose up
 
 Running `up` again produces no changes — every step checks current state before acting.
 
+#### Apps that need a restart
+
+`up` applies env, storage, links and Docker options without restarting anything, so the changes wait for a restart. It ends by listing each app it changed that way, with the exact command (`dokku ps:rebuild <app>` for settings only a rebuild applies, which replaces the restart line for an app needing both) (`would need` on `--dry-run`, also after a partial failure). It never runs the restart and has no `--restart` flag.
+
+```
+# Apps that need a restart or rebuild:
+dokku ps:restart worker  # env, storage
+```
+
+| Change | Listed | Evidence (Dokku 0.38.31) |
+|--------|--------|--------------------------|
+| `env` set or unset, per app | yes | applied with `--no-restart` |
+| top-level `env:` | yes, every app the run processes, when a global key is set or unset | global env is read when a container starts |
+| `storage` mount or unmount | yes | persistent-storage docs: "the app requires a restart" |
+| `docker_options` deploy and run | yes | docker-options docs: applies "only to containers created after" the change |
+| `links` link or unlink | yes | applied with `--no-restart` |
+| `network` `tld`, `bind_all_interfaces` | yes | read when containers start |
+| `networks`, `network` `attach_post_create`, `initial_network` | rebuild: `dokku ps:rebuild <app>` | network docs (network.md:210): "A change in these values will require an app deploy or rebuild" |
+| `docker_options` build, `build.args`, `build.dockerfile`, `app_json`, `context` | rebuild | read by a build, which a restart does not run |
+| `ports` | no | `ports:set` fires `post-proxy-ports-update`, which rebuilds the nginx config |
+| `domains`, `nginx`, `proxy`, `certs`, `logs`, `checks`, `registry`, `scheduler` | no | applied live or read at deploy |
+| `scale`, `ps` | no | `--skip-deploy`: takes effect on the next deploy |
+
 ## Commands
 
 | Command | Description |
@@ -108,21 +133,23 @@ Running `up` again produces no changes — every step checks current state befor
 ### 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
+(managed env keys, nginx, logs, registry, scheduler, checks, `ps`, network, proxy and git
+properties, build settings and 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` 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, and does not count 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` |
+| `nginx`, `logs`, `registry`, `ps`, `git` (not Dokku-written keys: `ps` `restore`, git `deploy-branch` and `source-image`) | `<plugin>:set <app> <key>` with no value (Dokku's default); nginx then rebuilds the proxy config |
+| `scheduler` | `scheduler:set <app> selected` or `shell` |
+| `proxy` properties | `proxy:set <app> type` with no value (`proxy-port` and `proxy-ssl-port` are written by Dokku) |
 | `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` |
+| `checks` | `checks:enable <app> <type,type>` 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.selected`, `build.skip_cleanup` | `builder:set <app> selected` / `skip-cleanup` with no value |
 | `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).
@@ -152,18 +179,19 @@ All features are idempotent — running `up` twice produces no changes.
 | Networks | Create shared Docker networks, attach to apps | [network](docs/reference/network.md) |
 | Domains | Configure domains per app or globally | [domains](docs/reference/domains.md) |
 | 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) |
+| SSL Certificates | Add, replace 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 (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) |
+| Scheduler, Registry, Git | `scheduler` (`selected`, `shell`), `registry` and `git` properties per app; every app-scope `:set` key of Dokku 0.38.31 (audit F5), keys Dokku refuses fail `validate` | [logs](docs/reference/logs.md#removal), [audit](docs/dokku-audit.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 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) |
+| Postgres | Postgres services with optional S3 backups, read from `postgres:info` so backup drift shows in `diff`; a changed version or image shows in `diff` | [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) |
+| Service Links | Link postgres/redis services to apps, with `alias`, `env_var` or `querystring` | [plugins](docs/reference/plugins.md#linking-services-to-apps-appsapplinks) |
 
 ## Variable interpolation
 

package/dist/chunk-WM244P42.js

@@ -0,0 +1,89 @@
+// src/modules/version.ts
+import { createRequire } from "module";
+
+// src/core/logger.ts
+import chalk from "chalk";
+function logAction(context, message) {
+  process.stdout.write(chalk.blue(`[${context.padEnd(12)}]`) + ` ${message}`);
+}
+function logDone() {
+  console.log(`... ${chalk.green("done")}`);
+}
+function logSkip() {
+  console.log(`... ${chalk.yellow("already configured")}`);
+}
+function logError(context, message) {
+  console.error(chalk.red(`[${context.padEnd(12)}] ERROR: ${message}`));
+}
+function logWarn(context, message) {
+  console.warn(chalk.yellow(`[${context.padEnd(12)}] WARN: ${message}`));
+}
+
+// src/modules/version.ts
+var MIN_DOKKU_VERSION = "0.38.29";
+var SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)/;
+function parseSemver(input) {
+  const m = input.match(SEMVER_RE);
+  if (!m) throw new Error(`Cannot parse version: ${input}`);
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function extractServerVersion(output) {
+  const match = output.match(/(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+function compareSemver(a, b) {
+  const [aMaj, aMin, aPatch] = parseSemver(a);
+  const [bMaj, bMin, bPatch] = parseSemver(b);
+  if (aMaj !== bMaj) return aMaj < bMaj ? -1 : 1;
+  if (aMin !== bMin) return aMin < bMin ? -1 : 1;
+  if (aPatch !== bPatch) return aPatch < bPatch ? -1 : 1;
+  return 0;
+}
+function toolVersion() {
+  const require2 = createRequire(import.meta.url);
+  for (const p of ["../package.json", "../../package.json"]) {
+    try {
+      return require2(p).version;
+    } catch {
+    }
+  }
+  return "unknown";
+}
+async function assertDokkuSupported(ctx) {
+  const output = await ctx.query("version");
+  const server = extractServerVersion(output);
+  if (!server) {
+    throw new Error(`Cannot parse Dokku server version from output: ${output}`);
+  }
+  if (compareSemver(server, MIN_DOKKU_VERSION) === -1) {
+    throw new Error(
+      `dokku-compose ${toolVersion()} needs Dokku >= ${MIN_DOKKU_VERSION}; this server runs ${server}. Upgrade Dokku first.`
+    );
+  }
+  return server;
+}
+function compareToFile(server, file) {
+  if (!file) return "none";
+  const c = compareSemver(server, file);
+  return c === 0 ? "equal" : c < 0 ? "older" : "newer";
+}
+function enforceFileVersion(server, file) {
+  const rel = compareToFile(server, file);
+  if (rel === "older") {
+    throw new Error(`Dokku server is v${server} but the file requires >= v${file}. Upgrade Dokku or lower dokku.version.`);
+  }
+  if (rel === "newer") {
+    logWarn("dokku", `server is v${server}, newer than dokku.version ${file} in the file; update the file when ready`);
+  }
+}
+
+export {
+  logAction,
+  logDone,
+  logSkip,
+  logError,
+  logWarn,
+  assertDokkuSupported,
+  compareToFile,
+  enforceFileVersion
+};