Héberger PocketBase sur un VPS : guide complet

PocketBase est un backend-as-a-service open source distribué sous forme d'un seul binaire : pas de Postgres séparé, pas de Redis, pas de pile complexe à orchestrer. Tout repose sur SQLite, ce qui le rend parfaitement adapté à un VPS d'entrée de gamme.

En l'auto-hébergeant, vous gardez la maîtrise totale de vos données utilisateurs et de vos fichiers, sans dépendre d'un Firebase ou d'un Supabase managé dont les quotas et la latence peuvent poser problème selon votre région. Un VPS vous donne une IP fixe, un domaine personnalisé et des sauvegardes que vous contrôlez entièrement.

Comme PocketBase écrit dans un dossier pb_data unique, la stratégie de backup se résume à copier ce répertoire, ce qui simplifie énormément l'exploitation par rapport à un cluster de base de données classique. Vous pouvez migrer votre backend en déplaçant un seul dossier.

PocketBase est extrêmement frugal. Voici ce dont vous avez besoin selon votre charge :

Minimum absolu : 1 vCPU, 512 Mo de RAM. Suffisant pour un projet en développement ou une petite application avec moins de 1 000 utilisateurs actifs.

Recommandé en production : 1 vCPU, 1 Go de RAM. PocketBase gère sans difficulté un projet de taille modeste à moyenne avec cette configuration ; le cache SQLite et les pics de trafic temps réel sont absorbés confortablement.

Pour des volumes élevés : 2 vCPU, 2 Go de RAM. La limite de PocketBase est généralement l'écriture concurrente sur SQLite, pas le CPU.

Côté stockage, prévoyez 20 à 40 Go SSD NVMe selon le volume de fichiers uploadés par vos utilisateurs. SQLite étant mono-fichier, un disque NVMe améliore sensiblement les performances en écriture concurrente — évitez les disques réseau (NFS, CIFS) qui peuvent corrompre la base en cas de verrous mal gérés.

Logiciels requis : Docker 24+ et Docker Compose v2 (ou le binaire PocketBase seul avec systemd), un nom de domaine ou sous-domaine pointant vers l'IP du VPS via un enregistrement A, un reverse proxy (Caddy, Nginx ou Traefik) pour gérer le TLS.

PocketBase supporte nativement OAuth2 avec plusieurs fournisseurs : Google, GitHub, GitLab, Discord, Twitter/X, Microsoft, Apple et d'autres. La configuration se fait entièrement depuis l'interface d'admin, sans toucher au code.

Pour Google OAuth :
1. Ouvrez la Google Cloud Console, créez un projet et activez l'API « OAuth consent screen ».
2. Dans « Credentials », créez un « OAuth 2.0 Client ID » de type « Web application ».
3. Ajoutez https://app.your-domain.com/api/oauth2-redirect comme URI de redirection autorisée.
4. Copiez le Client ID et le Client secret.
5. Dans PocketBase /_/, allez dans Settings → Auth providers → Google, activez-le et collez vos identifiants.

Pour GitHub OAuth :
1. Sur GitHub, allez dans Settings → Developer settings → OAuth Apps → New OAuth App.
2. Renseignez https://app.your-domain.com comme Homepage URL et https://app.your-domain.com/api/oauth2-redirect comme Authorization callback URL.
3. Copiez le Client ID et générez un Client Secret.
4. Activez GitHub dans Settings → Auth providers de PocketBase.

Chaque fournisseur actif apparaîtra automatiquement sur la page de connexion générée par PocketBase. Votre frontend n'a qu'à appeler pb.collection('users').authWithOAuth2({ provider: 'google' }) via le SDK JavaScript.

PocketBase stocke tout dans le dossier pb_data : la base SQLite (pb_data/data.db), les fichiers uploadés (pb_data/storage/) et les logs. Une sauvegarde complète se résume à archiver ce dossier.

