Deploy and Host PocketBase Custom S3 Backups on Railway

PocketBase is a lightweight, open-source backend packed into a single Go binary. It includes a realtime database, built-in authentication, file storage, access rules, and an elegant admin UI. It exposes REST and realtime APIs, supports schema migrations and JavaScript hooks, and is suitable for shipping MVPs, internal tools, and small-to-medium applications quickly.

This Railway template deploys PocketBase with persistent storage and optional Litestream backups to your own S3-compatible bucket. You can deploy it in one click, run PocketBase immediately, and add your S3-compatible backup configuration before or after deployment.

About This Template

This template includes:

PocketBase running as the main backend service
Persistent storage for PocketBase data
Optional Litestream replication for S3-compatible backups
Support for existing S3-compatible buckets
One-click deployment through Railway Template

The goal is simple: deploy PocketBase quickly, while giving you the option to back up the PocketBase database to your own object storage.

About Hosting PocketBase

Hosting PocketBase is simple: run the single binary in a container, expose the HTTP port, and persist the data directory.

This template is designed to:

Run PocketBase inside a container
Honor Railway’s provided PORT
Store PocketBase data in persistent storage
Optionally use Litestream to back up the PocketBase database to S3-compatible storage
Start PocketBase even when S3 backup variables are not configured yet

After the first successful deploy, open your Railway-generated domain and visit:

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

Use this page to create your PocketBase superuser account.

If you see a login screen instead of the registration page, check the Railway deployment logs. PocketBase may print a one-time installer or setup link during first initialization.

One-Click Deploy

This template is intended for one-click deployment.

You can deploy it in two ways:

Option 1: Deploy first, configure S3 later

Click Deploy on Railway
Leave the S3 backup variables empty
Deploy the template
Open the PocketBase dashboard at /_/
Create your superuser account
Add your S3-compatible variables later
Redeploy the PocketBase service to enable Litestream backups

Option 2: Configure S3 before deploy

Click Deploy on Railway
Fill in your S3-compatible bucket variables
Deploy the template
Open the PocketBase dashboard at /_/
Create your superuser account

If the S3 variables are incomplete, Litestream will be skipped and PocketBase will continue running normally.

Custom S3 Backups

This template is designed for users who already have their own S3-compatible bucket.

You can use providers such as:

AWS S3
Cloudflare R2
Backblaze B2
Wasabi
DigitalOcean Spaces
Vultr Object Storage
Linode Object Storage
External MinIO
Any S3-compatible object storage provider

Litestream will only start when the required S3 variables are configured.

Required variables for backups:

LITESTREAM_BUCKET
LITESTREAM_ENDPOINT
LITESTREAM_ACCESS_KEY_ID
LITESTREAM_SECRET_ACCESS_KEY

Optional but commonly used:

LITESTREAM_REGION
LITESTREAM_FORCE_PATH_STYLE

Litestream Backups

Litestream is used to continuously replicate the PocketBase database to S3-compatible object storage.

In this template, Litestream runs alongside PocketBase. Once the required S3 variables are available, Litestream starts automatically and sends database replicas to your configured bucket.

If the S3 configuration is incomplete, you may see a log like this:

Litestream skipped: S3 configuration is incomplete.
Required: LITESTREAM_BUCKET, LITESTREAM_ENDPOINT, LITESTREAM_ACCESS_KEY_ID, LITESTREAM_SECRET_ACCESS_KEY

This is expected behavior.

PocketBase will still start and run normally.

Common Use Cases

Rapid CRUD and MVP backends
Backend for mobile apps or SPAs
Internal tools and dashboards
Small SaaS products
Admin panels with authentication and file uploads
Lightweight realtime applications
Projects that already have an existing S3-compatible bucket
Projects that need deploy-first, configure-backup-later flexibility

Dependencies for PocketBase Hosting

Deployment Dependencies

This template uses:

PocketBase
Litestream
Persistent storage
S3-compatible object storage
Container runtime

Railway provides the runtime environment. Your S3-compatible bucket can be configured before deployment or added later through Railway Variables.

Environment Variables

Railway automatically provides the application port:

PORT

This template may also use variables for PocketBase data and Litestream backup configuration:

