# 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](/local-storage/tech-details) for the full semantics.

## Quick start

Add a Local Storage service to your project:

```yaml title="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`:

```yaml title="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](/local-storage/how-to/connect) 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](/local-storage/tech-details#filesystem-semantics))
- **Single-node stateful apps**: Prometheus, Gitea, and similar applications that keep their state in a local data directory — see the [Gitea recipe ↗](https://github.com/zeropsio/recipe-gitea) 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

:::caution 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](/local-storage/how-to/manage#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](/storage/overview) for a comparison with Object Storage and Shared Storage and guidance on which one to use.

Already on Shared Storage? Follow the [migration guide](/local-storage/how-to/migrate-from-shared-storage) 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](/local-storage/how-to/manage#consistent-database-backups). Snapshot-based, point-in-time backups are planned.
- Single container mode only; there is currently no HA mode.

## Next steps

- [Create Local Storage](/local-storage/how-to/create) — Create a service with zerops-import.yaml or in the GUI.
- [Mount to a service](/local-storage/how-to/connect) — The zerops.yaml volume field and how the mount behaves.
- [Manage & backups](/local-storage/how-to/manage) — Browse the volume over SSH and web shell, back up and restore.
- [Migrate from Shared Storage](/local-storage/how-to/migrate-from-shared-storage) — Move data from a deprecated Shared Storage to a Local Storage volume.
- [Technical details](/local-storage/tech-details) — Filesystem semantics, co-location, and failure behavior.

## Need help?

Stuck, or want to share what you built? Our core team and community are on Discord.

- [Discord](https://discord.com/invite/WDvCZ54) — Join the Zerops community on Discord. Ask questions and share your tips.
- [zCLI](/references/cli) — Get more out of Zerops with the command-line tool.