Instalación de PocketBase Backend Ligero

PocketBase es un backend completo en un único binario que incluye base de datos SQLite, autenticación de usuarios, API REST y en tiempo real, y panel de administración, todo sin dependencias externas. Con menos de 30 MB de tamaño y capaz de manejar miles de peticiones por segundo en un VPS básico, PocketBase es la opción más eficiente para backends de aplicaciones pequeñas y medianas. Esta guía cubre la instalación, configuración de colecciones y estrategias de backup en Linux.

Requisitos Previos

Linux (Ubuntu, Debian, CentOS o cualquier distribución)
Acceso con permisos de usuario o root
256 MB RAM mínimo (PocketBase es extremadamente eficiente)
Nginx o Caddy para producción (proxy inverso con SSL)

Instalación del Binario

PocketBase se distribuye como un único ejecutable sin dependencias:

# Crear directorio de instalación
mkdir -p /opt/pocketbase
cd /opt/pocketbase

# Descargar la última versión (verificar la versión actual en GitHub)
POCKETBASE_VERSION="0.22.12"
curl -LO "https://github.com/pocketbase/pocketbase/releases/download/v${POCKETBASE_VERSION}/pocketbase_${POCKETBASE_VERSION}_linux_amd64.zip"

# Descomprimir
unzip pocketbase_${POCKETBASE_VERSION}_linux_amd64.zip

# Dar permisos de ejecución
chmod +x pocketbase

# Verificar la versión
./pocketbase --version

# Limpiar el archivo comprimido
rm pocketbase_*.zip

Primer inicio

# Iniciar PocketBase (escucha en 0.0.0.0:8090 por defecto)
./pocketbase serve

# El panel de administración está en:
# http://IP_SERVIDOR:8090/_/
# La primera vez te pedirá crear una cuenta de admin

# Iniciar en un puerto diferente
./pocketbase serve --http="0.0.0.0:8080"

# Iniciar con directorio de datos personalizado
./pocketbase serve --dir=/var/lib/pocketbase/data

# Modo debug (verbose)
./pocketbase serve --debug

Configuración como Servicio

Para producción, configura PocketBase como servicio systemd:

# Crear usuario dedicado para PocketBase
useradd --system --no-create-home --shell /bin/false pocketbase

# Crear directorio de datos y darle permisos
mkdir -p /var/lib/pocketbase/data
chown -R pocketbase:pocketbase /var/lib/pocketbase

# Mover el binario a /usr/local/bin
cp /opt/pocketbase/pocketbase /usr/local/bin/
chown pocketbase:pocketbase /usr/local/bin/pocketbase

# Crear el servicio systemd
cat > /etc/systemd/system/pocketbase.service << 'EOF'
[Unit]
Description=PocketBase Backend
After=network.target

[Service]
Type=simple
User=pocketbase
Group=pocketbase
ExecStart=/usr/local/bin/pocketbase serve \
    --http="127.0.0.1:8090" \
    --dir="/var/lib/pocketbase/data"
Restart=on-failure
RestartSec=5s

# Seguridad adicional
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/pocketbase

[Install]
WantedBy=multi-user.target
EOF

# Habilitar e iniciar el servicio
systemctl daemon-reload
systemctl enable pocketbase
systemctl start pocketbase

# Verificar el estado
systemctl status pocketbase

Proxy inverso con Nginx y SSL

# Instalar Nginx y Certbot
apt-get install -y nginx certbot python3-certbot-nginx

# Configurar el virtualhost de Nginx
cat > /etc/nginx/sites-available/pocketbase << 'EOF'
server {
    listen 80;
    server_name api.tudominio.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.tudominio.com;

    ssl_certificate /etc/letsencrypt/live/api.tudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.tudominio.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8090;
        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;
        
        # Necesario para SSE y WebSockets (tiempo real)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
    }
}
EOF

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

# Obtener certificado SSL
certbot --nginx -d api.tudominio.com

Modelo de Datos y Colecciones

PocketBase usa colecciones en lugar de tablas. Cada colección tiene un esquema definido visualmente en el panel de administración o mediante la API:

Crear colecciones desde el panel

Accede a https://api.tudominio.com/_/ y ve a Collections > New Collection:

Base Collection: colección normal con CRUD completo
Auth Collection: colección con sistema de autenticación integrado
View Collection: vista (query SQL predefinida, solo lectura)

Crear colecciones con la API

