Deploy and Host PocketBase with MinIO Backups on Railway

PocketBase is a lightweight, open-source backend with a realtime database, authentication, file storage, access rules, REST API, realtime API, and admin dashboard.

This Railway template deploys PocketBase with Litestream backups to MinIO.

It includes four services:

• PocketBase — the backend application
• Bucket — the MinIO S3-compatible storage service
• MinIO Console — the web UI for inspecting buckets and backups
• Bucket Init — a helper service that creates the default backup bucket automatically

The goal is simple: run PocketBase quickly, keep its live data persistent, and replicate the PocketBase database to MinIO using Litestream.

About Hosting PocketBase with MinIO Backups

This template hosts PocketBase together with a self-hosted S3-compatible backup target.

PocketBase stores the live app data in a persistent volume. Litestream runs inside the PocketBase service and watches the PocketBase database file. MinIO stores the replicated backup objects. MinIO Console gives you a browser-based dashboard to check whether the backup bucket and objects exist. Bucket Init prepares the default bucket so Litestream can start writing backups without manual setup.

The services work together like this:

PocketBase
├─ Runs the backend app
├─ Stores live data in /data
└─ Runs Litestream

Litestream
├─ Watches /data/data.db
└─ Replicates the database to MinIO

Bucket
├─ Runs MinIO S3-compatible API
└─ Stores backup objects

Bucket Init
├─ Waits until MinIO is ready
└─ Creates the default backup bucket

MinIO Console
├─ Provides the web dashboard
└─ Lets you inspect buckets and backup objects

Backup flow:

PocketBase /data/data.db
      ↓
Litestream
      ↓
MinIO Bucket
      ↓
pocketbase/data.db

What This Template Includes

This template deploys:

• PocketBase backend service
• Litestream replication inside PocketBase
• MinIO S3-compatible storage service
• MinIO Console for backup inspection
• Bucket Init service for automatic bucket creation
• Persistent storage for PocketBase data
• Persistent storage for MinIO objects
• Internal Railway networking between PocketBase and MinIO
• Public URL for PocketBase
• Public URL for MinIO Console

PocketBase runs your app. Litestream backs up the database. MinIO stores the backup. Bucket Init creates the bucket. MinIO Console lets you verify the backup.

One-Click Deploy

After deploying the template:

1. Open the PocketBase public URL.
2. Go to /_/.
3. Create your PocketBase superuser account.
4. Open the MinIO Console public URL.
5. Log in using the generated MinIO root credentials.
6. Confirm the pocketbase-backups bucket exists.
7. Check that Litestream backup objects appear under pocketbase/data.db.

The template is designed so PocketBase can start quickly while the backup stack prepares itself in the background.

PocketBase Setup

Open your PocketBase URL:

https://your-pocketbase-app.up.railway.app/_/

Create your first superuser account.

If the setup page does not appear and you see a login screen, check the PocketBase logs. PocketBase may print a one-time setup link during first initialization.

After login, you can start creating:

• Collections
• Records
• Auth rules
• File fields
• API rules
• Hooks and migrations

MinIO Console Usage

Open the MinIO Console URL from Railway.

Use the generated credentials from the Bucket service:

MINIO_ROOT_USER
MINIO_ROOT_PASSWORD

From the console, you can:

• View the backup bucket
• Confirm Litestream objects are being created
• Inspect object paths
• Verify MinIO storage persistence
• Debug bucket or credential issues

Default bucket:

pocketbase-backups

Expected backup path:

pocketbase/data.db

Bucket Init Service

The Bucket Init service exists to avoid manual bucket creation.

On startup, it:

1. Waits for the MinIO Bucket service to become available.
2. Connects to MinIO using the generated root credentials.
3. Creates the default bucket if it does not already exist.
4. Keeps running so Railway shows the service as healthy/running.

This avoids the common Litestream error:

NoSuchBucket: The specified bucket does not exist

The intended startup flow is:

Bucket → Bucket Init + MinIO Console → PocketBase

Railway may start services in parallel, so Bucket Init includes retry logic and waits until MinIO is ready before creating the bucket.

Litestream Backups

