PocketBase es un backend de código abierto que cabe en un único ejecutable: incluye una base de datos SQLite, una API REST, suscripciones en tiempo real, autenticación de usuarios, almacenamiento de archivos y un panel de administración. En este tutorial instalarás PocketBase en Ubuntu 24.04 como servicio systemd con un usuario dedicado, lo publicarás con Nginx y HTTPS, crearás una colección con reglas de acceso y activarás las copias de seguridad automáticas.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath. PocketBase es muy ligero: 1 vCPU y 1 GB de RAM son suficientes para empezar.
  • Un usuario no root con privilegios sudo.
  • Un subdominio con un registro A apuntando al servidor. En esta guía se usa api.tudominio.com.

Paso 1: Descargar PocketBase

Instala las herramientas que usarás durante la guía:

sudo apt update
sudo apt install unzip curl jq

Obtén el número de la última versión publicada en GitHub (sin la v inicial, que no forma parte del nombre del archivo):

PB_VERSION=$(curl -fsSL https://api.github.com/repos/pocketbase/pocketbase/releases/latest | jq -r .tag_name | sed 's/^v//')
echo "$PB_VERSION"

0.30.0

Tu versión puede ser más reciente. Descarga el binario para Linux x86_64 y el archivo de sumas de verificación. Si tu servidor es ARM, cambia amd64 por arm64:

cd /tmp
curl -fsSLO "https://github.com/pocketbase/pocketbase/releases/download/v${PB_VERSION}/pocketbase_${PB_VERSION}_linux_amd64.zip"
curl -fsSLO "https://github.com/pocketbase/pocketbase/releases/download/v${PB_VERSION}/checksums.txt"
sha256sum --ignore-missing -c checksums.txt

pocketbase_0.30.0_linux_amd64.zip: OK

Descomprime el ejecutable en /opt/pocketbase y comprueba la versión:

sudo mkdir -p /opt/pocketbase
sudo unzip -o "pocketbase_${PB_VERSION}_linux_amd64.zip" pocketbase -d /opt/pocketbase
/opt/pocketbase/pocketbase --version

pocketbase version 0.30.0

Paso 2: Crear un usuario de sistema y la cuenta de superusuario

PocketBase guarda sus datos en pb_data y las migraciones en pb_migrations, junto al ejecutable. Crea un usuario de sistema sin shell que sea propietario de ese directorio, mientras el binario sigue perteneciendo a root:

sudo useradd --system --home-dir /opt/pocketbase --shell /usr/sbin/nologin pocketbase
sudo chown pocketbase:pocketbase /opt/pocketbase
sudo chown root:root /opt/pocketbase/pocketbase

Crea la cuenta de superusuario, que da acceso al panel de administración. Sustituye el correo y usa una contraseña larga en lugar de tu_contraseña_segura:

sudo -u pocketbase /opt/pocketbase/pocketbase superuser upsert [email protected] 'tu_contraseña_segura'

La orden crea el directorio pb_data con la base de datos inicial. Compruébalo:

sudo ls /opt/pocketbase/pb_data

auxiliary.db  data.db

Paso 3: Crear el servicio systemd

PocketBase escuchará solo en 127.0.0.1:8090; Nginx será quien reciba el tráfico público. Crea la unidad de systemd:

sudo nano /etc/systemd/system/pocketbase.service

[Unit]
Description=PocketBase
After=network.target

[Service]
Type=simple
User=pocketbase
Group=pocketbase
WorkingDirectory=/opt/pocketbase
ExecStart=/opt/pocketbase/pocketbase serve --http=127.0.0.1:8090
Restart=on-failure
RestartSec=5s
LimitNOFILE=4096

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/pocketbase

[Install]
WantedBy=multi-user.target

ProtectSystem=strict deja todo el sistema de archivos en solo lectura para el servicio, excepto /opt/pocketbase. Recarga systemd y arranca el servicio:

sudo systemctl daemon-reload
sudo systemctl enable --now pocketbase
sudo systemctl status pocketbase --no-pager

● pocketbase.service - PocketBase
     Loaded: loaded (/etc/systemd/system/pocketbase.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-09-25 10:05:12 UTC; 3s ago
...

Comprueba el endpoint de salud:

curl -s http://127.0.0.1:8090/api/health

{"message":"API is healthy.","code":200,"data":{}}

Paso 4: Publicar PocketBase con Nginx y HTTPS

Instala Nginx y Certbot, y abre los puertos en UFW:

sudo apt install nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Crea el sitio de Nginx. Las suscripciones en tiempo real de PocketBase usan Server-Sent Events, conexiones HTTP largas; por eso se usa HTTP/1.1, se vacía la cabecera Connection y se amplía el tiempo de lectura:

sudo nano /etc/nginx/sites-available/pocketbase

server {
    listen 80;
    listen [::]:80;
    server_name api.tudominio.com;

    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_read_timeout 360s;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

client_max_body_size limita el tamaño de los archivos que se pueden subir; auméntalo si tus colecciones admiten archivos más grandes. Activa el sitio y recarga Nginx:

sudo ln -s /etc/nginx/sites-available/pocketbase /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Solicita el certificado. Certbot añade el bloque HTTPS y la redirección desde HTTP:

sudo certbot --nginx -d api.tudominio.com

Comprueba el acceso público:

curl -s https://api.tudominio.com/api/health

{"message":"API is healthy.","code":200,"data":{}}

El panel de administración está en https://api.tudominio.com/_/. Inicia sesión con la cuenta de superusuario del paso 2.

Paso 5: Crear una colección con reglas de acceso

En PocketBase los datos se organizan en colecciones. Cada colección tiene reglas que deciden quién puede listar, ver, crear, modificar o borrar registros: una regla vacía ("") permite el acceso a cualquiera, null lo reserva a los superusuarios y una expresión como @request.auth.id != "" exige un usuario autenticado.

Puedes crear colecciones desde el panel (New collection), pero hacerlo por la API deja el proceso documentado y reproducible. Obtén un token de superusuario:

TOKEN=$(curl -s -X POST https://api.tudominio.com/api/collections/_superusers/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"[email protected]","password":"tu_contraseña_segura"}' | jq -r .token)

Crea la colección tareas: cualquiera puede leer, solo los usuarios autenticados pueden crear y solo los superusuarios pueden modificar o borrar:

curl -s -X POST https://api.tudominio.com/api/collections \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tareas",
    "type": "base",
    "fields": [
      {"name": "titulo", "type": "text", "required": true},
      {"name": "hecha", "type": "bool"}
    ],
    "listRule": "",
    "viewRule": "",
    "createRule": "@request.auth.id != \"\"",
    "updateRule": null,
    "deleteRule": null
  }' | jq -r .name

tareas

Comprueba que un cliente anónimo puede listar la colección, aunque todavía esté vacía:

curl -s https://api.tudominio.com/api/collections/tareas/records

{"items":[],"page":1,"perPage":30,"totalItems":0,"totalPages":0}

Paso 6: Registrar un usuario y crear registros

PocketBase incluye una colección de autenticación llamada users. Registra un usuario de prueba:

curl -s -X POST https://api.tudominio.com/api/collections/users/records \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"otra_contraseña_segura","passwordConfirm":"otra_contraseña_segura"}' | jq -r .email

[email protected]

Inicia sesión con ese usuario y guarda su token:

USER_TOKEN=$(curl -s -X POST https://api.tudominio.com/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"[email protected]","password":"otra_contraseña_segura"}' | jq -r .token)

Crea una tarea con el token del usuario:

curl -s -X POST https://api.tudominio.com/api/collections/tareas/records \
  -H "Authorization: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Configurar copias de seguridad","hecha":false}' | jq -r .titulo

Configurar copias de seguridad

Si repites la misma petición sin la cabecera Authorization, PocketBase responde con un error 400, porque la regla createRule exige un usuario autenticado.

Desde una aplicación web, el SDK oficial (npm install pocketbase) permite suscribirse a los cambios en tiempo real:

import PocketBase from "pocketbase";

const pb = new PocketBase("https://api.tudominio.com");

pb.collection("tareas").subscribe("*", (e) => {
  console.log(e.action, e.record.titulo);
});

Paso 7: Programar copias de seguridad

PocketBase incluye copias de seguridad integradas que generan un ZIP con el contenido de pb_data, incluidos los archivos subidos. En el panel, ve a Settings > Backups, abre las opciones y activa las copias automáticas con una expresión cron, por ejemplo 0 3 * * * para una copia diaria a las 3:00, y el número máximo de copias que quieres conservar. Las copias se guardan en /opt/pocketbase/pb_data/backups, salvo que configures un almacenamiento S3 compatible en esa misma pantalla.

Para lanzar una copia manual por la API, usa el token de superusuario del paso 5:

curl -s -X POST https://api.tudominio.com/api/backups \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
sudo ls /opt/pocketbase/pb_data/backups

pb_backup_20260925101530.zip

Una copia que solo vive en el mismo servidor no te protege si pierdes el disco: configura el destino S3 o copia periódicamente esos ZIP a otra máquina. Para restaurar, usa el botón de restauración junto a cada copia en Settings > Backups.

Paso 8: Actualizar PocketBase

PocketBase está en versión 0.x y algunas versiones incluyen cambios incompatibles, así que lee las notas de la versión antes de actualizar. Haz una copia de seguridad, descarga la nueva versión como en el paso 1 y sustituye el ejecutable:

sudo systemctl stop pocketbase
sudo unzip -o "/tmp/pocketbase_${PB_VERSION}_linux_amd64.zip" pocketbase -d /opt/pocketbase
sudo systemctl start pocketbase
/opt/pocketbase/pocketbase --version

Al arrancar, PocketBase aplica automáticamente las migraciones pendientes de la base de datos.

Solución de problemas

El servicio no arranca. Revisa el registro de systemd:

sudo journalctl -u pocketbase -n 50 --no-pager

Si aparece permission denied o readonly database, el usuario pocketbase no es propietario de pb_data. Corrígelo con sudo chown -R pocketbase:pocketbase /opt/pocketbase/pb_data; suele pasar cuando se ejecuta alguna orden de PocketBase con sudo sin -u pocketbase.

Nginx devuelve 502 Bad Gateway. PocketBase no está escuchando en 127.0.0.1:8090. Comprueba sudo systemctl status pocketbase y curl -s http://127.0.0.1:8090/api/health.

Las suscripciones en tiempo real se cortan. Comprueba que el bloque location incluye proxy_http_version 1.1, proxy_set_header Connection '' y un proxy_read_timeout mayor que el intervalo de reconexión, y que no hay otro proxy o CDN delante que almacene en búfer las respuestas.

Conclusión

Tienes PocketBase funcionando en Ubuntu 24.04 como servicio aislado, publicado con Nginx y HTTPS, con una colección protegida por reglas de acceso y copias de seguridad programadas. Como siguientes pasos, configura el SMTP en Settings > Mail settings para verificar correos y recuperar contraseñas, activa proveedores OAuth2 en las opciones de la colección users y amplía el backend con hooks en JavaScript dentro de /opt/pocketbase/pb_hooks.