Mount Local Storage to a service

Runtime services mount a Local Storage volume through the volume field in zerops.yaml. The mount is part of the service's runtime configuration, so it is applied by a deploy.

The volume field

zerops.yaml

zerops:
  - setup: app
    run:
      base: nodejs@22
      volume:
        hostname: vol         # hostname of the Local Storage service
        mountPath: /srv/data  # optional, defaults to /mnt/{hostname}
        readOnly: false       # optional, defaults to false

Field	Required	Description
hostname	yes	Hostname of the Local Storage service in the same project.
mountPath	no	Absolute path the volume is mounted to inside the runtime containers. Defaults to /mnt/{hostname}. System directories (/etc, /var, /var/www, /tmp, ...) are rejected; their subdirectories are allowed.
readOnly	no	Mounts the volume read-only. Defaults to false. Use it for the "one writer, many readers" pattern and to protect data from accidental writes.

The minimal configuration is just the hostname:

run:
  volume:
    hostname: vol

The referenced service must exist in the project and must be a Local Storage service, otherwise the deploy fails with a validation error.

How the mount behaves

• The content is shared among all containers of the connected runtime service, and among all other runtime services that mount the same volume
• The mount point is owned by the zerops user and group, so your application can read and write without sudo
• Writes are immediately visible to every other container — a real local filesystem, not a network mount (see filesystem semantics)
• The volume is mounted in runtime containers only, not during build and prepare phases
• A runtime service mounts at most one Local Storage volume

All connected containers share one machine

Every container of every connected runtime service is placed on the same physical machine that holds the volume. This is what makes the shared local filesystem possible, but it ties all connected services to a single machine: a hardware failure affects them all at once, and horizontal scaling is limited by that machine's capacity. See co-location and scheduling.

Change or remove the mount

The volume field is applied by a deploy. To change the mount path, toggle readOnly, or disconnect from the volume, edit or remove the volume field in zerops.yaml and deploy again.

Caution

A Local Storage service cannot be deleted while runtime services still mount its volume. Remove the volume field from their zerops.yaml and deploy them first.