Deploy a PocketBase backend

What this covers

A Pocketbase Backend service runs one process — the PocketBase server. It is not a place to host an application you wrote: nothing in a repository you give it is built or executed. From a repository it reads only pb_migrations/ (collection schema and API rules), pb_hooks/ (custom endpoints, scheduled jobs, mail) and public/ (static files served from the same domain). Your data lives in a pb_data/ directory held at the service level, not inside a release, so it survives redeployments and rollbacks. File storage is local to the runtime VM unless you point uploads at an S3-compatible bucket. Buying the service without a repository still gives you a working, empty PocketBase that you configure entirely through the dashboard at /_/. All three directories are read from the repository ROOT: PocketBase does not use the Subdirectory field, which belongs to the runtimes that build and run your code.

Before you start

Work out which of the two things you need. If you want a database with auth and an admin dashboard, this article is right. If you have an application you wrote and it needs a database, you need two services: this backend, and an App Hosting plan running your code on the runtime it is written in (node, python_fastapi, laravel, java or static). They are wired together with a POCKETBASE_URL environment variable — see 'Connect your app to a PocketBase backend'. Then decide whether you want a code-defined backend or a dashboard-defined one. For code-defined, push a Git repository containing pb_migrations/ and/or pb_hooks/ and paste its URL into the Artifact Reference field; private repositories also need a GitHub token with repo scope. For dashboard-defined, leave that field empty and create everything in /_/. You do not need to install Go or compile anything.

How to do it

1. Buy a Pocketbase Backend service from Portal → Catalog. This is its own service — an App Hosting plan does not provide a PocketBase backend, and the free app trial does not cover it.
2. Open Portal → Services and select your Pocketbase Backend service.
3. In the Deploy App section, leave the Artifact Reference field empty for a backend you configure in the dashboard.
4. To define your backend in code instead, paste your GitHub repository URL into Artifact Reference — it is cloned and any pb_migrations/ and pb_hooks/ it contains are loaded. For a private repository, also paste a GitHub token with repo scope.
5. Leave the build and start command fields empty. PocketBase is configured automatically and runs no build.
6. Click Redeploy App and wait up to 60 seconds.
7. Visit https://your-domain/_/ to open the admin dashboard and create your superuser account. You can also set it from the service page.
8. In the dashboard, create Collections (your tables) with the fields you need. An app that only needs sign-in can skip this — the built-in users collection is always there.
9. Set API rules on each collection. New collections are admin-only by default, so until you set a rule (for example @request.auth.id != "" for signed-in users) requests from your app are refused with 403.
10. Copy your backend URL. Your API is at https://your-domain/api/ and the admin dashboard at /_/.
11. Deploy your own application as a separate App Hosting service, and give it the backend URL as a POCKETBASE_URL environment variable. Connect with the PocketBase SDK or any HTTP client.
12. Realtime subscriptions work out of the box — WebSocket connections are proxied through nginx. Use pb.collection('name').subscribe('*', callback) in your app.

What our team checks

Support verifies that the PocketBase server is running, the admin dashboard is reachable at /_/, and nginx is proxying both HTTP requests and WebSocket connections to the service port.