PocketBase on AWS User Guide

Overview

This image runs PocketBase, the open source backend that bundles an embedded SQLite database with realtime subscriptions, built in user authentication, file storage and an admin dashboard into a single portable binary. It gives you a production grade REST and realtime API for your web and mobile applications without standing up a separate database server.

The PocketBase binary is installed under /opt/pocketbase and runs as a dedicated unprivileged pocketbase system account under a systemd service that starts it on boot and restarts it on failure. The application data directory pb_data, holding the embedded SQLite database, uploaded files and migrations, lives at /var/lib/pocketbase/pb_data, which is a dedicated, independently resizable EBS data volume.

PocketBase binds to the loopback interface only and is published on port 80 by an nginx reverse proxy. PocketBase provides its own authentication: the admin dashboard at /_/ is gated by a superuser login, and your own user collections each have their own auth. The superuser password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/pocketbase-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the dashboard and the API
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for PocketBase. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the dashboard and the API. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg PocketBase Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=pocketbase}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Superuser Password

The dashboard superuser password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/pocketbase-credentials.txt

The file lists the dashboard URL, the superuser email (admin@cloudimg.local) and the generated password, along with the API endpoints. Keep this password somewhere safe.

Step 5: Sign In to the Admin Dashboard

The PocketBase admin dashboard is served on port 80 by nginx at the /_/ path. In a browser, go to:

http://<instance-public-ip>/_/

Sign in with the superuser email admin@cloudimg.local and the password from the credentials file. The dashboard opens on the Collections view, where the built in users collection and any collections you create are listed.

Select a record to open the record editor, where you can view and edit field values, including rich text content, files and relations.

Open Settings to configure the application name and URL, mail settings, file storage, scheduled backups and authentication providers for the single file backend.

Step 6: Confirm PocketBase Is Running

Over SSH, confirm the backend and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active pocketbase nginx

sudo ss -tlnp | grep -E ':(80|8090) '

You should see both services reported as active, PocketBase listening on 127.0.0.1:8090 (loopback only), and nginx listening on port 80.

Check the health endpoint through the proxy, which returns HTTP 200 with a small JSON body and needs no authentication:

curl -fsS http://127.0.0.1/api/health

Step 7: Create a Collection

A collection is a database table with a schema, automatic REST endpoints and a rules based authorization layer. Create collections from the dashboard with New collection: give it a name, add fields (text, number, bool, select, relation, file, editor and more), and set the API rules that control who can list, view, create, update and delete records. As soon as you save, PocketBase exposes the collection at /api/collections/<name>/records.

You can also manage collections from the dashboard Import collections and Export collections screens, which round trip the full schema as JSON so you can version control it and promote it between environments.

Step 8: Consume the REST and Realtime API

The REST and realtime API is served on the same port 80. The health endpoint is open; everything else is governed by the collection API rules and authentication.

Authenticate as the superuser to obtain a token for administrative API calls. From your workstation, POST the superuser email and password as JSON:

curl -X POST http://<instance-public-ip>/api/collections/_superusers/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@cloudimg.local","password":"<your-password>"}'

The response contains a token. Pass it in an Authorization header on subsequent requests, for example to list collections or read records. For application end users, create a users style auth collection and authenticate against /api/collections/users/auth-with-password (or one of the configured OAuth2 providers) to obtain a per user token.

PocketBase also exposes a realtime API over Server Sent Events at /api/realtime; clients subscribe to a collection or record and receive create, update and delete events as they happen. The bundled nginx proxy is configured with buffering disabled and a long read timeout so the realtime stream works through port 80.

Step 9: The Data Volume

The pb_data directory lives on a dedicated EBS volume mounted at /var/lib/pocketbase. This keeps the SQLite database and uploaded files off the operating system disk and lets you resize or snapshot them independently. Confirm the mount with:

df -h /var/lib/pocketbase

To grow the data store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. The entire backend state, the database, files and migrations, lives under this mount.

Step 10: Enable HTTPS

The dashboard and API are served over plain HTTP on port 80 by nginx. For production use, place them behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:8090 exactly as the bundled site does for port 80. Restrict the security group so ports 80 and 443 are reachable only from the networks that use the backend.

PocketBase can also terminate TLS itself when run with a public domain, but the bundled deployment fronts it with nginx so you can manage certificates and routing in one place.

Step 11: Backup and Maintenance

PocketBase has a built in backups feature under Settings → Backups in the dashboard, which produces a downloadable archive of pb_data and can run on a schedule. You can additionally back up the whole backend by snapshotting the /var/lib/pocketbase EBS volume. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; PocketBase and nginx start automatically on boot.

To upgrade PocketBase, replace the binary at /opt/pocketbase/pocketbase with a newer release and restart the service with sudo systemctl restart pocketbase; PocketBase applies any pending database migrations automatically on start.

Support

This image is published and supported by cloudimg. Support covers deployment, collection and schema design, authentication and OAuth2 setup, API rules, file storage, realtime subscriptions, backups, TLS and tuning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.