DATA_DIR
PB_VERSION
PB_SHA256
LITESTREAM_ENABLED
LITESTREAM_DB_PATH
LITESTREAM_REPLICA_PATH
LITESTREAM_FORCE_PATH_STYLE
LITESTREAM_RESTORE_ON_START
LITESTREAM_BUCKET
LITESTREAM_REGION
LITESTREAM_ENDPOINT
LITESTREAM_ACCESS_KEY_ID
LITESTREAM_SECRET_ACCESS_KEY

Recommended default variables:

PORT="8080"
DATA_DIR="/data"
PB_SHA256=""
PB_VERSION="0.39.4"
LITESTREAM_DB_PATH="/data/data.db"
LITESTREAM_ENABLED="true"
LITESTREAM_REPLICA_PATH="pocketbase/data.db"
LITESTREAM_FORCE_PATH_STYLE="true"
LITESTREAM_RESTORE_ON_START="false"
LITESTREAM_BUCKET=""
LITESTREAM_REGION=""
LITESTREAM_ENDPOINT=""
LITESTREAM_ACCESS_KEY_ID=""
LITESTREAM_SECRET_ACCESS_KEY=""

S3 Variable Notes

For custom S3-compatible backups, fill in these variables:

LITESTREAM_BUCKET="your-bucket-name"
LITESTREAM_REGION="your-bucket-region"
LITESTREAM_ENDPOINT="https://your-s3-endpoint"
LITESTREAM_ACCESS_KEY_ID="your-access-key-id"
LITESTREAM_SECRET_ACCESS_KEY="your-secret-access-key"

Example for a generic S3-compatible provider:

LITESTREAM_BUCKET="my-pocketbase-backups"
LITESTREAM_REGION="us-east-1"
LITESTREAM_ENDPOINT="https://s3.example.com"
LITESTREAM_ACCESS_KEY_ID="your-access-key-id"
LITESTREAM_SECRET_ACCESS_KEY="your-secret-access-key"
LITESTREAM_FORCE_PATH_STYLE="true"

Some providers require LITESTREAM_FORCE_PATH_STYLE=true. If backups fail with endpoint or bucket resolution errors, keep this value enabled.

Restore Behavior

Restore is disabled by default:

LITESTREAM_RESTORE_ON_START="false"

Only set this to true when restoring into a fresh or empty volume.

LITESTREAM_RESTORE_ON_START="true"

The entrypoint is designed to skip restore if the database already exists locally. This prevents accidental overwrite during normal redeployments.

Persistent Storage

PocketBase stores its application data, uploaded files, collections, users, and configuration in its data directory.

This template is designed to use persistent storage so your PocketBase data survives restarts and redeployments.

Attach a Railway volume at:

/data

Do not rely on container filesystem storage for production data. Container filesystems are ephemeral and may be lost when the service is rebuilt or redeployed.

First-Time Setup

After deployment:

Open your generated Railway domain
Go to:

/_/

Create the PocketBase superuser
Log in to the PocketBase dashboard
Start creating collections, users, APIs, and rules

Example:

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

Admin Dashboard

PocketBase includes a built-in admin dashboard.

You can access it from:

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

From the dashboard, you can manage:

Collections
Records
Users
Authentication settings
API rules
File uploads
Application settings

API Access

PocketBase exposes REST and realtime APIs automatically.

REST API:

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

Admin dashboard:

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

Health check:

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

Register UI

If the registration page does not appear immediately, check your Railway service logs.

PocketBase may provide a setup or installer link during the first startup.

logs

Useful References

PocketBase Documentation: https://pocketbase.io/docs/
PocketBase Releases: https://github.com/pocketbase/pocketbase/releases
PocketBase CLI Reference: https://pocketbase.io/docs/cli/
Litestream Documentation: https://litestream.io/
Railway Documentation: https://docs.railway.com/

Why Deploy PocketBase on Railway?

Railway is a platform for deploying infrastructure and application services with minimal configuration.

By deploying PocketBase on Railway, you get:

Fast one-click deployment
Managed deployment environment
Persistent storage support
Public service URL
Easy redeployments
Simple scaling path for small-to-medium projects
Optional S3-compatible backup configuration

This template is useful when you want PocketBase running quickly, but also want the flexibility to use your own existing S3-compatible bucket for backups.