Self-Hosting Portabase: A Comprehensive Guide to Effortless Database Backup and Restore

Soluce Technologies — Mon, 29 Dec 2025 13:49:02 +0000

In today's fast-paced database management landscape, reliability and control are paramount. Data loss can lead to costly downtime, and depending on third-party services often means sacrificing privacy or flexibility. That's where Portabase comes in—a free, open-source, self-hosted tool that simplifies automated backups and restores for your database instances. Powered by modern technologies like Next.js, Drizzle ORM, Better Auth, and Docker, Portabase provides an intuitive web dashboard for scheduling, monitoring, and managing backups across PostgreSQL, MySQL, MariaDB, and more.

Whether you're managing production PostgreSQL clusters or development MySQL setups, Portabase streamlines operations with minimal effort. This updated guide covers self-hosting Portabase, now with a focus on the powerful Portabase CLI —a user-friendly command-line tool that makes setup even easier by generating configurations, managing lifecycle, and handling database connections interactively.

By the end, you'll have a secure, scalable backup system. Let's get started—CLI or traditional Docker Compose, your choice!

Why Choose Self-Hosted Portabase?

Key advantages:

Security-Focused: Keep credentials on your infrastructure—no vendor lock-in.
Cost-Free: Apache-2.0 licensed, no fees.
Flexible Storage: Local files or S3-compatible (MinIO, AWS).
Scalable: Multi-database, organizations, projects with RBAC.
Database Support: PostgreSQL, MySQL, and full MariaDB support.
Notifications: Alerts via SMTP, Slack, Discord, etc.
Enhanced Organizations: Workspaces and teams for collaboration.
New: Portabase CLI: Simplified setup and management without manual file editing.

Ideal for devs needing quick restores or enterprises enforcing compliance.

Prerequisites

Docker & Docker Compose (v20+).
Server/VM: 2GB+ RAM, 10GB+ storage (Linux/macOS/Windows).
Database credentials for PostgreSQL/MySQL/MariaDB.

Option 1: Quick Setup with the Portabase CLI (Recommended)

The Portabase CLI is the easiest way to deploy and manage Portabase. It wraps Docker Compose, generates secure configs, and provides interactive assistants for adding components and databases—eliminating manual TOML/JSON editing errors.

Install the CLI

Run this:

curl -sL portabase.io/install | bash

Verify:

portabase --version

Deploy the Dashboard

Create and start the central web interface:

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

This generates the folder structure, docker-compose.yml, .env, and starts the server. Access at http://localhost:8887 and sign up (first user gets admin).

Deploy an Agent

On database hosts:

portabase agent prod-db-agent --start

The interactive assistant will:

Prompt for the Edge Key (get it from Dashboard > Agents > Add Agent).
Offer to add database connections automatically.

Manage Databases via CLI

Add a database interactively:

portabase db add prod-db-agent

(Prompts for type, host, port, credentials.)

List databases:

portabase db list prod-db-agent

Remove:

portabase db remove prod-db-agent

After changes, restart:

portabase restart prod-db-agent

Lifecycle Commands
From component folders (or use full path):

portabase start .
portabase stop .
portabase logs -f . (real-time logs)
portabase uninstall . --force (careful—deletes data!)

The CLI makes deployments faster and safer. Full reference: Portabase CLI Docs.

Option 2: Traditional Docker Compose Setup

If you prefer manual control...

Step 1: Server Setup

Create the Docker Compose File

In a new directory (e.g., ~/portabase), create docker-compose.yml:


name: portabase

services:
  portabase:
    image: solucetechnologies/portabase:latest
    env_file:
      - .env
    ports:
      - '8887:80'
    environment:
      - TZ="Europe/Paris"  # Customize to your timezone
    volumes:
      - portabase-private:/app/private
    depends_on:
      db:
        condition: service_healthy
    container_name: portabase-app
    restart: unless-stopped

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

volumes:
  postgres-data:
  portabase-private:

This configures:

The Portabase app on port 8887.
A lightweight PostgreSQL instance for internal metadata (separate from your backed-up databases).

Set Up the Environment (.env File)

Create .env in the same directory:


# Environment
NODE_ENV=production

# Database Connection
DATABASE_URL=postgresql://portabase_user:your_secure_password_here@db:5432/portabase?schema=public

# Project Details
PROJECT_NAME="My Portabase Instance"
PROJECT_DESCRIPTION="Self-hosted database backup manager"
PROJECT_URL=http://localhost:8887
PROJECT_SECRET=your_random_secret_key_here  # Generate with openssl rand -hex 32

