Volumes

Volumes give containers persistent storage that survives restarts, redeploys, image rebuilds, and container replacement.

In HubFly, managed volumes are project-scoped storage blocks that you can mount into containers and Compose services. Use them when your application needs data that must outlive a single container filesystem.

Common examples include database data, user uploads, CMS media, generated assets, queues, search indexes, application state, and Docker Compose named volumes.

When To Use A Volume

Use a volume for data that your application writes at runtime and needs later.

• A PostgreSQL container writing to /var/lib/postgresql/data
• A WordPress or CMS container storing uploaded media
• A Rails, Laravel, Django, or Node.js app storing generated files
• A worker sharing processed assets with an API container
• A Compose stack using named volumes such as postgres-data or redis-data

Do not use a volume for data that belongs in the image, such as compiled app code, dependencies, static binaries, or files that should be recreated on every deploy.

Persistent Vs Ephemeral Storage

Every container has an ephemeral filesystem. That filesystem is tied to the container lifecycle and can be replaced during deploys, rollbacks, or recovery.

A mounted volume is different. Data written under the mount path is stored in the managed volume, not only inside the container layer.

For example, if you mount a volume at /data, files written to /data persist. Files written to /tmp, /app, or any other unmounted path follow normal container filesystem behavior.

Create A Volume

You can create a volume from the project storage area or while configuring a new container. The creation flow has four steps:

1. Basic configuration
2. Driver and storage
3. Performance and security
4. Review

The required fields are the volume name and size.

Name And Description

Choose a name that describes the workload, not the implementation detail.

Good examples:

• postgres-data
• uploads
• media-assets
• redis-state
• cms-content

In the dashboard, names are entered as lowercase alphanumeric values with hyphens. The backend also accepts underscores, but lowercase names with hyphens are easier to read and work better across deployment tools.

Use the description field to explain ownership and purpose, especially for production data. For example: Stores customer uploads for the production API.

Size And Pricing

Volume size is configured in GB or TB. The dashboard includes quick presets:

• Database Start: 1 GB
• Assets/Images: 10 GB
• Large Storage: 100 GB

You can also enter a custom size. Volumes larger than 10 GB are treated as Large Storage and priced differently. The create flow shows an hourly and monthly cost estimate before the volume is created.

Pick a size based on expected growth, not only current usage. Volumes can be expanded later, but they cannot be shrunk.

Storage Driver

The dashboard currently exposes HubBlock as the managed storage backend for new volumes.

HubBlock is designed for persistent container storage on HubFly projects. It is the default choice for stateful containers, Docker volume mounts, and Compose named volumes.

Labels And Tags

Labels help you organize storage by team, environment, workload, compliance scope, or automation.

Useful labels include:

• env=production
• service=postgres
• owner=backend
• workload=database
• retention=critical

HubFly also adds reserved labels for internal management, project ownership, and optimization metadata. Reserved labels that start with com.hubfly should not be edited manually.

Performance Mode

Volumes include performance mode selection during creation.

• Standard: reliable default behavior for simple persistent storage
• Balanced: recommended for most production web apps and APIs
• High Performance: better fit for heavier I/O workloads such as databases, queues, indexing, or processing pipelines

If you are unsure, start with Balanced. For databases or storage-heavy services, use labels such as workload=database and choose High Performance when the workload is latency-sensitive.

Mount A Volume

A volume is useful after it is attached to a container or Compose service. When you attach a volume, you choose a mount path inside the container.

Examples:

/data
/var/lib/postgresql/data
/app/uploads
/usr/share/nginx/html/uploads

After deployment, application reads and writes under that path use the managed volume.

For a single-container deployment, use the storage step, choose an existing volume, and set the mount point. Template deployments may suggest mount points based on the selected template.

For a Compose stack, named volumes are attached through the service mounts configuration or imported from compatible Docker Compose YAML.

Compose Named Volumes

Compose stacks can create and attach named volumes for services.

Example:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
 
volumes:
  postgres-data:

When imported into HubFly Compose, named volume mounts are converted into managed volume mounts. Host bind mounts are skipped because they depend on a specific host filesystem path and are not portable across managed deployment regions.

Shared Mounts

A volume can be mounted by multiple containers in the same project. This is useful for services that intentionally share files, such as an API writing uploads and a worker processing those uploads.

Shared volumes require application-level coordination. A shared file volume is not a database cluster, distributed lock manager, or consistency layer by itself. If multiple containers write to the same files, design your application to handle locking, atomic writes, and concurrent access safely.

