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)
Top comments (0)