# Notifications (SMTP for Email)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password
SMTP_FROM=alerts@yourdomain.com

# Google OAuth (Optional)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret
AUTH_GOOGLE_METHOD=true

# Storage (S3/MinIO)
S3_ENDPOINT=http://minio.yourdomain.com
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_BUCKET_NAME=portabase-backups
S3_PORT=9000
S3_USE_SSL=false

# Storage Type
STORAGE_TYPE=s3  # Or 'local' for testing

# Retention Cron
RETENTION_CRON="0 2 * * *"  # Daily at 2 AM

Notes:

PROJECT_SECRET: Critical for security—generate a strong one.
Notifications: Configure SMTP for emails
STORAGE_TYPE: Use 'local' initially, then switch to 's3' for production.
For complete env options, see the documentation.

Launch the Server

Run:

docker compose up -d

Monitor with docker compose logs -f. It should be ready in under a minute.

Access the dashboard at http://localhost:8887. Sign up as the first user to gain admin access in the default workspace.

Step 2: Agent Setup

The agent handles backups securely on hosts near your databases. Deploy it separately for each environment.

Docker Compose for the Agent

In a new directory (e.g., ~/portabase-agent), create docker-compose.yml:



name: agent-portabase

services:
  app:
    container_name: agent-portabase
    restart: always
    image: solucetechnologies/agent-portabase:latest
    volumes:
      - ./databases.json:/app/src/data/config/config.json
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "your_edge_key_from_dashboard"
    networks:
      - portabase

  # Optional Test DBs
  db:
    image: postgres:17-alpine
    networks:
      - portabase
      - default
    ports:
      - "5430:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=devdb
      - POSTGRES_USER=devuser
      - POSTGRES_PASSWORD=changeme

  db2:
    image: mariadb:latest
    ports:
      - "3306:3306"
    environment:
      - MYSQL_DATABASE=mariadb
      - MYSQL_USER=mariadb
      - MYSQL_PASSWORD=changeme
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - portabase
      - default

volumes:
  postgres-data:
  mariadb-data:

networks:
  portabase:
    name: portabase_network
    external: true  # Run: docker network create portabase_network if needed

Configure Databases (databases.json)

Create databases.json:

{
  "databases": [
    {
      "name": "DEV - PostgreSQL",
      "database": "devdb",
      "type": "postgresql",
      "username": "devuser",
      "password": "changeme",
      "port": 5432,
      "host": "localhost",
      "generatedId": "uuid-here"  // Use uuidgen
    },
    {
      "name": "DEV - MariaDB",
      "database": "mariadb",
      "type": "mariadb",
      "username": "mariadb",
      "password": "changeme",
      "port": 3306,
      "host": "localhost",
      "generatedId": "uuid-here"
    }
  ]
}

(TOML format also supported.)

Launch the Agent

Run:

docker compose up -d

In the dashboard:

Go to Agents > Add Agent.
Copy the Edge Key and set it in the agent's environment.
The agent will auto-register and show as online.

Step 3: Configuring Backups and Advanced Usage

With everything running:

Organizations & Projects: Create workspaces for teams, with enhanced RBAC for better access control and collaboration.
Backup Policies: Set schedules (e.g., cron-based) and retention rules.
Storage Selection: Choose local or S3 for backups.
Notifications: Enable alerts for failures or completions via SMTP, Slack, etc., with severity-based routing.
Trigger Backups: Save policies to start automated runs.
Monitor and restore via the dashboard—supports PostgreSQL, MySQL, and now MariaDB.

Troubleshooting Tips

Connection Issues: Verify credentials; test with CLI tools.
Agent Offline: Check Edge Key and network; view logs with docker logs agent-portabase.
Ports/Storage: Adjust as needed; test S3 with CLI.
For proxies or advanced setups, consult the documentation.

Conclusion: Secure and Automate Your Data Management

Self-hosting Portabase turns complex database backups into a seamless, automated process. With recent updates adding MariaDB support, versatile notifications (SMTP, Slack, and more), and improved organizational features like RBAC and workspaces, it's more powerful than ever. Set it up in under 30 minutes and customize to fit your stack.

Contribute on GitHub: Server Repo | Agent Repo.

Join the community on Discord.

Video : Link

⭐ Star the project, deploy it, and share in the comments: Which databases are you backing up first?

DEV Community: Soluce Technologies