render-oss/render-disks

Render Persistent Disks

Persistent disks are high-performance SSDs you attach to a Render service to preserve filesystem changes across deploys and restarts. Without a disk, services have an ephemeral filesystem—all local file changes are lost on every deploy.

When to Use

• Storing file uploads, CMS media, or user-generated content
• Running a self-managed database (MySQL, MongoDB, ClickHouse) on Render
• Deploying stateful infrastructure (Elasticsearch, Kafka, RabbitMQ, Mattermost)
• Understanding why scaling is blocked or zero-downtime deploys are disabled
• Restoring data from an automatic disk snapshot

For managed databases, prefer Render Postgres (render-postgres) or Key Value (render-keyvalue) over self-managed alternatives on disk.

Critical Constraints

These constraints affect architecture decisions. Understand them before attaching a disk:

| Constraint | Impact | |------------|--------| | Single instance only | Cannot scale horizontally (numInstances must be 1, autoscaling not available) | | No zero-downtime deploys | Old instance stops before new instance starts (brief downtime on each deploy) | | Runtime access only | Disk is not available during buildCommand or preDeployCommand (those run on separate compute) | | Not accessible from other services | Only the attached service can read/write the disk | | Not available on cron jobs | Attach to a web service, private service, or background worker instead | | Not available on one-off jobs | One-off jobs run on separate compute without disk access | | Can increase size, cannot decrease | Start small and grow as needed |

Setup

Dashboard

1. Go to your service's Disks page
2. Set the mount path (absolute path where persistent data is stored)
3. Choose a size in GB
4. Click Add disk — triggers a new deploy

Blueprint

services:
  - type: web
    name: cms
    runtime: node
    plan: starter
    region: oregon
    buildCommand: npm ci && npm run build
    startCommand: npm start
    disk:
      name: cms-data
      mountPath: /var/data
      sizeGB: 10

Mount Path

Only files written under the mount path are preserved. Everything else remains ephemeral.

| Runtime | Source code path | Example mount path | |---------|------------------|--------------------| | Node.js, Python, Ruby, Elixir, Rust | /opt/render/project/src | /opt/render/project/src/uploads | | Go | /opt/render/project/go/src/github.com/<user>/<repo> | .../data | | Docker | Dockerfile's WORKDIR (commonly /app) | /app/storage |

Disallowed mount paths

Cannot mount at: /, /opt, /opt/render, /opt/render/project, /opt/render/project/src, /home, /home/render, /etc, /etc/secrets.

Subdirectories of these paths are fine (e.g. /opt/render/project/src/uploads).

Snapshots

• Render creates an automatic snapshot every 24 hours
• Snapshots are available for at least 7 days
• Restore from the service's Disks page in the Dashboard
• Full restore only — you cannot restore individual files
• Destructive — all changes after the snapshot are lost

Do not restore snapshots for custom database recovery. Use database-native backup tools (mysqldump, mongodump) instead—disk snapshots may capture a corrupted database state.

File Transfers

SCP (via SSH)

# Download from service
scp -s [email protected]_REGION.render.com:/mount/path/file ./local-file

# Upload to service
scp -s ./local-file [email protected]_REGION.render.com:/mount/path/file

Requires SSH access enabled for the service.

Magic-Wormhole

Available on all native runtimes (install manually on Docker):

# On the service shell
wormhole send /mount/path/file

# On your local machine
wormhole receive

Common Patterns

| Pattern | Service type | Mount path | Notes | |---------|-------------|------------|-------| | WordPress / Ghost / CMS | Web Service | /var/data or /app/content | Media uploads, SQLite | | Self-managed MySQL | Private Service | /var/lib/mysql | Use mysqldump for backups, not disk snapshots | | File upload API | Web Service | /opt/render/project/src/uploads | Single instance constraint | | Elasticsearch | Private Service | /usr/share/elasticsearch/data | Stateful search infrastructure |

Common Mistakes

| Mistake | Fix | |---------|-----| | Expecting horizontal scaling with a disk | Not possible — disk services are single-instance only | | Mounting at a disallowed path | Use a subdirectory (e.g. /opt/render/project/src/uploads not /opt/render/project/src) | | Reading disk during build or pre-deploy | These run on separate compute — move logic to the start command | | Restoring disk snapshot for a database | Use database-native backups instead | | Starting with a large disk size | Start small — you can increase but never decrease |

References

| Document | Contents | |----------|----------| | references/sizing-and-snapshots.md | Sizing guidance, snapshot lifecycle, restore procedures, cost patterns |

Related Skills

• render-web-services — Deploy lifecycle, health checks (disk disables zero-downtime)
• render-private-services — Internal services with disks (Elasticsearch, MySQL)
• render-blueprints — disk field reference in render.yaml
• render-postgres — Managed database alternative (no disk management needed)