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 (central dashboard + agents for execution) that you can deploy on your own infrastructure.

Prerequisites

Linux server/VPS with Docker and Docker Compose (Compose v3.8+).
Enough resources: ≥2 GB RAM, ≥10 GB disk (server + metadata + backups).
Access to the database instances you intend to back up (PostgreSQL, MySQL/MariaDB, MongoDB and more comming soon).

Deploy the Portabase Dashboard (Server)

Option A — CLI Quick Install (preferred)

1) Install the Portabase CLI:

curl -sL portabase.io/install | bash

2) Create and start the dashboard:

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

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

First registered user becomes admin.

Option B — Manual Docker Compose (production)

1) Create directory and compose file:

# ~/portabase/docker-compose.yml
name: portabase
services:
  portabase:
    image: portabase/portabase:latest
    env_file: .env
    ports:
      - "8887:80"
    volumes:
      - portabase-private:/app/private
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: postgres:17-alpine
    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"]
    restart: unless-stopped
volumes:
  postgres-data:
  portabase-private:

2) Create .env in same folder:

NODE_ENV=production
DATABASE_URL=postgresql://portabase_user:strong_password@db:5432/portabase?schema=public
PROJECT_NAME="Portabase Instance"
PROJECT_URL=http://<server-ip>:8887
PROJECT_SECRET=<strong-random-hex>

3) Launch stack:

docker compose up -d

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

Deploy Portabase Agent(s)

Agents run near databases to execute backups/restore. You can install one per host or environment.

Agent via Docker Compose

1) In a separate directory (~/portabase-agent):

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
            # If you prefer using .toml files, please check configuration section
            # DATABASES_CONFIG_FILE: "config.toml"
            EDGE_KEY: "${EDGE_KEY}"
        networks:
            - portabase

networks:
    portabase:
        name: portabase_network
        external: true

Note: Create the portabase_network manually if it does not exist: docker network create portabase_network.

2) Create databases.json listing DB endpoints:

{
  "databases": [
    {
      "name": "prod-postgres",
      "type": "postgresql",
      "host": "db1.internal",
      "port": 5432,
      "username": "backup_user",
      "password": "secure",
      "database": "mydb",
      "genrated_id": "uuid1"
    }
  ]
}

(Add one block per database.)

More information on that link : https://portabase.io/docs/agent/configuration

Supported Databases :

Database	Type Key	Support	Tested Versions
PostgreSQL	`postgresql`	✅ Stable	12, 13, 14, 15, 16, 17 and 18
MySQL	`mysql`	✅ Stable	5.7, 8 and 9
MariaDB	`mysql`	✅ Stable	10 and 11
MongoDB	`mongodb`	✅ Stable	4, 5, 6, 7 and 8

3) Start the agent:

docker compose up -d

4) In the dashboard UI → Agents → Add Agent, paste the EDGE_KEY from server and register.

Configure Backup Policies

Once dashboard + agents are connected:

Create Workspace/Project.
Register each agent and database.
Define backup schedules (cron syntax) and retention rules.
Choose storages backends (local folder, S3/MinIO or Google Drive).
Trigger a test backup; monitor status in UI.

Advanced & Production Considerations

Secure reverse proxy (Traefik/Nginx) for public access. More details
Set up alerts with multiple providers like SMTP, Slack, Discord, ntfy, and more.
Verify volumes and backups retention policy fits your compliance needs.

Summary

Self‑hosting Portabase is a Docker‑native deployment with:

Central dashboard + PostgreSQL .
Agents that execute backups and restorations near database hosts.
Support for PostgreSQL, MySQL/MariaDB, MongoDB.
Flexible storage (local, S3 and Google Drive for now) and scheduling.

Deployment patterns vary with scale and security needs; start with CLI for quick proof‑of‑concept, then standardize with Docker Compose or Kubernetes for production.

Github Portabase
Github Portabase Agent

Website
Documention

DEV Community: Charles Gauthereau