# Autenticarse como admin
curl -s -X POST https://api.tudominio.com/api/admins/auth-with-password \
    -H "Content-Type: application/json" \
    -d '{"identity":"[email protected]","password":"tuPasswordAdmin"}' \
    | jq -r '.token' > admin_token.txt

ADMIN_TOKEN=$(cat admin_token.txt)

# Crear una colección "articulos"
curl -X POST https://api.tudominio.com/api/collections \
    -H "Authorization: $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "articulos",
        "type": "base",
        "schema": [
            {
                "name": "titulo",
                "type": "text",
                "required": true,
                "options": {"min": 1, "max": 255}
            },
            {
                "name": "contenido",
                "type": "editor",
                "required": false
            },
            {
                "name": "publicado",
                "type": "bool",
                "required": false
            },
            {
                "name": "autor",
                "type": "relation",
                "options": {
                    "collectionId": "_pb_users_auth_",
                    "cascadeDelete": false
                }
            }
        ],
        "listRule": "",
        "viewRule": "",
        "createRule": "@request.auth.id != \"\"",
        "updateRule": "@request.auth.id = autor.id",
        "deleteRule": "@request.auth.id = autor.id"
    }'

Reglas de acceso

PocketBase usa un sistema de reglas declarativas para controlar el acceso:

# Ejemplos de reglas de acceso (en el panel o API)

# Cualquiera puede leer (vacío = todos)
listRule: ""

# Solo usuarios autenticados pueden leer
listRule: "@request.auth.id != \"\""

# Solo el propietario puede ver sus registros
listRule: "@request.auth.id = autor.id"

# Admin siempre puede ver todo, usuarios solo lo suyo
listRule: "@request.auth.role = 'admin' || @request.auth.id = autor.id"

# Filtros con relaciones
listRule: "categoria.nombre = 'tecnologia'"

Autenticación de Usuarios

# Crear una colección de autenticación desde el panel:
# Collections > New Collection > Auth Collection
# PocketBase crea automáticamente: registro, login, tokens, etc.

# Registrar un nuevo usuario
curl -X POST https://api.tudominio.com/api/collections/users/records \
    -H "Content-Type: application/json" \
    -d '{
        "username": "juan_perez",
        "email": "[email protected]",
        "password": "Password123!",
        "passwordConfirm": "Password123!",
        "nombre": "Juan Pérez"
    }'

# Autenticarse con email y contraseña
curl -X POST https://api.tudominio.com/api/collections/users/auth-with-password \
    -H "Content-Type: application/json" \
    -d '{"identity":"[email protected]","password":"Password123!"}' \
    | jq '.token'

# Usar el token para peticiones autenticadas
USER_TOKEN="el-token-obtenido"

curl https://api.tudominio.com/api/collections/articulos/records \
    -H "Authorization: $USER_TOKEN"

# Refrescar el token (antes de que expire)
curl -X POST https://api.tudominio.com/api/collections/users/auth-refresh \
    -H "Authorization: $USER_TOKEN"

# Actualizar el perfil del usuario
curl -X PATCH https://api.tudominio.com/api/collections/users/records/USER_ID \
    -H "Authorization: $USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"nombre": "Juan García"}'

Autenticación OAuth

# Configurar proveedores OAuth en el panel:
# Settings > Auth Providers

# Iniciar flujo OAuth desde la API
curl https://api.tudominio.com/api/collections/users/auth-methods
# Devuelve los proveedores configurados y sus URLs de inicio

# Después del flujo OAuth, completar con el código
curl -X POST https://api.tudominio.com/api/collections/users/auth-with-oauth2 \
    -H "Content-Type: application/json" \
    -d '{
        "provider": "google",
        "code": "codigo-de-google",
        "codeVerifier": "code-verifier",
        "redirectUrl": "https://miapp.com/callback"
    }'

Suscripciones en Tiempo Real

PocketBase tiene Server-Sent Events (SSE) integrados para actualizaciones en tiempo real:

// Suscribirse a cambios en una colección (JavaScript SDK)
// npm install pocketbase

import PocketBase from 'pocketbase';

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

// Suscribirse a todos los cambios en la colección 'articulos'
pb.collection('articulos').subscribe('*', function(e) {
    console.log('Acción:', e.action);  // 'create', 'update', 'delete'
    console.log('Registro:', e.record);
});

// Suscribirse a un registro específico
pb.collection('articulos').subscribe('RECORD_ID', function(e) {
    console.log('El artículo cambió:', e.record);
});

// Cancelar suscripción
pb.collection('articulos').unsubscribe('*');