Litestream continuously replicates the PocketBase database to MinIO.

Default live database:

/data/data.db

Default replica path in MinIO:

pocketbase/data.db

If Litestream starts before the bucket is ready, it may log temporary errors. Once Bucket Init creates the bucket, replication should continue normally.

If the error continues after Bucket Init says the bucket is ready, check that PocketBase and Bucket Init are pointing to the same MinIO service and bucket name.

Dependencies for PocketBase with MinIO Backups

This template depends on PocketBase, Litestream, MinIO, Railway private networking, and Railway persistent volumes.

PocketBase needs persistent storage for the live application database and uploaded files. MinIO needs persistent storage for backup objects. Litestream needs a reachable MinIO endpoint, valid credentials, and an existing backup bucket.

Deployment Dependencies

This template uses:

• Railway account
• PocketBase service
• Bucket service powered by MinIO
• MinIO Console service
• Bucket Init service
• Railway volume for PocketBase data
• Railway volume for MinIO object data
• Railway private networking
• Litestream for database replication

No external object storage provider is required. MinIO runs inside the same Railway project.

Persistent Storage

PocketBase stores app data in:

/data

This includes:

• PocketBase database
• Uploaded files
• Collections
• Users
• Auth data
• App configuration

MinIO also needs persistent storage for backup objects.

Do not rely on container filesystem storage for production data. Container filesystems are ephemeral and can be lost during rebuilds or redeployments.

Restore Behavior

Restore is disabled by default.

Only enable restore when recovering into a fresh or empty PocketBase volume.

Normal redeployments should not restore from backup automatically because that can overwrite or conflict with existing live data.

Recommended recovery flow:

1. Use a fresh PocketBase volume.
2. Enable restore.
3. Redeploy PocketBase.
4. Confirm the database was restored.
5. Disable restore again after recovery.

Useful URLs

PocketBase admin dashboard:

https://your-pocketbase-app.up.railway.app/_/

PocketBase REST API:

https://your-pocketbase-app.up.railway.app/api/

PocketBase health check:

https://your-pocketbase-app.up.railway.app/api/health

MinIO Console:

https://your-minio-console.up.railway.app

Troubleshooting

Bucket does not exist

If Litestream logs NoSuchBucket, Bucket Init may not have finished yet.

Check Bucket Init logs and wait until you see a message similar to:

Bucket ready: pocketbase-backups

If the error continues, restart or redeploy the PocketBase service.

Cannot log in to MinIO Console

Use the generated values from the Bucket service:

MINIO_ROOT_USER
MINIO_ROOT_PASSWORD

Do not use your PocketBase admin credentials for MinIO.

PocketBase setup page does not appear

Check the PocketBase service logs. PocketBase may print a one-time setup link for creating the first superuser.

Backup objects are not visible

Open MinIO Console and check:

• The pocketbase-backups bucket exists
• The object path pocketbase/data.db appears
• PocketBase logs show Litestream replication running
• Bucket Init completed successfully

Common Use Cases

• PocketBase backend with self-hosted backups
• MVP and small SaaS backend
• Internal tools and dashboards
• Mobile app backend
• Lightweight realtime applications
• Projects that need S3-compatible backups without an external storage provider
• Railway deployments that need app, storage, console, and backup automation in one template

Why Deploy PocketBase with MinIO Backups on Railway?

By deploying this template on Railway, you get PocketBase, Litestream, and MinIO in one project without needing a separate external object storage provider.

This setup gives you:

• One-click PocketBase deployment
• Persistent PocketBase data
• Litestream database replication
• Self-hosted MinIO backup storage
• Automatic backup bucket creation
• MinIO Console for visibility
• Private internal connection between PocketBase and MinIO
• Public PocketBase URL
• Public MinIO Console URL

This template is useful when you want PocketBase running quickly with backups stored in MinIO inside the same Railway project.

References

• PocketBase Documentation: https://pocketbase.io/docs/
• PocketBase Releases: https://github.com/pocketbase/pocketbase/releases
• Litestream Documentation: https://litestream.io/
• MinIO Documentation: https://min.io/docs/
• Railway Documentation: https://docs.railway.com/