Méthode 1 — cron simple : ajoutez cette ligne à votre crontab (crontab -e) pour une archive quotidienne à 3h du matin :

0 3 * * * tar czf /var/backups/pocketbase-$(date +\%F).tar.gz /opt/pocketbase/pb_data && find /var/backups -name 'pocketbase-*.tar.gz' -mtime +7 -delete

Cette commande crée une archive datée et supprime les sauvegardes de plus de 7 jours.

Méthode 2 — backups intégrés PocketBase : depuis l'interface /_/, allez dans Settings → Backups. PocketBase peut créer des archives de pb_data directement depuis l'admin ou via l'API (POST /api/backups). Vous pouvez télécharger ces archives ou les envoyer vers un stockage S3 compatible.

Méthode 3 — rclone vers S3 : pour une copie hors-site automatique, utilisez rclone :

0 4 * * * rclone sync /opt/pocketbase/pb_data your-remote:pocketbase-backup/

your-remote est un profil rclone configuré vers Backblaze B2, AWS S3 ou tout stockage objet compatible. Conservez toujours une copie hors du serveur — si le disque tombe, le seul backup local ne sert à rien.

Port déjà utilisé : si docker compose up échoue avec bind: address already in use sur le port 80 ou 443, vérifiez avec ss -tlnp | grep ':80' quel service occupe le port. Un nginx ou Apache installé sur l'hôte entre en conflit avec Caddy. Arrêtez-le (systemctl stop nginx) ou changez ses ports.

Permissions sur pb_data : PocketBase tourne avec l'utilisateur nobody (UID 65534) dans le conteneur officiel. Si vous montez un dossier créé par root, le processus ne peut pas écrire. Corrigez avec chown -R 65534:65534 /opt/pocketbase/pb_data.

/_/ inaccessible après démarrage : vérifiez que le reverse proxy pointe bien vers le nom de service Docker (pocketbase:8090) et non localhost:8090. Dans un réseau Docker Compose, les services se joignent par leur nom, pas par localhost.

Mettre à jour PocketBase : changez le tag de l'image dans docker-compose.yml (ex. ghcr.io/muchobien/pocketbase:0.23) puis docker compose pull && docker compose up -d. PocketBase effectue les migrations de schéma automatiquement au démarrage. Sauvegardez pb_data avant toute mise à jour majeure.

Certificat Let's Encrypt non obtenu : Caddy a besoin que les ports 80 et 443 soient accessibles depuis Internet pour le challenge HTTP-01. Vérifiez votre pare-feu (ufw status) et les règles de groupe de sécurité de votre hébergeur.

CLI d'administration : PocketBase expose une CLI pour les opérations courantes sans passer par l'interface web. Depuis le conteneur : docker exec -it pocketbase_pocketbase_1 /pb/pocketbase --help. Vous pouvez créer un super-admin en ligne de commande, exécuter des migrations ou vérifier la santé de la base.

Collections personnalisées : dans /_/, créez vos collections (équivalentes aux tables) en définissant les champs typés (text, number, bool, date, file, relation, select, JSON). Les règles d'API s'expriment en syntaxe PocketBase (@request.auth.id != "" pour restreindre aux utilisateurs connectés, @request.auth.id = id pour limiter à son propre enregistrement).

Hooks (JavaScript côté serveur) : depuis PocketBase v0.17, vous pouvez étendre le backend avec des scripts JavaScript exécutés côté serveur (pb_hooks/*.pb.js). Exemples d'usage : envoyer un email à la création d'un utilisateur, valider des données complexes avant insertion, déclencher un webhook vers Slack. Ces hooks sont des fichiers montés dans le conteneur :

volumes:
  - ./pb_data:/pb_data
  - ./pb_hooks:/pb_hooks

SDK JavaScript : le SDK officiel (npm install pocketbase) simplifie les appels depuis votre frontend React, Vue ou mobile. Il gère l'authentification, le refresh de token et les abonnements temps réel (pb.collection('tasks').subscribe('*', callback)).