Volume Management Guide for Multi-Client Deployments

Generated: 2025-08-11 UTC
Updated: 2025-08-12 UTC - Simplified to 2-volume architecture
Purpose: Comprehensive guide for managing service-specific volumes in Sliplane deployments

Critical Requirement: Client Data Isolation

Each client deployment MUST have completely separate volumes. Sharing volumes between clients is a severe security risk that will cause:

Data breaches - Clients can access each other's data
Database corruption - Multiple services writing to same SQLite database
Compliance violations - Most regulations require data separation
Privacy issues - Client A should never see Client B's information

Volume Naming Convention

Standard Pattern

{client-id}-{volume-type}

Examples

hirebest-data         # HireBest's database volume
hirebest-docs         # HireBest's documentation volume
sasha-main-data       # Main deployment's database
acme-corp-uploads     # ACME Corp's upload storage

Volume Types - "Starter" Sizing (Simplified to 2 Essential Volumes)

Each service deployment needs exactly 2 volumes with efficient "Starter" sizing:

{service-name}-home - All user data, Claude config, workspaces (2Gi starter, scales to 5Gi+)
{service-name}-data - SQLite database storage (10Mi - handles thousands of records)

IMPORTANT: Each service gets its own dedicated volumes - NO sharing between services!

The home volume contains ALL user data:

Claude CLI configuration at /home/nodejs/.claude/
User workspaces at /home/nodejs/.claude/projects/workspace/
Documentation at /home/nodejs/.claude/projects/workspace/docs/
File uploads at /home/nodejs/uploads/
Application config at /home/nodejs/config/

Why "Starter" sizing works:

2Gi home volume handles most use cases (can scale to 5Gi when needed)
SQLite is incredibly efficient - 10Mi can store thousands of records
Easy to scale up volumes when growth requires it

Complete Volume Setup Per Service

Production Example - linzoid-sasha-studio

Volume Name                      Mount Path       Size    Purpose
──────────────────────────────────────────────────────────────────
linzoid-sasha-studio-home    →  /home/nodejs     2Gi     ALL user data, Claude config, workspaces
linzoid-sasha-studio-data    →  /app/data        10Mi    SQLite database

Client Example - hirebest

Volume Name                Mount Path       Size    Purpose
────────────────────────────────────────────────────────────
hirebest-home          →  /home/nodejs     2Gi     ALL user data, Claude config, workspaces
hirebest-data          →  /app/data        10Mi    SQLite database

Another Client Example - acme-corp

Volume Name                Mount Path       Size    Purpose
────────────────────────────────────────────────────────────
acme-corp-home         →  /home/nodejs     2Gi     ALL user data, Claude config, workspaces
acme-corp-data         →  /app/data        10Mi    SQLite database

Step-by-Step Sliplane Configuration

Creating Volumes for a New Service

CRITICAL: Volumes MUST be configured at service creation time in Sliplane!

Volumes cannot be added after service creation
Use the API deployment scripts which automatically include volumes
If creating manually, volumes must be defined when creating the service

Automatic Creation (Recommended)

# Volumes are automatically created with correct sizing
./scripts/deploy-with-api.sh CLIENT_NAME

Manual Creation in Sliplane Dashboard

When Creating a New Service
- In the service creation form, scroll to Volumes section
- Add exactly 2 volumes:
Volume 1 - Home Volume
- Volume Name: {service-name}-home
- Mount Path: /home/nodejs
- Size: 2Gi (starter) or 5Gi (growth)
Volume 2 - Data Volume
- Volume Name: {service-name}-data
- Mount Path: /app/data
- Size: 10Mi (handles thousands of records)
Verify Configuration
- Check that both volumes are listed
- Confirm each has correct mount path
- Ensure names follow {service-name}-{type} pattern

Common Mistakes to Avoid

1. Sharing Volumes (NEVER DO THIS)

❌ WRONG:
shared-data → hirebest-service → /app/data
shared-data → sasha-main-service → /app/data

Result: Both clients share the same database = data breach!

2. Generic Volume Names

❌ WRONG:
data → /app/data
docs → /app/docs

Problem: Can't tell which client owns which volume

3. Attaching Existing Volumes

❌ WRONG:
Using "Attach existing volume" for a new client

Problem: Might accidentally attach another client's volume

Correct Implementation

Proper Volume Isolation

