How to self-host Portabase

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 :

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:

1. Create Workspace/Project.


2. Register each agent and database.


3. Define backup schedules (cron syntax) and retention rules.


4. Choose storages backends (local folder, S3/MinIO or Google Drive).


5. Trigger a test backup; monitor status in UI.

Advanced & Production Considerations

1. Secure reverse proxy (Traefik/Nginx) for public access. More details
   


2. Set up alerts with multiple providers like SMTP, Slack, Discord, ntfy, and more.


3. 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