Skip to content
PLANOVI Docs

Storage Volumes & Persistence

Data integrity and persistence across container redeployments are fundamental to the Planovi VPS infrastructure. State is managed strictly via Docker named volumes and explicitly isolated host filesystem paths.

💾 Docker Named Volumes

The master docker-compose.yml configures persistent named volumes backed by the host’s 200 GB NVMe storage:

Volume NameTarget Container PathContent Description
supabase-db-data/var/lib/postgresql/dataPostgreSQL 15 database clusters, tables, indexes, WAL logs, and extensions
supabase-storage-data/var/lib/storageUploaded member declarations, contract PDFs, invoice documents, and avatars

Both volumes reside in /var/lib/docker/volumes/ on the host, ensuring that rebuilding or upgrading container images never impacts operational data.

🗂️ Host Filesystem Allocation

Host storage is divided into distinct lifecycle zones:

/
├── var/lib/docker/volumes/            # Docker persistent database & file storage volumes
│   ├── vps-stack_supabase-db-data/    # Live PostgreSQL database data files
│   └── vps-stack_supabase-storage-data/# Live object storage files
│
├── opt/
│   ├── vps-stack/
│   │   └── backups/                   # Nightly compressed database snapshots (.sql.gz)
│   │
│   └── vps-apps/                      # Cloned application Git repositories
│       ├── webpage/
│       ├── microservices/
│       ├── flutter-app/
│       ├── converters/
│       └── backend/

Storage Quota Guidelines

  • PostgreSQL Database (supabase-db-data): Typically consumes 2–8 GB. Automatic index maintenance runs via periodic vacuuming.
  • Object Storage (supabase-storage-data): Configured with a default file size limit of 50 MB (FILE_SIZE_LIMIT: "52428800").
  • Daily Backups (/opt/vps-stack/backups): Kept compressed (gzip). Retention policies clean snapshots older than 14 days to prevent storage bloat.

🚚 Storage File Migration Pipeline (migrate-storage-files.py)

When migrating storage assets from cloud-hosted Supabase instances (e.g. Supabase Cloud S3 buckets) to the self-hosted storage container on the VPS, the migration script /opt/vps-stack/scripts/migrate-storage-files.py handles recursive transfer:

# Execution on host
python3 /opt/vps-stack/scripts/migrate-storage-files.py \
    --source-s3 s3://supabase-cloud-bucket \
    --destination /var/lib/docker/volumes/vps-stack_supabase-storage-data/_data \
    --verify-checksum

The script:

  1. Streams files directly into the target bucket directory hierarchy on disk.
  2. Preserves MIME types and object paths matching Supabase metadata tables (storage.objects).
  3. Verifies MD5 checksums post-transfer.
  4. Corrects file permissions so the supabase-storage container user (UID 1000) has read/write ownership.