feat: add docket export command#282
Merged
Merged
Conversation
Adds a per-task ExportSupport() declaration classifying how each task participates in a future docket export command, renders it into the generated task docs, and introduces a swappable executor in the subprocess package so command dispatch can be faked in tests.
Adds the export command, the inverse of apply: it reads a live Dokku server and writes a recipe describing it, lifting sensitive values into a companion vars-file that the recipe references through inputs so the pair applies with a vars-file. The engine enumerates apps and reconstructs each app's structure through per-task AppExporter implementations, supports redaction and stdout streaming, and prompts before overwriting existing output unless overwrite is passed.
Adds AppExporter implementations for the ports and buildpacks tasks, reconstructing them from the live server and wiring them into the export order. Verified round-trip against dokku 0.38.21: apply of the exported recipe reports no drift.
Adds the export command to the command reference, rewrites the migration guide to start from docket export, removes the now-implemented export idea from the roadmap, and points the service tasks' export-support note at the follow-up issue.
Adds AppExporter implementations for ps scale and the checks, proxy, domains, and maintenance toggles, emitting a task only when the state differs from the dokku default. Verified round-trip against real dokku for ps scale and the proxy toggle; the checks and maintenance readers depend on plugin versions/availability and are skipped with a warning when unreadable.
Adds an AppExporter for storage attachments, reconstructing each mount from storage:list as a host_dir bind-mount or a named entry. Verified round-trip against real dokku.
Adds exportProperties, which reconstructs a property plugin's explicitly-set values from its report (the raw per-app key is only present when set, so defaults are skipped), and wires it for nginx. Verified round-trip against real dokku.
Wires exportProperties into every property-plugin task (builders, proxies, git, logs, cron, checks, ps, network, registry, letsencrypt, app-json, apps, scheduler variants) and adds them to the export order. Verified round-trip against real dokku across the nginx, git, logs, and proxy plugins with no drift.
Asserts every entry in appExportOrder resolves to a registered task implementing AppExporter, so a typo or unwired exporter fails the build instead of being silently skipped.
Wires a leading global play into the export engine via a new GlobalExporter path, implements it for named storage registry entries (skipping auto-generated legacy entries), and adds the app-lock exporter. Verified round-trip against real dokku.
Reads the checks disabled-list from checks:report --format json (dokku 0.38.21 renamed the --checks-disabled flag) and reads the buildpacks list from buildpacks:report so build-precedence order is preserved instead of being lost to an unordered set.
Reconstructs resource limits and reservations from resource:report --format json, one task per process type, carrying only explicitly-set values. Verified round-trip against real dokku.
storage:list does not expose phases, readonly, subpath, or process-type, so the storage_mount exporter cannot reconstruct those attachment details.
Adds exporters for docker options (one task per option, split from the space-joined report; marked partial per dokku/dokku#8799), http-auth allowed IPs and domains, and app ACL users. Verified round-trip against real dokku.
Adds the http-auth user exporter: usernames come from the report and each unreadable password is lifted into a required, sensitive input the user supplies before applying. Verified round-trip against real dokku once the password is filled in.
Adds a global exporter for SSH keys. ssh-keys:list --format json exposes both the name and the public-key body, so each key is reproduced faithfully. Verified whole-server round-trip against real dokku.
Reconstructs an app's deploy source from apps:report: git-sync (remote#ref), docker-image, and archive (tar/tar.gz/zip) map to the matching git task, each self-selecting on the recorded source type. Image and archive URLs are sensitive, so the engine now generically lifts any sensitive scalar field into the vars-file. Verified git-sync round-trip against real dokku.
Adds a global exporter for scheduler-k3s node profiles, reconstructed from profiles:list (name, role, kubelet args, taint/allow-unknown-hosts flags). Verified round-trip against a real dokku with the scheduler-k3s plugin installed.
scheduler-k3s exposes no report for annotations, labels, or KEDA trigger authentication, so their state cannot be read back for export. Reclassifies them ExportUnsupported and tracks the read-back gap in dokku/dokku#8800.
Adds integration tests that run the exporters against a real dokku: a config round-trip (export then plan reports no drift), a full ExportRecipe pipeline check, and a scheduler-k3s profile round-trip gated on the plugin. Verified passing against dokku 0.38.21.
Adds a global exporter for scheduler-k3s helm chart value overrides (reconstructed from charts:report, grouped per chart) and an app exporter for the letsencrypt toggle (emitted when letsencrypt:active). Adds gated integration tests: the scheduler-k3s chart/profile tests need only dokku (scheduler-k3s is core, no deploy required), and the letsencrypt test is gated on its plugin. All verified against real dokku.
Reclassifies network and plugin as ExportUnsupported (their identity/install-URL is not exposed by dokku) and points the certs, maintenance-custom-page, network, plugin, and scheduler-k3s annotations/labels/trigger-auth caveats at their tracking issues (docket#283-287, dokku/dokku#8797/#8798/#8800).
The maintenance plugin has no command to read the custom page back (only a checksum), so a faithful export is blocked on dokku/dokku-maintenance#28; the caveat now points at it alongside the interim required-input option in docket#284.
Adds an exporter for per-app SSL certificates. certs:show streams the cert and key PEM (which the reader never used, only certs:report metadata), so the certificate is reconstructed faithfully with the sensitive PEM lifted into the vars-file. The global cert has no equivalent show command in dokku-global-cert, so it remains unexported. Verified round-trip against real dokku.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a docket export command, the inverse of apply: it reads a live Dokku server and writes a recipe describing it, so an existing server can be captured as a recipe instead of hand-written. This is the starting point for a migration, and the migration guide now begins with it.
Because a faithful recipe would otherwise embed secrets, export writes two files: the recipe, and a companion vars-file holding the sensitive values. The recipe references those values through per-play inputs, so the pair applies together with docket apply --vars-file. A --redact flag writes placeholders instead of real secrets, and stdout streams a single self-contained recipe for inspection. Existing output is never overwritten without a prompt unless --overwrite is passed.
Export covers the large majority of task types, verified against a real dokku by the export-apply-plan idempotency contract: applying an exported pair back to the same server reports no drift. Each task declares its own export support, rendered into an Export support section on its reference page, so the tasks that cannot be reconstructed are visible and explained. Those gaps are write-only credentials, values dokku does not expose from a read command, and the datastore service tasks; follow-up issues track the service coverage and the upstream reporting gaps.