Deploy PocketBase
A backend in one binary, with an admin panel, running on the free plan.
PocketBase is a database, user accounts, file uploads, a REST API, and an admin panel, all in one binary. This template runs the maintained upstream build on Dockhold and adds a start script that wires it to Dockhold's port, App storage, and your admin account. Deploy it as it is, or use it as the starting point for your own backend.
1. Open the deploy link
Start from thepocketbase-starter template. Open thedeploy linkand sign in if asked.
2. Size the app and turn on App storage
Under App size, keep 256 MB. UnderApp storage, turn it on and pick 10 GB. The free plan covers both. PocketBase keeps its database and uploads on that storage, so without it the next restart would start empty.
3. Add your admin secrets
Under Environment, in the Secrets list, click New secret twice to store the email and password PocketBase will use for its first admin account, tick each one, and set its Env var name to the name PocketBase expects. Give the entries names that belong to this app, for examplepocketbase-admin-email and pocketbase-admin-password, because secrets are shared across your apps by name and two PocketBase apps that share an entry would share a password.
| Secret (your name) | Env var name | Value |
|---|---|---|
pocketbase-admin-email | PB_ADMIN_EMAIL | The email you will sign in with |
pocketbase-admin-password | PB_ADMIN_PASSWORD | 8 to 71 characters |
4. Deploy and sign in
Click Deploy and wait until the app shows as running. Open https://<your app>/_/ and sign in with that email and password.
The start script creates that admin account from the two secrets before PocketBase starts listening, so there is never a moment when someone else could reach the app first and claim the setup page for themselves.
If the app refuses to start, its page shows one line saying what is missing. App storage is on the app's Size tab; secrets are attached on its Variables tab. Fix it and click Restart.
Two ways to use it
Run PocketBase. Deploy the repository as it is. You get a hosted PocketBase with an admin panel, and you build your schema in that panel. The app stays on the version it was built with; a Restart does not pull new code. To pick up a starter update, switch to the second path.
Develop your backend. Click Use this templateon GitHub to make your own copy, connect that repository in Dockhold, and deploy it. From then on every push redeploys the app. Put server-side logic in pb_hooks/, schema changes in pb_migrations/, and a static frontend in pb_public/.
Only the second path gives you push-to-deploy. The first path never reads your GitHub account.
Try it
Open https://<your app>/api/collections/notes/records in a private browser window. It returns one record, from a public read-onlynotes collection the template's migration creates: anyone can read it, only superusers can change it. Now add a record in the admin panel and refresh the private window.
Your admin account
The start script re-saves your admin account from the two secrets on every start. The values stored in Dockhold are always the ones that work. To change one, edit the secret under Settings, then Secrets, then restart the app.
| What you do | What happens |
|---|---|
| Change the password in Dockhold, then Restart | The new password works. |
| Change the password inside PocketBase | It works until the next restart, then the Dockhold value is back. Change it in Dockhold instead. |
| Change the admin email, then Restart | A second superuser is created. The old one stays until you remove it in Settings, then Admins. |
| Delete the managed admin inside PocketBase | It is recreated on the next restart. |
| Create other superusers inside PocketBase | They are never touched. |
A Restart signs the admin out, because re-saving the account ends its existing sessions. Sign in again after every restart. Sessions of other superusers, and of your app's users, are not affected.
Backups and upgrading
Your backup set is the data on App storage plus the two secrets. Take one from Settings, then Backups, in the admin panel, before you upgrade and on a schedule. Upgrades happen on the Develop path: take a backup, change the pinned version and its checksum in the Dockerfile of your copy (or merge the template's main into it), and push. If a deploy rolls back because the new version doesn't come up healthy, restore the backup before you retry: an old version reading data a newer version already touched isn't safe.
Troubleshooting
- App refuses to start, asks for App storage: PocketBase keeps its database in a file and needs somewhere durable to put it. Turn on App storage on the app's Size tab; the app restarts on its own.
- App refuses to start, names a missing secret:
PB_ADMIN_EMAILorPB_ADMIN_PASSWORDisn't set. Add both as secrets on the app's Variables tab and restart. - App refuses to start over a rejected value: the email isn't a valid address, or the password is under 8 or over 71 characters. Fix the secret's value and restart; your previous login keeps working until then.