✅ CORRECT:
hirebest-home → hirebest-service → /home/nodejs
hirebest-data → hirebest-service → /app/data

acme-corp-home → acme-corp-service → /home/nodejs
acme-corp-data → acme-corp-service → /app/data

Result: Complete data isolation between services

Clear Naming Convention

✅ CORRECT:
linzoid-sasha-studio-home
linzoid-sasha-studio-data
hirebest-home
hirebest-data

Benefit: Immediately clear which service owns each volume

Correct Mount Paths

✅ CORRECT:
{service-name}-home → /home/nodejs
{service-name}-data → /app/data

Benefit: Application finds everything where expected

Migration Guide for Existing Deployments

If you've already deployed with shared or incorrectly named volumes:

Step 1: Backup Existing Data

# SSH into your container
ssh user@your-sliplane-server

# Create backups
tar -czf backup-data.tar.gz /app/data
tar -czf backup-docs.tar.gz /app/docs
tar -czf backup-uploads.tar.gz /app/uploads

Step 2: Create New Client-Specific Volumes

Follow the volume creation steps above
Use proper naming convention

Step 3: Migrate Data

# Copy data to new volumes
cp -r /old-volume/* /new-volume/

Step 4: Update Service Configuration

Detach old volumes
Attach new client-specific volumes
Restart service

Step 5: Verify

# Check data is accessible
ls -la /app/data/
ls -la /app/docs/

Step 6: Remove Old Volumes

Once verified, delete old shared volumes
Keep backups for safety

Volume Sizing Guidelines

"Starter" Sizing (Recommended for Initial Deployments)

Our default "Starter" sizing is highly efficient:

home: 2Gi - Handles standard workspaces, docs, and uploads
data: 10Mi - Handles thousands of SQLite records

When to Scale Up

Home Volume (nodejs-home)

Starter: 2Gi (standard workspaces and documentation)
Growth: 5Gi (extensive documentation + moderate uploads)
Scale: 10Gi+ (heavy file uploads, multiple large projects)

Database (data)

Starter: 10Mi (thousands of records)
Growth: 100Mi (tens of thousands of records)
Scale: 1Gi (hundreds of thousands of records)
SQLite is incredibly space-efficient!

Cost Optimization

Starting with "Starter" sizing:

2Gi home volume reduces initial costs by 60% vs 5Gi
SQLite efficiency means 10Mi goes a long way
Easy to scale up when needed
Most services never need more than starter sizing

Verification and Troubleshooting

Verify Volume Isolation

# SSH into container
ssh user@sliplane-server

# Check volume mounts
df -h | grep app

# Should see client-specific volumes:
# /dev/vdb1  1.0G  33M  968M   4% /app/data     (hirebest-data)
# /dev/vdb2  5.0G  89M  4.9G   2% /app/docs     (hirebest-docs)

Common Issues

Issue: "Permission Denied" accessing volumes

Solution: Ensure volumes are mounted with correct permissions

chown -R nodejs:nodejs /app/data
chown -R nodejs:nodejs /app/docs

Issue: "Database is locked"

Cause: Multiple services accessing same SQLite database
Solution: Ensure each client has separate -data volume

Issue: Lost data after restart

Cause: Volumes not properly mounted
Solution: Check volume configuration in Sliplane dashboard

Best Practices

Document Volume Mapping
- Keep a spreadsheet of client → volume mappings
- Include creation dates and sizes
Regular Backups
- Implement automated backups per client
- Test restore procedures
Monitor Usage
- Set up alerts for volume capacity
- Plan for growth
Access Control
- Use Sliplane's team features to limit who can modify volumes
- Audit volume access logs
Naming Consistency
- Always use lowercase
- Use hyphens, not underscores
- Follow {client}-{type} pattern strictly

API Automation (Currently Implemented)

Volumes are now automatically created when deploying services via the API:

Current Automation Features

Automatic volume creation during service deployment
Service-specific volume naming
Correct sizing based on deployment type
Volumes defined at service creation (Sliplane requirement)

How It Works

# Deploy with automatic volume creation
./scripts/deploy-with-api.sh CLIENT_NAME

The deployment script automatically includes:

"volumes": [
    {
        "name": "{service-name}-home",
        "mountPath": "/home/nodejs"
    },
    {
        "name": "{service-name}-data",
        "mountPath": "/app/data"
    }
]

Note: Sliplane automatically assigns sizes to volumes. You may need to resize through the dashboard if different from defaults.