# Persistent Storage > [!IMPORTANT] > New as of 0.5.0. Named storage entries new as of 0.38.0. The preferred method to attach persistent storage to a Dokku-managed container is the Dokku storage plugin. ``` storage:annotations:report [] [] # Displays annotations for one or more storage entries storage:annotations:set [] # Set or clear a single annotation on a storage entry storage:create [] [flags] # Register a named storage entry storage:destroy [--force] [--destroy-host-dir] # Remove a named storage entry (must be unmounted from every app first) storage:ensure-directory [--chown option] # [DEPRECATED] use storage:create instead storage:exec [-- ...] # Run a command (or shell) in a temporary container that mounts the entry storage:info [--format text|json] # Show details for one storage entry storage:labels:report [] [] # Displays labels for one or more storage entries storage:labels:set [] # Set or clear a single label on a storage entry storage:list [--format text|json] # List bind mounts for an app's container(s) (legacy host:container view) storage:list-entries [--scheduler s] [--format text|json] # List registered storage entries storage:migrate [|--all] # Re-run the legacy -v to attachment migration for an app storage:mount [--replace] ... [flags] # Create or replace bind mounts storage:report [|--global] [] # Displays a storage report for one or more apps storage:set [] # Update a storage entry in place storage:unmount [--all] [...] [flags] # Remove one or all bind mounts storage:wait # Wait for a storage entry's PVC to be bound (k3s) ``` A storage entry is the source of truth for the underlying volume - a host directory on docker-local, or a PersistentVolumeClaim on k3s. Multiple apps can mount the same entry, and an attachment carries the per-app details (container path, phases, subpath, readonly, process type). Names are globally unique across the install and must be DNS-1123 labels (lowercase letters, digits, dashes) of 45 characters or less so they can be used verbatim as Helm release and PVC names. The legacy `storage:mount :` form continues to work on docker-local. On a k3s app it is rejected; create a named entry with `storage:create --scheduler k3s` and mount it instead. Existing colon-form mounts are migrated automatically the first time the new code runs - they show up as `legacy-` entries in `storage:list-entries`. The storage plugin supports the following mount points: - explicit paths that exist on the host (docker-local) - docker volumes (docker-local) - PersistentVolumeClaims provisioned via a StorageClass (k3s) - hostPath-backed PVs (k3s) ## Usage ### Listing persistent storage Persistent storage bind mounts are specified on a per-app basis, and can be listed with the `storage:list` command: ```shell dokku storage:list node-js-app ``` ``` -----> node-js-app volume bind-mounts: /var/lib/dokku/data/storage/node-js-app:/app/storage ``` The output format can also be set to `json` for programmatic access: ```shell dokku storage:list node-js-app --format json ``` ``` [ { "entry_name": "node-js-app", "host_path": "/var/lib/dokku/data/storage/node-js-app", "container_path": "/app/storage" } ] ``` Each entry mirrors the underlying attachment. `readonly` (boolean) and `volume_options` (string) reflect `Attachment.Readonly` and `Attachment.VolumeOptions` directly and are only present when set, so external tooling can drift-detect attachments against the raw attachment fields. For example, a mount created with `--volume-options noexec,nosuid --volume-readonly` renders as: ``` [ { "entry_name": "node-js-data", "host_path": "/var/lib/dokku/data/storage/node-js-data", "container_path": "/app/storage", "readonly": true, "volume_options": "noexec,nosuid" } ] ``` ### Creating storage directories > [!IMPORTANT] > New as of 0.25.5 A storage directory can be created with the `storage:ensure-directory` command. This command will create a subdirectory in the recommended `/var/lib/dokku/data/storage` path - created during Dokku installation - and prepare it for use with an app. When Dokku itself runs in a container with a shared Docker socket, default named storage is still created under `DOKKU_LIB_ROOT` (typically `/var/lib/dokku`) inside the Dokku container. Docker `-v` mounts for `storage:exec` and app deploys rewrite that path to `DOKKU_LIB_HOST_ROOT` so the host Docker daemon binds the directory from the host-visible data volume. See the [Docker installation notes](/docs/getting-started/install/docker.md) for setting `DOKKU_LIB_HOST_ROOT`. ```shell dokku storage:ensure-directory node-js-app ``` ``` -----> Ensuring /var/lib/dokku/data/storage/node-js-app exists Setting directory ownership to 32767:32767 Directory ready for mounting ``` By default, permissions are set for usage with Herokuish buildpacks. These permissions can be changed via the `--chown` option according to the following table: - `--chown herokuish` (default): Use `32767:32767` as the folder permissions. - This is used for apps deployed with Buildpacks via Herokuish. - `--chown heroku`: Use `1000:1000` as the folder permissions. - This is used for apps deployed with Cloud Native Buildpacks using the `heroku/builder` builder. - `--chown paketo`: Use `2000:2000` as the folder permissions. - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `paketo` builders. - `--chown root`: Use `0:0` as the folder permissions. - This is used for containers that run their processes as root, as is typical for most Dockerfile or Docker image deploys. - `--chown false`: Skips the `chown` call. - `--chown `: Use `:` as the folder permissions, where `` is a custom numeric user/group id. - This is used for containers that run their processes as a uid/gid that doesn't correspond to any of the above named options. Users deploying via Dockerfile will want to specify `--chown false` and manually `chown` the created directory if the user and/or group id of the runnning process in the deployed container do not correspond to any of the above options. The `--chown` flag - whether on `storage:create` or `storage:ensure-directory` - only manages the default `/var/lib/dokku/data/storage/` location. If a custom `` is passed to `storage:create`, the chown call is refused and the operator must chown the path themselves. > [!WARNING] > Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory. ### Setting directory permissions > [!IMPORTANT] > New as of 0.38.27 Where `--chown` states who owns the host directory, `--mode` states its permission bits. It takes a 3 or 4 digit octal mode, and is a `--mode` flag on `storage:create` and a `mode` property on `storage:set`: ```shell dokku storage:create node-js-data --mode 0777 ``` ```shell dokku storage:set node-js-data mode 0770 ``` Omitting the value clears the mode, leaving the directory's permissions alone on subsequent runs: ```shell dokku storage:set node-js-data mode ``` Without a mode, a newly created directory keeps the `0755` default and a pre-existing directory keeps whatever permissions it already had. The value is stored on the entry and re-applied every time `storage:create` or `storage:set` runs against it, so a declarative caller converges the directory by re-running the same command rather than reaching for `chmod` over SSH. The mode is shown by `storage:info`: ```shell dokku storage:info node-js-data ``` ``` -----> Storage entry node-js-data Scheduler: docker-local Host path: /var/lib/dokku/data/storage/node-js-data Mode: 0777 ``` The mode is applied to the directory itself and does not recurse into its contents. Like `--chown`, it is docker-local only and only manages the default `/var/lib/dokku/data/storage/` location - it is refused for k3s entries and for entries created with a custom ``. That refusal also covers migrated `legacy-*` entries, whose host paths come from the original colon-form mount rather than the default location. ### Updating a storage entry > [!IMPORTANT] > The property form is new as of 0.38.27. Prior versions used flags, which still work but emit a deprecation warning. An existing entry is edited with `storage:set`, which takes a property and a value. Omitting the value unsets the property, restoring whatever the entry defaults to: ```shell dokku storage:set node-js-data chown herokuish dokku storage:set node-js-data chown ``` The following properties can be set: | Property | Description | Unsetting it means | |---|---|---| | `chown` | Ownership preset or numeric uid for the host directory | no chown is performed | | `mode` | Octal permissions for the host directory | permissions are left alone | | `namespace` | Namespace holding the PVC (k3s) | the `default` namespace | | `reclaim-policy` | Whether the underlying volume survives `storage:destroy` | `Retain` | | `size` | PVC size (k3s) | rejected, since k3s entries require a size | | `access-mode` | PVC access mode (k3s) | rejected, see below | | `storage-class-name` | PVC storage class (k3s) | rejected, see below | `access-mode` and `storage-class-name` cannot be changed on an entry that already exists, because Kubernetes cannot apply either to a bound PVC. Both a different value and an empty one are refused, since clearing is equally a change: ```shell dokku storage:set node-js-data access-mode ReadWriteMany ``` ``` ! storage:set cannot change access-mode in place; recreate the entry ``` Setting `chown` or `mode` on a docker-local entry applies the change to the host directory immediately. Every other property is a metadata write, and k3s entries re-apply their helm release so the cluster picks the change up. The older flag form - `dokku storage:set node-js-data --mode 0770` - continues to work and warns. It gained unset semantics too, so `--mode ""` clears the mode the same way omitting the positional value does. ### Annotations and labels > [!IMPORTANT] > New as of 0.38.27 Annotations and labels are attached to a storage entry one key at a time, matching the [scheduler-k3s equivalents](/docs/deployment/schedulers/k3s.md#setting-annotations). On k3s they propagate to both the PersistentVolumeClaim and the PersistentVolume, so backup tools like Velero and Longhorn can find the volume. ```shell dokku storage:annotations:set node-js-data backup.velero.io/backup-volumes node-js-data dokku storage:labels:set node-js-data app.kubernetes.io/part-of billing ``` Keys may contain `/`, as the Kubernetes-style keys above do, and are stored verbatim. To clear a single key, omit the value. Other keys are left untouched, so a declarative caller does not need to re-send the whole set on every call: ```shell dokku storage:annotations:set node-js-data backup.velero.io/backup-volumes ``` Configured annotations and labels can be inspected with the matching report commands. Without an entry name they cover every registered entry: ```shell dokku storage:annotations:report dokku storage:annotations:report node-js-data dokku storage:labels:report node-js-data ``` ``` =====> node-js-data annotations information Annotation backup.velero.io/backup-volumes: node-js-data ``` JSON output emits the keys flat, and a single value can be read directly with a flag of the form `--storage-annotations.` (or `--storage-labels.`), which requires an entry name: ```shell dokku storage:annotations:report node-js-data --format json dokku storage:annotations:report node-js-data --storage-annotations.backup.velero.io/backup-volumes ``` `storage:create` still accepts repeatable `--annotation key=value` and `--label key=value` flags for setting the initial set at creation time. The same flags on `storage:set` are deprecated in favor of these commands, because they replace the entire map rather than a single key. ### Mounting storage into apps Dokku supports mounting both explicit host paths as well as docker volumes via the `storage:mount` command. This takes two arguments, an app name and a `host-path:container-path` or `docker-volume:container-path` combination. ```shell # mount the directory into your container's /app/storage directory, relative to the container root (/) # explicit host paths _must_ exist prior to usage. dokku storage:mount node-js-app /var/lib/dokku/data/storage/node-js-app:/app/storage # mount the docker volume into your container's /app/storage directory, relative to the container root (/) # docker volumes _must_ exist prior to usage. dokku storage:mount node-js-app some-docker-volume:/app/storage ``` In the first example, Dokku will then mount the shared contents of `/var/lib/dokku/data/storage/node-js-app` to `/app/storage` inside the container. The mount point is *not* relative to your app's working directory, and is instead relative to the root (`/`) of the container. Mounts are only available for containers created via `run` and by the deploy process, and not during the build process. A mount is bound into every process type unless `--process-type` narrows it - see [scoping a mount to a process type](#scoping-a-mount-to-a-process-type). In addition, the host path is never auto-created by either Dokku or Docker, and should be an explicit path, not one relative to the current working directory. > If the `/storage` path within the container had pre-existing content, the container files will be over-written. This may be an issue for users that create assets at build time but then mount a directory at the same place during runtime. Files are not merged. For named storage entries, additional Docker mount options can be passed via `--volume-options`. The value is a comma-separated mount-options string stored verbatim on the attachment and rendered into the `-v` flag at deploy time. This is useful for SELinux labels (`Z`, `z`) or hardening flags (`noexec,nosuid`): ```shell dokku storage:create node-js-data dokku storage:mount node-js-app node-js-data --container-dir /app/storage --volume-options Z ``` When combined with `--volume-readonly`, the rendered options become `ro,` - for example, `--volume-options noexec,nosuid --volume-readonly` renders as `:ro,noexec,nosuid`. Re-running `storage:mount` against a named entry with the same `--container-dir` and `--process-type` updates the existing attachment's mount-time attributes (`--phase`, `--volume-subpath`, `--volume-readonly`, `--volume-chown`, `--volume-options`) in place rather than appending a duplicate. This is the idempotent equivalent of `storage:set` for entries, and lets declarative tooling change a mount-time attribute without an unmount-then-remount dance that would briefly drop the volume from `storage:report`. Mount-time fields are rewritten wholesale, not merged - omitting a flag on a re-mount clears any previously-set value. The legacy `host:container[:opts]` form still rejects duplicates with `Mount path already exists.`. Once persistent storage is mounted, the app requires a restart. See the [process scaling documentation](/docs/processes/process-management.md) for more information. ```shell dokku ps:restart app-name ``` #### Scoping a mount to a process type > [!IMPORTANT] > New as of 0.38.29 By default a mount is bound into every one of an app's containers. `--process-type` narrows it to a single Procfile process type, which is how a worker gets a scratch volume the web process has no business seeing: ```shell dokku storage:create node-js-scratch dokku storage:mount node-js-app node-js-scratch --container-dir /scratch --process-type worker ``` The magic `_default_` process type is the unscoped case, and it is what a mount gets when `--process-type` is omitted. Default-scoped mounts are bound into every process; a mount scoped to a named process type is bound only into that one. Some containers belong to no process type at all - a `dokku run` one-off, the ephemeral containers that run `app.json` deploy tasks, and k3s cron jobs. Those receive default-scoped mounts only, since there is no process type for a named scope to match. On k3s this applies to the deploy phase; `--phase run` attachments are not mounted there at all. A container path can be claimed by only one mount per process type, so `storage:mount` rejects a container path that an overlapping scope already holds. The default scope overlaps every named one: ```shell dokku storage:create node-js-data dokku storage:create node-js-cache dokku storage:mount node-js-app node-js-data --container-dir /app/storage # fails: the default-scoped mount above also applies to web dokku storage:mount node-js-app node-js-cache --container-dir /app/storage --process-type web ``` Two *named* scopes never apply to the same container, so they may each bind a different entry at the same container path: ```shell dokku storage:mount node-js-app node-js-data --container-dir /app/storage --process-type web dokku storage:mount node-js-app node-js-cache --container-dir /app/storage --process-type worker ``` #### Replacing the entire mount set > [!IMPORTANT] > New as of 0.38.29. Per-mount attributes in the option list new as of 0.38.30. The form above mounts one entry at a time, so matching an app's mounts to a declared set means 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. The `--replace` flag writes the whole set in a single call, taking `name:container-dir` pairs instead of a single entry and a `--container-dir` flag. ```shell dokku storage:mount --replace node-js-app node-js-data:/app/storage node-js-cache:/cache ``` Anything previously mounted and not named in the call is unmounted. Each pair takes the same optional third field as the legacy colon form, a comma-separated list, and that list carries every mount-time attribute the mount needs, so two mounts declared in one call can differ in all of them: ```shell dokku storage:mount --replace node-js-app \ node-js-data:/app/storage:ro,Z,volume-subpath=uploads,volume-chown=herokuish \ node-js-cache:/cache:phase=deploy,phase=run,noexec ``` | Token | Meaning | |---|---| | `ro` | Mount the volume read-only | | `rw` | Mount it read-write, the explicit opposite of `ro` and the default | | `volume-subpath=` | Subpath within the entry | | `volume-chown=