Commit Graph
52 Commits
Author SHA1 Message Date
Jose Diaz-Gonzalez b612285392 fix: honor storage attachment process types at deploy time
An attachment's process type was recorded, reported and used to scope `storage:mount --replace` and `storage:unmount --all`, but nothing read it when the volume was actually mounted, so `storage:mount <app> <entry> --container-dir <path> --process-type web` bound the volume into every process rather than only `web`. Both schedulers now scope a mount to the process type it was declared for, and containers that belong to no process type - a `dokku run` one-off, an `app.json` deploy task, a k3s cron job - receive default-scoped mounts only. A container path can now be claimed by a single mount per process type, and `storage:migrate` drains process-scoped `-v` lines out of `docker-options` rather than only the default-scoped ones.
2026-09-21 18:08:42 -04:00
Jose Diaz-Gonzalez 1d0985428a feat: add a whole-set form for an app's storage mounts
The `storage` plugin mounted and unmounted one attachment at a time, so matching an app's mounts to a declared set meant reading `storage:list`, computing the difference in both directions and issuing one `storage:mount` or `storage:unmount` per addition and removal, with a failure partway through leaving the app holding a mixture of the two sets.

A `--replace` flag on `storage:mount` now writes the declared set in a single call, taking `name:container-dir` pairs whose optional third field carries the same mount options the legacy colon form accepts. Every pair is parsed and validated before anything is written, so a rejected pair leaves the stored mounts untouched. The remaining mount-time flags scope the whole call the way `--process-type` already scoped a single mount, which means an omitted `--process-type` replaces the `_default_` scope and leaves mounts scoped to a named process type in place.

An empty pair list is rejected rather than treated as a request to unmount everything, so a generated list that expands to nothing cannot silently drop an app's storage. `storage:unmount --all` handles that case instead, taking an optional `--process-type` filter and treating a scope that matches nothing as a no-op so it stays idempotent.

`storage:unmount` also accepts more than one mount at a time, naming each by entry name or by the colon form, and resolves every argument against the app's attachments before removing any of them.

The help listing now carries one entry per subcommand with its flags inline rather than a row per variant, and the command listing at the top of the storage documentation matches it line for line. Folding those rows together also surfaced `--global` on `storage:report` and `storage:migrate`, neither of which both listings had mentioned.

Finally, `--volume-chown` is now validated on mount, where a typo previously exited zero and wrote a value that only the report ever read.
2026-09-20 01:06:14 -04:00
Jose Diaz-Gonzalez 74f9acf7ba refactor: align storage:set with dokku conventions
`storage:set` now takes `<name> <property> [<value>]` like every other `:set` command, where omitting the value unsets the property. Previously it took flags and could not distinguish an empty value from an omitted one, so nothing it set could ever be cleared. The flag form keeps working and emits a deprecation warning.

