How to self-host Portabase

Charles Gauthereau — Tue, 27 Jan 2026 16:31:38 +0000

Portabase is an open-source, self-hosted database backup & restore platform: a central dashboard plus lightweight Rust agents that execute backups next to your databases. The control plane never dials into your environments; agents poll outbound, so there are no inbound ports to open. Backups are encrypted with AES-GCM, and the project is Apache-2.0.

Prerequisites

Linux server/VPS with Docker and Docker Compose.
Enough resources: ≥ 2 GB RAM, ≥ 10 GB disk (server + metadata + backups).
Access to the database instances you intend to back up. Supported engines (all stable): PostgreSQL, MySQL, MariaDB, MongoDB, SQLite, Redis, Valkey, Firebird, MSSQL.

Deploy the Portabase Dashboard (Server)

Option A: CLI Quick Install (preferred)

1) Install the Portabase CLI:

curl -sL https://portabase.io/install | bash

2) Create and start the dashboard (the CLI generates PROJECT_SECRET and wires up the internal database):

portabase dashboard my-instance --port 8887 --start

3) Access the UI: http://<server-ip>:8887

First registered user becomes admin.

Option B: Manual Docker Compose (production)

1) Create a directory and a compose file:

# ~/portabase/docker-compose.yml
name: portabase

services:
  app:
    container_name: portabase-app-prod
    image: portabase/portabase:latest
    restart: unless-stopped
    env_file: .env
    environment:
      TZ: "Europe/Paris"
    ports:
      - "8887:80"
    volumes:
      - portabase-data:/data
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

  db:
    container_name: portabase-pg
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=portabase
      - POSTGRES_USER=portabase_user
      - POSTGRES_PASSWORD=strong_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U portabase_user -d portabase"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:
  portabase-data:

2) Create .env in the same folder. Storage, notifications, and auth (OAuth2/OIDC) are configured in the dashboard UI, so the .env stays minimal:

PROJECT_URL=http://<server-ip>:8887

# Encrypts agent <-> server communication. Generate one:
#   openssl rand -hex 32
PROJECT_SECRET=<strong-random-hex>

DATABASE_URL=postgresql://portabase_user:strong_password@db:5432/portabase?schema=public

3) Launch the stack:

docker compose up -d

4) Verify the dashboard is reachable at http://<server-ip>:8887.

This PostgreSQL holds Portabase's own metadata, not your backups.

Deploy Portabase Agent(s)

Agents run near your databases to execute backups and restores. Install one per host or environment.

Agent via Docker Compose

1) Create the external network and an empty config file first (the agent needs the file present at start):

docker network create portabase_network
mkdir ~/portabase-agent && cd ~/portabase-agent
echo '{"databases": []}' > databases.json

2) In ~/portabase-agent/docker-compose.yml:

name: portabase-agent

services:
  app:
    container_name: portabase-agent
    image: portabase/agent:latest
    restart: always
    volumes:
      # Mount the DB config file
      - ./databases.json:/config/config.json
    extra_hosts:
      # Allows the agent to contact the host's 'localhost'
      - "localhost:host-gateway"
    environment:
      TZ: "Europe/Paris"
      LOG: info
      POLLING: 5
      APP_ENV: production
      DATA_PATH: "/data"
      # DATABASES_CONFIG_FILE: "config.toml"  # uncomment to use TOML
      EDGE_KEY: "${EDGE_KEY}"
    networks:
      - portabase

networks:
  portabase:
    name: portabase_network
    external: true

3) Populate databases.json with your DB endpoints. Each entry needs a real UUID v4 in generated_id (generate with uuidgen; do not invent a string). Note the mount path is /config/config.json:

{
  "databases": [
    {
      "name": "prod-postgres",
      "type": "postgresql",
      "host": "db1.internal",
      "port": 5432,
      "username": "backup_user",
      "password": "secure",
      "database": "mydb",
      "generated_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

(Add one block per database. More detail: https://portabase.io/docs/agent/configuration)

Supported databases:

Database	Type Key	Support	Tested Versions	Restore
PostgreSQL	`postgresql`	✅ Stable	12, 13, 14, 15, 16, 17 and 18	Yes
MySQL	`mysql`	✅ Stable	5.7, 8 and 9	Yes
MariaDB	`mysql`	✅ Stable	10 and 11	Yes
MongoDB	`mongodb`	✅ Stable	4, 5, 6, 7 and 8	Yes
SQLite	`sqlite`	✅ Stable	3.x	Yes
Firebird	`firebird`	✅ Stable	3.0, 4.0, 5.0	Yes
MSSQL	`mssql`	✅ Stable	n/a	Yes
Redis	`redis`	✅ Stable	2.8+	No
Valkey	`valkey`	✅ Stable	7.2+	No

(Use the mysql type key for MariaDB.)

4) Get an Edge Key from the dashboard (Agents → Add Agent), set it as EDGE_KEY, then start the agent:

docker compose up -d

The agent registers and flips to online within a few poll cycles.

Configure Backup Policies

Once dashboard and agents are connected:

Create a Workspace/Project.
Register each agent and database.
Define backup schedules (cron) and a retention strategy: by count, by time, or GFS rotation.
Choose storage backends: local folder, S3-compatible (AWS S3, MinIO, RustFS), Google Drive, or Google Cloud Storage. You can target several at once for redundancy. (Azure Blob is on the roadmap.)
Trigger a test backup and monitor status in the UI.

Advanced & Production Considerations

Put a reverse proxy (Traefik/Nginx) in front for public access. Guide
Wire up alerts: Email, Slack, Discord, Telegram, Ntfy, Gotify, MS Teams, Pushover, or webhooks.
Confirm your volumes and retention policy match your compliance requirements.

Summary

Self-hosting Portabase is a Docker-native (and Kubernetes-ready) deployment:

Central dashboard backed by PostgreSQL for metadata.
Rust agents executing AES-GCM-encrypted backups and restores near the database hosts.
Nine supported engines: PostgreSQL, MySQL, MariaDB, MongoDB, SQLite, Redis, Valkey, Firebird, MSSQL.
Flexible storage (local, S3, Google Drive, Google Cloud Storage), cron scheduling, and GFS retention.

Start with the CLI for a quick proof-of-concept, then standardize on Docker Compose or Kubernetes for production.

Portabase dashboard (GitHub)
Portabase agent, Rust (GitHub)
Portabase CLI (GitHub)

Website · Documentation · Discord

DEV Community: Charles Gauthereau