DEV Community

Cover image for How to self-host Portabase
Charles Gauthereau
Charles Gauthereau

Posted on

How to self-host Portabase

#opensource #database #programming #webdev

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
Enter fullscreen mode Exit fullscreen mode

2) Create and start the dashboard:

portabase dashboard my-instance --port 8887 --start
Enter fullscreen mode Exit fullscreen mode

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:
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

3) Launch stack:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

(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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)