Annotations and labels move to `storage:annotations:set`, `storage:annotations:report`, `storage:labels:set`, and `storage:labels:report`, matching the `scheduler-k3s` equivalents. These operate on a single key, so clearing one leaves the rest in place rather than replacing the whole map as the `--annotation` and `--label` flags do.
2026-08-10 15:00:45 -04:00
Jose Diaz-Gonzalez 87b240054f feat: add storage directory mode and removal flags
`storage:create` and `storage:set` accept a `--mode` flag that sets the octal permissions of a docker-local host directory, and `storage:destroy` accepts a `--destroy-host-dir` flag that removes the directory along with its contents. A docker-local entry also honors `--reclaim-policy Delete` at destroy time now, matching how that policy governs a k3s PersistentVolume. Both are limited to the default `/var/lib/dokku/data/storage/<name>` location, the same restriction `--chown` already carries. `storage:set` applies `--chown` and `--mode` to the directory rather than only recording them.
2026-08-10 01:23:10 -04:00
RichardDorian 962c54bb2a docs(storage): add documentation regarding custom chown values 2026-07-07 19:28:27 +02:00
Jose Diaz-Gonzalez bec6b9f14a feat: expose per-attachment fields in storage:report
storage:report gains a flat dotted key per attachment field (entry-name, host-path, container-path, phases, process-type, subpath, readonly, volume-options, volume-chown) under the --storage-attachment.<index>.<field> shape. Both stdout and JSON pick the keys up through the existing common.ReportSingleApp pipeline. Attachments that reference a missing storage entry emit a warning and are skipped, so the rest of the report still renders. Closes #8710.
2026-05-30 04:11:30 -04:00
Jose Diaz-Gonzalez 3bb21b6987 feat: make storage:mount upsert the existing attachment
Re-running `storage:mount <app> <entry> --container-dir <path>` against an existing `(entry, container_dir, process_type)` tuple now updates the attachment's mount-time fields in place instead of erroring with `already mounted`. Declarative tooling that wants to change `--volume-options`, `--volume-chown`, `--phase`, `--volume-subpath`, or `--volume-readonly` on an existing mount no longer has to unmount-then-remount, which briefly dropped the volume from `storage:report` and raced against any deploy that fired in the window. The legacy `host:container[:opts]` form keeps its strict `Mount path already exists.` failure.
2026-05-30 03:23:32 -04:00
Jose Diaz-Gonzalez e9160db769 fix: expose attachment readonly and volume_options in storage:list json
The `storage:list <app> --format json` payload conflated the
attachment's `Readonly` flag and its `VolumeOptions` field into a
single derived `volume_options` string that rendered as `ro`,
`<options>`, or `ro,<options>` depending on which fields were set on
the underlying attachment. That shape is fine for the legacy
`host:container[:options]` text view but it leaves drift-detection
tooling unable to tell whether a `ro` token came from
`Attachment.Readonly == true` or from the operator setting
`Attachment.VolumeOptions = "ro"` directly. The JSON now exposes
`readonly` (boolean) and `volume_options` (string) as separate
omitempty keys populated straight from the attachment, and
`formatStorageListEntry` combines them at format time for the colon-
form text view. `ParseMountPath` was extended in lockstep so callers
of the legacy `host:container:opts` form no longer have to special-
case the `ro` token themselves.
2026-05-30 03:00:21 -04:00
Jose Diaz-Gonzalez f4d27be7a6 feat: add --volume-options flag to storage:mount
The named-entry form of `storage:mount` had no way to set the attachment's `volume_options`, even though the legacy `host:container:opts` colon form parses options into the same field and every downstream consumer (the docker-args trigger and the storage:list/storage:report display path) already renders them. Tooling that declaratively re-applies attachments silently dropped options on every re-apply.
2026-05-30 02:28:14 -04:00
Jose Diaz-Gonzalez 94c43f6dd8 fix: pass storage entry basename to chown-storage-dir
storage:create --chown invoked chown-storage-dir with the full host path, but the helper validates a basename and prepends the storage root itself, so every call failed with `Directory can only contain the following set of characters`. Pass the entry name and reject the combination of --chown with a non-default host path, since the helper only manages the default storage location.
2026-05-29 20:49:12 -04:00
Jose Diaz-Gonzalez 3493869fa4 feat: prompt for confirmation on storage:destroy
`storage:destroy` now prompts for confirmation before removing a named storage entry, matching the behavior of other destructive commands such as `apps:destroy` and `network:destroy`. The prompt can be skipped with the `--force` flag or the global `dokku --force` flag for non-interactive callers.
2026-05-29 14:31:20 -04:00
Jose Diaz-Gonzalez b2320121fe refactor: convert filesystem migration markers to plugin properties
The docker-options DOCKER_OPTIONS_<PHASE>.migrated sentinels and the storage data/storage-registry/migrations/<app> flag files are now stored as per-app properties (`migrated-<phase>` and `legacy-mounts-migrated` respectively), so they survive a property-store backup/restore and align with the existing `migrated-from-files`, `env-migrated`, and `nginx-conf-sigil-migrated` patterns. The new markers are written only when a non-empty legacy source was actually migrated, distinguishing apps that never had legacy state from apps that did and were drained. A one-cycle upgrade-cycle conversion drains any leftover filesystem sentinels into the new properties and removes the files; for docker-options the conversion deliberately runs before the global `migrated-from-files` short-circuit so installs upgrading from the previous release still get their `.migrated` files converted.
2026-05-23 23:47:58 -04:00
Jose Diaz-Gonzalez b601a626f5 docs: storage entries and migration guide for #6814
Updates persistent-storage.md to lead with the named storage entry workflow while keeping the legacy colon-form documentation intact, adds a Persistent storage section to the k3s scheduler doc, documents the storage-app-mounts, storage-create, storage-destroy, and storage-status triggers in plugin-triggers, and adds an entry to the 0.38.0 migration guide explaining the install-time migration of legacy mounts and the new DNS-1123 name validation. Bats coverage in tests/unit/storage.bats now exercises storage:create / list-entries / destroy, name validation rejections, multi-entry attachment, the destroy-while-mounted error, and the ensure-directory deprecation warning.
2026-04-29 14:54:15 -04:00
Álvaro Justen (@turicas) 96bb17d70c Fix paketo chown option 2025-03-10 12:50:46 -03:00
Jose Diaz-Gonzalez 7381cf74c6 feat: add support for custom user namespaces when creating persistent storage directories
Closes #3454
2024-01-23 02:25:11 -05:00
Ed Morley e6747e8357 Replace deprecated builder reference in persistent-storage.md
Since the `heroku/buildpacks:*` builders are deprecated in favour of `heroku/builder`.
2023-10-30 12:31:11 +00:00
Jose Diaz-Gonzalez d61d91cf87 docs: use github admonitions
These still need to be properly parsed.
2023-08-19 14:24:12 -04:00
Jose Diaz-Gonzalez 5dd78e2b86 docs: update markdownlint rules for better formatting 2023-08-19 13:46:42 -04:00
Jose Diaz-Gonzalez 852dfc6287 feat: add json output format support to storage:list
This will allow the command to be used in a programmatic fashion.
2022-12-26 16:33:40 -05:00
Jose Diaz-Gonzalez c0449d2bf1 docs: reference node-js-app instead of lollipop in storage docs
We've standardized on node-js-app elsewhere.
2022-12-26 16:12:26 -05:00
Jose Diaz-Gonzalez 1f75e7d378 docs: document the storage:list command 2022-12-26 16:11:57 -05:00
josegonzalez f92d240461 docs: update data loss blockquote to be warning 2022-12-06 14:41:35 -05:00
Jose Diaz-Gonzalez 01531c3986 docs: cleanup links to renamed docs 2022-09-05 16:49:56 -04:00
Jose Diaz-Gonzalez f8b1b02df5 docs: fix typo on persistent storage docs
Closes #4909
2021-11-08 10:17:29 -05:00
Jose Diaz-Gonzalez d9eea74f18 feat: implement storage:ensure-directory command
Closes #4805
2021-09-29 11:36:02 -04:00
Jose Diaz-Gonzalez c50f39b4fa docs: more cleanup 2021-07-09 22:46:52 -04:00
Grant Jenks 4387ae2bb3 Fix typo: "diretory" to "directory"
Fix typo: "diretory" to "directory"
2021-03-25 22:20:47 -07:00
Jose Diaz-Gonzalez 66acde1c66 docs: clarify permissions on persistent storage paths
CNB uses a custom user/group id depending on the image.