For read-heavy shared assets, keep one service responsible for writing and let other services read from the shared mount.

File Browser Access

The volume detail page can generate a temporary HubFly Files session for direct browser access to the volume contents.

The file browser lets you browse, upload, edit, and delete files without opening a shell into the container. Sessions expire after one hour.

File browser access depends on the volume being accessible on the host. If the volume is not currently mounted or cannot be resolved by the storage backend, the dashboard will show an error instead of a session URL.

Use file browser access for operational tasks such as uploading seed files, inspecting generated assets, editing small configuration files, or recovering a known file. Do not use it as a replacement for application-level backups, migrations, or version-controlled configuration.

Monitoring And Usage

The volume detail page shows storage and runtime information when available:

• provisioned size
• used storage
• allocated storage
• usage percentage
• read and write I/O
• read and write throughput
• optimization mode
• attached containers and mount paths

Use this information to catch growth early. If a database or uploads directory is growing quickly, expand the volume before it reaches capacity.

Resize A Volume

Volumes support scale-up resizing.

You can increase the size of an existing volume from the volume detail page. The new target size must be larger than the current size. Shrinking an existing volume is not supported.

Plan resizing around the application using the volume. Some filesystems and databases can use expanded capacity immediately. Others may require a restart, filesystem growth step, migration, or application-level maintenance window.

Transfer A Volume

A detached volume can be transferred to another project in the same region.

Transfer rules:

• You need volume management permission on the source project.
• You need volume management permission on the target project.
• The target project must be in the same region as the volume.
• The volume must not be mounted to any container.

Transfers move project ownership. They do not move the volume to another region. If you need storage in a different region, create a new volume in that region and migrate the data at the application level.

Delete A Volume

Deleting a volume permanently removes its storage record and data.

A mounted volume cannot be deleted. Detach it from every container first. The volume detail page shows attached containers and mount paths so you can find what is using the volume before deleting it.

For production systems, confirm that you have a current backup or export before deleting persistent storage.

Production Recommendations

Name volumes after the data they hold, not the container using them. A name like postgres-data remains meaningful after the container is redeployed or replaced.

Keep one primary writer when possible. Shared volume writes are possible, but they are safest when one service owns writes and other services read.

Mount volumes only at paths your application expects. Accidentally mounting over an application directory can hide files that were baked into the image.

Use labels for ownership and environment. Labels make it easier to audit storage later, especially when a project contains many containers or Compose services.

Monitor usage before capacity becomes urgent. Expanding is supported; shrinking is not.

Use application-native backups for important state. A persistent volume keeps data across container lifecycle events, but persistence is not the same thing as a backup strategy.

Troubleshooting

My Data Disappeared After Redeploy

Confirm that the application writes to the mounted path. Data written outside the mount path is stored in the container filesystem and may not survive a redeploy.

The Container Cannot See The Files

Check the mount path configured on the container or Compose service. The app must read from the same path where the volume is mounted.

Also check file ownership and permissions inside the container. Some images run as a non-root user and may need the directory permissions adjusted by the app or entrypoint.

I Cannot Delete A Volume

The volume is probably still attached to one or more containers. Open the volume detail page, review the attached containers list, and detach or remove those containers first.

I Cannot Transfer A Volume

Transfers require the volume to be detached and the target project to be in the same region. If the target project is in another region, create a new volume in that project and migrate the data.

The File Browser Does Not Open

A file browser session requires the storage backend to return an accessible host mount path. If the volume is not currently accessible, mount it to a container first or retry after the storage backend reports the volume as available.

I Need Less Storage Than I Allocated

Volumes cannot be shrunk in place. Create a smaller volume, copy the data you need, update the container mount, verify the application, and then delete the old volume after backup validation.

FAQ

Are Volumes The Same As Docker Volumes?

They serve the same role for applications: persistent storage mounted into a container path. HubFly manages the underlying storage lifecycle and connects the volume to your container or Compose service.

Can I Mount One Volume Into Multiple Containers?

Yes, within the same project. Make sure your application can safely handle concurrent file access.

Can I Move A Volume To Another Region?

No. Volume transfer is project-to-project within the same region. Cross-region movement requires creating storage in the target region and migrating data.

Can I Resize Down?

No. Existing volumes support scale-up only.

Do Volumes Replace Backups?

No. Volumes preserve runtime data across container lifecycle changes, but they are not a full backup policy. Use database dumps, object exports, snapshots, or application-level backup workflows for critical production data.