Persistent Volumes & File Storage

Learn how to configure persistent volume mounts to retain user uploads, local caches, and stateful application data across container redeployments.

1. Ephemeral Containers vs Persistent Volumes

By default, Docker containers have an ephemeral filesystem. Any file written inside a container (e.g. user avatar uploads, SQLite databases, generated PDFs) is lost when the container stops, redeploys, or rolls back.

TurboV provides Persistent Volumes to map dedicated host directories directly into your container instances:

[ Host Filesystem: /var/lib/turbov/applications/<appId>/volumes/<name>/ ]
                                │
                                │ (Persistent across redeployments)
                                ▼
         [ Container Path: /app/uploads or /data/storage ]

2. Adding a Volume Mount

To attach persistent storage to an application:

  1. Open your application in the dashboard and select Settings → Volumes.
  2. Click Add Volume Mount.
  3. Configure the mount:
    • Volume Name: A unique identifier (e.g. user-uploads, sqlite-data).
    • Mount Path: The absolute path inside the container (e.g. /app/uploads or /data).
  4. Click Save & Redeploy.

The agent creates the directory on the host at:

/var/lib/turbov/applications/<appId>/volumes/<volumeName>/

and mounts it into the container during startup.

3. Permissions & Ownership (UID / GID)

A common issue in containerized storage is permission mismatches between host directories and non-root container users.

TurboV automatically manages directory permissions:

  • When creating a volume directory on the host, the agent initializes the path with appropriate read/write permissions for standard container users (such as UID 1000 / GID 1000 commonly used in Alpine and Debian node/python images).
  • If your container runs as a custom user or group, you can run terminal permissions adjustments via the in-dashboard App Commander.

4. Volume Persistence Lifecycle

  • Redeployments: When you push new code or update environment variables, the new container mounts the exact same host volume directory. All uploaded files and state are instantly available to the new container.
  • Rollbacks: Rolling back to an older deployment preserves the current volume contents.
  • Server Migration: If migrating your application to a new physical server, you can clone or transfer the /var/lib/turbov/applications/<appId>/volumes/ directory using standard rsync or include volumes in your automated Backup Schedules.