Also cleanup the entire doc to make it generally more readable with less repetition.

Closes #4479
2021-03-21 23:14:39 -04:00
Jose Diaz-Gonzalez 75b7ae94e1 docs: use updated links for documentation
Docs are now hosted on https://dokku.com, so we can avoid the extra rewrite.
2021-02-28 01:18:33 -05:00
Leopold Talirz 6b4c545592 Update persistent-storage.md
add directory to complete path
2021-01-04 16:17:54 +01:00
Jose Diaz-Gonzalez c8537bff48 docs: document custom networking 2020-02-08 22:15:15 -05:00
Jose Diaz-Gonzalez c1781c39ca docs: correct header
[ci skip]
2019-03-13 16:55:39 -04:00
Jose Diaz-Gonzalez 7349c30cd9 feat: allow disabling chown for persistent storage in scheduler-docker-local
Some systems - such as a mounted read-only CIFS filesystem - do not fully support chown, and chowning should be considered optional for cases when the host os has already taken care of permissioning. This commit allows users to disable chown by setting a property on the scheduler-docker-local plugin.
2018-08-01 06:51:47 -04:00
Jose Diaz-Gonzalez 2679bf3709 docs: switch from ps:rebuild to ps:restart
A rebuild from source is not generally required here.
2018-07-25 22:44:47 -04:00
Jose Diaz-Gonzalez 3bf3bb433b docs: clarify user/group id
[ci skip]
2017-08-17 14:43:56 -04:00
Jose Diaz-Gonzalez fa0b4b26ac docs: clarify storage documentation caveats
[ci skip]
2017-08-17 14:36:23 -04:00
Yazin 1e18299364 fix typo 2017-05-30 13:38:27 +01:00
Jose Diaz-Gonzalez 0ba9393285 docs: use urls that are linkable on github 2017-04-13 23:09:46 -06:00
Jose Diaz-Gonzalez 25e44b5492 docs: use node-js-app as the app name, not node-js-sample 2017-03-15 02:42:10 -06:00
Jose Diaz-Gonzalez b7da215ab5 feat: implement storage:report command
Refs #2356
2017-03-15 02:42:10 -06:00
Jose Diaz-Gonzalez 927d569db5 Move "new as of" note to correct section
Also move note up.

[ci skip]
2017-01-15 01:07:12 -07:00
Jose Diaz-Gonzalez f0ecac5998 Update persistent storage to reference the sample app as normal
[ci skip]
2017-01-15 01:05:08 -07:00
Slava Vishnyakov a53c61b4d8 Update persistent-storage.md 2016-12-15 18:46:16 +03:00
Slava Vishnyakov 42b1666fbe Update persistent-storage.md 2016-12-15 17:15:00 +03:00
Slava Vishnyakov de9f495e2c storage needs deploy too 2016-12-15 14:22:52 +03:00
Jose Diaz-Gonzalez f26b3f1966 Use correct casing for Dokku name
lowercase should only be used to refer to the binary, not the project
2016-09-03 15:51:14 -04:00
Jose Diaz-Gonzalez eb4e3485fe Merge pull request #2388 from dokku/2384-proxy-scheme-docs
Add documentation for proxy ports scheme handling
2016-08-26 15:29:50 -04:00
Jose Diaz-Gonzalez ab8063e88a Add documentation for proxy ports scheme handling
Closes #2384

[ci skip]
2016-08-26 15:29:17 -04:00
Michael Hobbs 0e779e98c0 add docs for app user and persistent storage 2016-08-26 11:13:21 -07:00
Jose Diaz-Gonzalez 434951028d Dockerfile deploys do not support mounted volumes
[ci skip]
2016-08-06 15:44:18 -04:00