# Probar SSE desde curl
curl -N https://api.tudominio.com/api/realtime \
    -H "Authorization: USER_TOKEN"

Backup y Recuperación

Backup automático

# PocketBase incluye backup integrado en el panel:
# Settings > Backups > Create backup

# También se puede hacer backup directamente del archivo SQLite
# (con PocketBase detenido o usando el snapshot de SQLite)

# Backup manual del archivo de datos
systemctl stop pocketbase
cp /var/lib/pocketbase/data/data.db /backup/pocketbase-$(date +%Y%m%d-%H%M%S).db
systemctl start pocketbase

# Backup sin detener el servicio (SQLite WAL mode - seguro en caliente)
sqlite3 /var/lib/pocketbase/data/data.db ".backup '/backup/pocketbase-$(date +%Y%m%d).db'"

Script de backup automático con rclone

# Instalar rclone para subir backups a S3/Backblaze/etc
curl https://rclone.org/install.sh | sudo bash
rclone config  # Configurar el proveedor de almacenamiento

# Script de backup periódico
cat > /usr/local/bin/pocketbase-backup.sh << 'EOF'
#!/bin/bash
# Script de backup de PocketBase

BACKUP_DIR="/var/backups/pocketbase"
DATA_DIR="/var/lib/pocketbase/data"
FECHA=$(date +%Y%m%d-%H%M%S)
BACKUP_FILE="$BACKUP_DIR/pocketbase-$FECHA.db"
RETENTION_DAYS=7

# Crear directorio si no existe
mkdir -p "$BACKUP_DIR"

# Backup seguro usando SQLite .backup
sqlite3 "$DATA_DIR/data.db" ".backup '$BACKUP_FILE'"

# Comprimir el backup
gzip "$BACKUP_FILE"

# Subir a almacenamiento remoto
rclone copy "$BACKUP_FILE.gz" remote:pocketbase-backups/

# Eliminar backups locales antiguos
find "$BACKUP_DIR" -name "*.gz" -mtime +$RETENTION_DAYS -delete

echo "Backup completado: $BACKUP_FILE.gz"
EOF

chmod +x /usr/local/bin/pocketbase-backup.sh

# Agregar al crontab (backup diario a las 3 AM)
echo "0 3 * * * root /usr/local/bin/pocketbase-backup.sh >> /var/log/pocketbase-backup.log 2>&1" > /etc/cron.d/pocketbase-backup

Restaurar desde backup

# Detener PocketBase
systemctl stop pocketbase

# Restaurar el archivo de base de datos
cp /backup/pocketbase-20240115.db /var/lib/pocketbase/data/data.db
chown pocketbase:pocketbase /var/lib/pocketbase/data/data.db

# Reiniciar PocketBase
systemctl start pocketbase

# Verificar que funciona
curl https://api.tudominio.com/api/health

Solución de Problemas

PocketBase no arranca

# Ver logs del servicio
journalctl -u pocketbase -n 50

# Verificar permisos del directorio de datos
ls -la /var/lib/pocketbase/data/
# El usuario pocketbase debe ser propietario

# Probar manualmente como el usuario del servicio
sudo -u pocketbase /usr/local/bin/pocketbase serve --dir=/var/lib/pocketbase/data

Error 400 al crear registros

# Verificar los campos requeridos y sus tipos
curl https://api.tudominio.com/api/collections/mi-coleccion/records \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"campo": "valor"}' | jq .

# El error devuelve información detallada sobre qué campos fallan
# Verificar también las reglas de creación (createRule) de la colección

SSE no recibe eventos

# Verificar la configuración de Nginx para SSE
# Debe tener proxy_read_timeout suficientemente alto
# y los headers de Upgrade/Connection para WebSocket

# Verificar que el token es válido
curl https://api.tudominio.com/api/collections/users/auth-refresh \
    -H "Authorization: TU_TOKEN" | jq '.token'

Conclusión

PocketBase destaca por ser la solución backend más eficiente en recursos: un único binario de 30 MB puede manejar miles de peticiones por segundo con menos de 100 MB de RAM en un VPS básico. Su combinación de SQLite, API REST automática, autenticación integrada y tiempo real lo hace perfecto para aplicaciones móviles, MVPs y proyectos con presupuesto limitado de infraestructura. La sencillez de backup (es un único archivo SQLite) y actualización (reemplazar el binario) son ventajas adicionales frente a soluciones más complejas como Supabase o Appwrite.

Pocketbase Lightweight Backend Installation

On this page