Local Storage on Zerops

Zerops Local Storage is a managed service that owns a persistent, locally-attached disk volume. Runtime services in the same project mount the volume to a directory of their choosing, and every container sees the same files through a real local filesystem — no network filesystem in between.

Because all connected containers run on the same physical machine and share one kernel, the volume behaves like a single local disk: file locking (flock, fcntl) works correctly across containers, memory-mapped files stay coherent, and a write in one container is immediately visible everywhere else. This is what makes SQLite (including WAL mode), Prometheus TSDB, and other filesystem-based databases safe on Local Storage — workloads that must never run on a network filesystem. See Technical details for the full semantics.

Quick start

Add a Local Storage service to your project:

zerops-import.yaml

services:
  - hostname: vol
    type: local-storage:single@1

  - hostname: app
    type: nodejs@22
    buildFromGit: https://github.com/myorg/myapp

Then mount it in the runtime service's zerops.yaml:

zerops.yaml

zerops:
  - setup: app
    run:
      base: nodejs@22
      volume:
        hostname: vol

After the next deploy, the volume is mounted at /mnt/vol in all containers of the app service. See Mount to a service for the full volume configuration including a custom mount path and read-only mounts.

Use cases

Local Storage is a good fit for:

SQLite and other embedded databases: full locking and mmap coherence make SQLite safe, including WAL mode with multiple connecting containers (single-writer restrictions still apply)
Single-node stateful apps: Prometheus, Gitea, and similar applications that keep their state in a local data directory — see the Gitea recipe ↗ for a complete example built on Local Storage
Sharing filesystem state: certificates, caches, and other files shared across containers and services within a project, with immediate visibility of writes
Anything that needs a real local filesystem: workloads that break on network filesystems because they rely on locking, mmap, inotify, or atomic renames

Not currently highly available

The volume lives on a single physical machine, together with every runtime service that mounts it. If that hardware fails, or when maintenance requires moving workloads elsewhere, Zerops moves the volume to a healthy server and every connected runtime service goes through a small outage — stop, move, start. Recovering the volume and its data is not guaranteed.

Automated backups are enabled by default and strongly recommended.

Choosing a storage type

Local Storage trades high availability for correctness and speed: it is the only storage type where lock-dependent workloads like databases are safe. An HA mode may be added in the future. See Storage on Zerops for a comparison with Object Storage and Shared Storage and guidance on which one to use.

Already on Shared Storage? Follow the migration guide to move your data to a Local Storage volume without changing your application.

Key trade-offs

Co-location: all containers of every connected runtime service are placed on the same physical machine as the volume. Connecting a volume therefore ties the runtime service itself to that machine — a hardware failure affects all connected services at once, and horizontal scaling is limited by the capacity of that machine.
One volume per runtime service: a runtime service mounts at most one Local Storage volume. Multiple runtime services can mount the same volume.
The volume is mounted in runtime containers only — it is not available during build and prepare phases.
Backups are .tar.gz archives of the live volume, so database files can be captured mid-write. Schedule an application-level copy (sqlite3 .backup) for a restorable database — see consistent database backups. Snapshot-based, point-in-time backups are planned.
Single container mode only; there is currently no HA mode.