Storage

This section describes how device storage is laid out by default and how to add your own partitions and mounts or expand storage to use the whole disk.

Default disk layout

A device’s primary disk is divided into a small number of areas, each with a distinct role:

Area Role Persistent Encrypted by default
Boot Files required to start the device Yes No
Configuration Device settings, identity, administrator password, hooks Yes Yes (when encryption is enabled)
System images The OS image(s) used to boot, including the version you can roll back to Yes No
Data Container images, workload data, and logs Yes Yes (when encryption is enabled)

The data area takes the remaining space on the disk, so most of the disk is available to your workloads. The configuration and data areas hold everything you set up; the boot and system-image areas belong to the OS and are managed for you across upgrades.

Configuring additional partitions and mounts

You can attach extra storage and control where it is mounted using a storage mapping. The mapping is a YAML document that lists the partitions a device should ensure exist and where each should be mounted, plus any bind mounts that redirect a directory to persistent storage.

You can provide the storage mapping when you create an install image (so it applies from first boot) or push it from the dashboard.

Mapping format

A storage mapping has two sections: diskmappings (partitions to ensure and mount) and bindmounts (directories to redirect).

diskmappings:
  - disk: /dev/sdb
    partition_number: 1
    mountpoint: /mnt/extra
    size: 50G
    filesystem: ext4
  - disk: /dev/sdb
    partition_number: 2
    mountpoint: /mnt/scratch
    size: -1            # use all remaining free space
    filesystem: ext4

bindmounts:
  - mountsource: /mnt/extra/registry
    mountpoint: /var/lib/registry

The fields for each diskmappings entry:

Field Required Meaning
disk Yes The target disk or partition (for example, /dev/sdb).
partition_number When disk is a whole disk Which partition to create or use.
mountpoint Yes Absolute path, or a logical name (see below).
size For new partitions Size with an SI suffix (500M, 1G, 2T), or -1 to use all remaining free space.
filesystem For new partitions Filesystem to create, for example ext4.

Behavior to keep in mind:

  • If a partition already exists, it is mounted as specified; size and filesystem are ignored (existing data is not reformatted).
  • If a partition does not exist and there is room, it is created with the requested size and filesystem, then mounted.
  • A partition with size: -1 grows to fill the free space available on its disk.

Logical mount names

For convenience, a few common destinations can be referenced by name instead of an absolute path:

Logical name Mounts at
logs /var/log
docker /var/lib/docker
droplet the device agent’s working directory

Bind mounts

A bind mount redirects a directory onto persistent storage so its contents survive reboots and upgrades. By default, the standard runtime directories (container storage, logs, and the agent’s working directory) are already bound to the data area; add your own entries only when you want additional directories to persist or to live on a separate disk.

Expanding storage

When you install onto a disk that is larger than the image, the data area can be grown to use the extra space:

  • During installation you can request that the last partition be expanded to fill the disk.
  • A storage mapping entry with size: -1 grows the data partition to consume the remaining free space.

This lets a single image target disks of different sizes while still using all available capacity for workloads and data.

Next steps