# CLI Reference
import { TypeTable } from "fumadocs-ui/components/type-table";
import { Callout } from "fumadocs-ui/components/callout";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";
The **Portabase CLI** is the central orchestration tool. It acts as an intelligent wrapper on top of Docker Compose to:
1. **Generate** valid and secure configurations.
2. **Manage** the container lifecycle (start/stop/logs).
3. **Administer** database connections without manually editing JSON files.
***
Installation [#installation]
```bash
curl -sL https://portabase.io/install | bash
```
Check the installed version:
```bash
portabase --version
```
***
Development [#development]
If you want to contribute to the CLI or test your changes locally:
Clone the repository [#clone-the-repository]
```bash
git clone https://github.com/Portabase/cli.git
cd cli
```
Install dependencies [#install-dependencies]
```bash
uv sync
```
Link for local testing [#link-for-local-testing]
To use your local version of the CLI globally:
```bash
pip install -e .
```
Now the `portabase` command will point to your local development version.
Component Initialization [#component-initialization]
These commands generate the folder structure, `docker-compose.yml` files, `.env` configurations, and security keys.
agent [#agent]
Creates a new backup agent. The agent is the connector that installs on your database servers.
```bash
portabase agent [OPTIONS] NAME
```
**Arguments**
| Argument | Required | Description |
| :------- | :------: | :----------------------------------------------------- |
| `NAME` | Yes | The name of the folder to create (e.g., `prod-db-01`). |
**Options**
| Option | Alias | Description |
| :------------ | :---: | :------------------------------------------------------------------------------------------ |
| `--key ` | `-k` | The **Edge Key** provided by the Dashboard. If omitted, it will be requested interactively. |
| `--start` | `-s` | Start the agent immediately after creation. |
If you simply run `portabase agent my-agent`, the CLI will launch an assistant to:
1. Request the key.
2. Offer to automatically add database containers (Postgres/MariaDB).
dashboard [#dashboard]
Creates a Dashboard instance (the web management interface).
```bash
portabase dashboard [OPTIONS] NAME
```
**Options**
| Option | Alias | Description | Default |
| :------------- | :---: | :---------------------------------------------- | :------ |
| `--port ` | | The web listening port for the interface. | `8887` |
| `--start` | `-s` | Start the dashboard immediately after creation. | `False` |
***
Database Management (db) [#database-management-db]
The `db` module allows you to modify an agent's `databases.json` configuration without risk of syntax errors.
These commands modify the configuration. For them to take effect, you must restart the agent (`portabase restart <agent>`).
db list [#db-list]
Displays a summary table of databases configured for a given agent.
```bash
portabase db list
```
db add [#db-add]
Launches an interactive assistant to add a new connection to the configuration.
```bash
portabase db add
```
The assistant will ask you for:
* **Type**: PostgreSQL, MySQL, MariaDB.
* **Host**: The IP address or hostname (use `localhost` for a DB on the same server).
* **Port**: The listening port (e.g., 5432).
* **Credentials**: Username and password.
db remove [#db-remove]
Removes a database from the configuration via an interactive selection menu.
```bash
portabase db remove
```
***
Lifecycle (Operations) [#lifecycle-operations]
These commands replace direct use of `docker compose`. They must target the folder of a component (Agent or Dashboard).
If you are already in the component folder, you can use `.` as the path. Example: `portabase logs .`
start [#start]
Starts containers in detached mode (background). Equivalent to `docker compose up -d`.
```bash
portabase start
```
stop [#stop]
Stops containers cleanly.
```bash
portabase stop
```
restart [#restart]
Restarts all services. Useful after a configuration change (`db add` or modification in `.env`).
```bash
portabase restart
```
logs [#logs]
Displays container logs.
```bash
portabase logs [OPTIONS]
```
**Options**
| Option | Alias | Description |
| :------------------------- | :---: | :---------------------------------------------------------------------- |
| `--follow` / `--no-follow` | `-f` | Follows logs in real time (enabled by default). Press `Ctrl+C` to exit. |
uninstall [#uninstall]
Removes the entire deployment.
```bash
portabase uninstall [OPTIONS]
```
**Options**
| Option | Alias | Description |
| :-------- | :---: | :--------------------------------------------- |
| `--force` | `-f` | Does not ask for confirmation before deleting. |
This command performs a `docker compose down -v`. This **removes containers AND data volumes** (local databases, configurations).
This action is irreversible.
***
Common Troubleshooting [#common-troubleshooting]
The CLI needs to communicate with Docker. Make sure Docker is running:
* **Mac/Windows**: Launch Docker Desktop.
* **Linux**: Check the service (`sudo systemctl status docker`).
On Linux, if you haven't added your user to the `docker` group, you may need to run commands with `sudo`. *Recommended: Add
your user to the docker group to avoid using sudo.*
If the agent logs indicate it cannot reach the server:
1. Verify that your **Edge Key** is correct.
2. Verify that the dashboard URL (in the agent config) is accessible from the agent server.
# Contributing
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
We love contributions! Portabase is an open-source project, and we welcome help with the Dashboard, the Agent, and the CLI.
Whether you want to fix a bug, add a new feature, or improve the documentation, here is how you can get started with development for each component.
} description="Contribute to the Next.js web interface. Learn how to run it locally and manage the database." />
} description="Improve the Python-based agent that handles backups and communication with the dashboard." />
} description="Help enhance the Go-based command-line tool that orchestrates the entire ecosystem." />
***
General Workflow [#general-workflow]
1. **Fork** the repository you want to contribute to.
2. **Clone** your fork locally.
3. **Create a branch** for your changes.
4. **Commit** your work with clear and concise messages.
5. **Push** to your fork and **open a Pull Request**.
Thank you for helping make Portabase better!
# Getting Started
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
Portabase is composed of three main parts. To get started, we recommend installing the **Dashboard** first, then your first **Agent**.
} description="Set up the central management interface to manage all your backups and agents." />
} description="Deploy a lightweight agent on your database servers to handle backup tasks." />
} description="Learn how to use the Portabase CLI to automate installation and management." />
***
Quick start (CLI) [#quick-start-cli]
If you already have the requirements, you can install the CLI directly:
```bash
curl -sL https://portabase.io/install | bash
```
# Introduction
import VideoDialog from "../../src/features/common/components/video-dialog";
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, ShieldCheckIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
Welcome to Portabase [#welcome-to-portabase]
**Portabase** is the solution designed to simplify the **backup** and **management** of your databases.
We know that managing backups manually is risky and tedious. Portabase automates this process by installing smart connectors (**Agents**) on your servers. These agents handle everything: they secure your data and send it to your preferred storage spaces, without requiring advanced technical skills.
No more writing complex scripts. Portabase connects your servers to a unique dashboard for serene data management.
***
Features [#features]
Supported databases [#supported-databases]
| Database | Support | Tested versions |
| :------------- | :------- | :--------------------------- |
| **PostgreSQL** | ✅ Stable | 12, 13, 14, 15, 16, 17 et 18 |
| **MySQL** | ✅ Stable | 5.7, 8 et 9 |
| **MariaDB** | ✅ Stable | 10 et 11 |
| **MongoDB** | ✅ Stable | 4, 5, 6, 7 et 8 |
Scheduled backups [#scheduled-backups]
* **Cron-based scheduling**: For full control.
* **Manual trigger**: Support for on-demand backups.
Storage backends [#storage-backends]
* **On-premise storage**: Backups are stored directly on your server.
* **S3-compatible**: AWS S3, Minio, RustFS, etc ([documentation](/docs/dashboard/advanced/storage/s3)).
* **Google Drive** : coming soon.
* **Azure Blob Storage** : coming soon.
* **Google Cloud Storage** : coming soon.
Smart notifications [#smart-notifications]
* **Multi-channel delivery**: Email, Slack, Discord, Telegram, Ntfy, Gotify, webhooks.
* **Real-time alerts**: Immediate feedback on success and failure.
* **Custom alert policies**: Database-level notification rules.
* **Team-ready**: Designed for DevOps, on-call, and incident workflows.
Built for team environments [#built-for-team-environments]
* **Workspaces**: Organize databases, notification channels, and storage backends by organization and project.
* **Access control**: Fine-grained, role-based permissions on all resources.
* **Role management**: Member, admin, and owner roles at both system and organization levels.
Self-hosted & secure [#self-hosted--secure]
* **Containerized deployment**: Docker-based setup for predictable installation and operations.
* **Privacy by design**: All data remains within your own infrastructure.
* **Open source**: Apache 2.0 licensed — fully auditable codebase.
Portabase Agent [#portabase-agent]
* **Headless architecture**: Runs locally on your infrastructure to manage backups and database operations.
* **Multi-target support**: Single agent can connect to multiple databases across different servers.
* **Lightweight & efficient**: Minimal resource footprint while providing full operational control.
* **Secure communication**: Encrypted channels between agent and central dashboard.
***
How it works? [#how-it-works]
The ecosystem relies on three simple elements:
} description="The web interface to control your backups, view history, and restore your data if needed." />
} description="The connector that installs on your servers. It works in the background to protect your databases." />
} description="A simple tool to run on your computer to install and configure your agents in seconds." />
# Requirements
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
To run Portabase, you need the following installed on your system:
1. Docker & Docker Compose [#1-docker--docker-compose]
Portabase runs as a set of Docker containers. You must have Docker Engine (version 20.10+) and Docker Compose (version 2.0+) installed.
Ubuntu / Debian / Fedora [#ubuntu--debian--fedora]
The easiest way to install Docker on Linux is using the official convenience script:
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
**Post-installation steps:**
To run Docker without `sudo`, add your user to the `docker` group:
```bash
sudo usermod -aG docker $USER
```
*You may need to log out and back in for this change to take effect.*
Docker Desktop [#docker-desktop]
For macOS, the recommended way is to install **Docker Desktop**. It includes Docker Engine, Docker CLI, and Docker Compose.
1. Download the installer from the [Official Docker Website](https://docs.docker.com/desktop/install/mac-install/).
2. Drag and drop Docker into your Applications folder.
3. Launch Docker from your Applications.
***
2. Operating System [#2-operating-system]
* **Linux**: Any modern distribution (Ubuntu 22.04+, Debian 11+, CentOS, etc.).
* **macOS**: Catalina 10.15 or newer.
***
3. Network Requirements [#3-network-requirements]
* **Local Port**: By default, the dashboard uses port `8887`. Ensure it is not being used by another service.
* **Internet Access**: Required to pull Docker images and for the agent to communicate with the dashboard (if hosted remotely).
You can check if Docker is correctly installed by running `docker compose version` in your terminal.
***
4. Development Requirements (Optional) [#4-development-requirements-optional]
If you plan to contribute to Portabase or build it from source, you will need the following tools:
Agent (Rust) [#agent-rust]
The agent is built with Rust for performance and safety.
* **Rust**: Version 1.75+ (latest stable recommended).
* **Package manager**: `cargo`, included with the Rust toolchain.
CLI (Python) [#cli-python]
The CLI is written in Python with Typer.
* **Python**: Version 3.12+.
* **Package manager**: `uv`
Dashboard (TypeScript) [#dashboard-typescript]
The dashboard is a modern web application built with Next.js and React.
* **Node.js**: Version 20+.
* **Package manager**: `pnpm` Version 9+.
# Roadmap
If you are not redirected, [click here](https://github.com/orgs/Portabase/projects/1).
# Configuration File
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
The Portabase Agent needs to know where your databases are located to connect to them. This configuration is done via a file (commonly named `databases.json`) mounted into the Docker container.
You can manage this file in two ways:
1. **Via the CLI** (command `portabase db add`): recommended, as it generates IDs and validates the syntax for you.
2. **Manually**: useful for automation (Ansible, Terraform) or when you prefer editing files by hand.
The agent supports two formats: **JSON** (default) and **TOML** (more human-friendly).
***
File structure [#file-structure]
You can define multiple databases in a single file. This allows a single agent to back up, for example, both your `staging` and `production` environments.
Standard format used by the CLI.
```json title="databases.json"
{
"databases": [
{
"name": "my-site-prod",
"databases": "my-site-prod",
"type": "postgresql",
"host": "localhost",
"port": 5432,
"username": "admin_prod",
"password": "super_secure_password",
"generated_id": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "my-site-dev",
"databases": "my-site-dev",
"type": "mysql",
"host": "192.168.1.50",
"port": 3306,
"username": "root",
"password": "dev_password",
"generated_id": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
```
A format often preferred for its human readability.
```toml title="databases.toml"
[[databases]]
name = "my-site-prod"
type = "postgresql"
host = "localhost"
port = 5432
username = "admin_prod"
password = "super_secure_password"
generated_id = "550e8400-e29b-41d4-a716-446655440000"
[[databases]]
name = "my-site-dev"
type = "mysql"
host = "192.168.1.50"
port = 3306
username = "root"
password = "dev_password"
generated_id = "123e4567-e89b-12d3-a456-426614174000"
```
***
Field reference [#field-reference]
Here is the meaning of each configuration parameter:
| Field | Required | Description |
| :------------- | :------: | :--------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | The database name to back up (e.g. "prod\_api"). |
| `type` | Yes | Engine type: `postgresql`, `mysql`, `mariadb` (use `mysql` for MariaDB). |
| `host` | Yes | Host IP or name. If the agent runs on the same server, use `localhost` (with `extra_hosts` in Docker) or the local IP. |
| `port` | Yes | Listening port (`5432` for Postgres, `3306` for MySQL). |
| `username` | Yes | User with read/dump permissions. |
| `password` | Yes | Password for that user. |
| `generated_id` | **Yes** | A unique UUID v4 identifier. |
***
The generatedId rule [#the-generatedid-rule]
Each database must have a **unique ID**. This ID lets the Dashboard recognize a database's backup history even if you rename it.
If you create this file manually, you **must** generate a valid UUID v4. Do not invent a simple random string.
**How to generate a UUID:**
* **Terminal**: `uuidgen`.
* **Python**: `python3 -c "import uuid; print(uuid.uuid4())"`.
* **Online**: [https://www.uuidgenerator.net/](https://www.uuidgenerator.net/).
***
Docker mount [#docker-mount]
If you edit the file manually, ensure it's mounted into the agent container.
```yaml title="docker-compose.yml"
services:
agent:
# ...
volumes:
- ./databases.json:/config/config.json
```
After any manual change, restart the agent so it picks up the new configuration:
`docker compose restart agent`
# Installation
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
The **Portabase Agent** is a lightweight connector that runs on your servers. Its role is to:
1. Secure the connection with the Dashboard.
2. Execute backup tasks.
3. Manage local (or remote) databases.
It can manage existing databases (already installed on your server) or create new ones via Docker.
***
Need to be update, check docker install
The CLI guides you step by step: it configures the agent and offers to add databases immediately.
Ensure the CLI is installed first. If it isn’t, follow the instructions [here](/docs/cli#installation).
Retrieve your Edge Key [#retrieve-your-edge-key]
Before starting, go to your **Portabase Dashboard**, create a new Agent and copy its **Edge Key**.
Create the Agent [#create-the-agent]
Run the command on the server where you want to install the agent:
```bash
portabase agent my-agent
```
The CLI will ask for your **Edge Key**. Paste it and confirm.
Configure Databases [#configure-databases]
The wizard will ask whether you want to configure a database. You have two choices:
* **Docker (New Local Container)**: The CLI will add a PostgreSQL or MariaDB container to the agent's `docker-compose.yml`. Great for starting a fresh local project.
* **Manual (External/Existing)**: To connect an already existing database on your server (or a remote RDS/managed instance). You will need to provide host, port and credentials.
Start [#start]
If you didn't start the agent at the end of installation:
```bash
portabase start my-agent
```
For a manual installation, create the file structure and configure the network so the agent can reach your local databases.
File structure [#file-structure]
Create a folder and prepare required files:
```bash
mkdir portabase-agent && cd portabase-agent
touch docker-compose.yml .env databases.json
```
The `databases.json` file must exist (even empty) before starting the container, otherwise the agent may fail to start.
Initialize the JSON file with an empty object:
```bash
echo '{"databases": []}' > databases.json
```
Docker configuration [#docker-configuration]
Create the `docker-compose.yml`. Note the use of `extra_hosts` so the agent can reach the host's services via `localhost`.
```yaml title="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: "UTC"
POLLING: 5
APP_ENV: production
DATA_PATH: "/data"
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`.*
Environment variables [#environment-variables]
Add your key and optional configurations to the `.env` file:
```bash title=".env"
EDGE_KEY=your_edge_key_here
TZ=UTC
POLLING=5
APP_ENV=production
DATA_PATH=/data
```
| Variable | Description | Default |
| :---------- | :--------------------------------------------------------- | :----------- |
| `EDGE_KEY` | Your agent's unique key from the dashboard. | **Required** |
| `TZ` | Timezone for the agent (e.g., `UTC`, `Europe/Paris`). | `UTC` |
| `POLLING` | Frequency (in seconds) to check for new tasks. | `5` |
| `APP_ENV` | Environment type (`production`, `staging`, `development`). | `production` |
| `DATA_PATH` | Internal path where the agent stores its data. | `/data` |
Start [#start-1]
```bash
docker compose up -d
```
***
[//]: # "## Database Management"
[//]: #
[//]: # "For a full list of supported databases and detailed configurations, check the [Databases](./db) section."
[//]: #
[//]: # "Once the agent is installed, you need to tell it which databases to backup. The CLI offers a dedicated `db` module to manage the `databases.json` configuration file without syntax errors."
[//]: #
[//]: # "### Add a database"
[//]: #
[//]: # "This command launches an interactive assistant to add a connection (Postgres, MySQL, MariaDB)."
[//]: #
[//]: # "```bash"
[//]: # "# Syntax: portabase db add "
[//]: # "portabase db add my-agent"
[//]: # "```"
[//]: #
[//]: # "You will be asked for:"
[//]: #
[//]: # "- **Type**: PostgreSQL, MySQL or MariaDB."
[//]: # "- **Host**: `localhost` (if on the same machine) or an IP address."
[//]: # "- **Port**: e.g. `5432`."
[//]: # "- **Credentials**: User and Password."
[//]: #
[//]: # "### List configured databases"
[//]: #
[//]: # "To see which databases are managed by this agent:"
[//]: #
[//]: # "```bash"
[//]: # "portabase db list my-agent"
[//]: # "```"
[//]: #
[//]: # "### Remove a database"
[//]: #
[//]: # "```bash"
[//]: # "portabase db remove my-agent"
[//]: # "```"
[//]: #
[//]: # ""
[//]: # " After adding or removing a database, it's recommended to restart the agent so changes are applied immediately:"
[//]: # " `portabase restart my-agent`"
[//]: # ""
Development [#development]
To set up the agent in a development environment:
Clone the repository [#clone-the-repository]
```bash
git clone https://github.com/Portabase/agent-rust.git
cd agent-rust
```
Build the agent [#build-the-agent]
```bash
cargo build
```
Start in development mode [#start-in-development-mode]
```bash
docker compose up
```
***
Lifecycle commands [#lifecycle-commands]
As with the dashboard, you can control the agent with standard commands:
| Command | Description |
| :--------------------------- | :--------------------------------------------------------------------- |
| `portabase start ` | Start the agent. |
| `portabase stop ` | Stop the agent. |
| `portabase logs ` | Check whether the agent is connected to the dashboard ("Ping server"). |
| `portabase uninstall ` | Remove the agent and its configuration. |
# Installation
import {Tab, Tabs} from "fumadocs-ui/components/tabs";
import {Step, Steps} from "fumadocs-ui/components/steps";
import {Callout} from "fumadocs-ui/components/callout";
The **Portabase Dashboard** is the central interface that allows you to manage your agents, configure your backups, and visualize the state of your infrastructure.
You have two methods to install it:
1. **Via CLI**: Ideal for getting started quickly locally.
2. **Via Docker Compose**: Recommended for advanced production environments or GitOps.
***
The CLI takes care of everything: it downloads templates, generates encryption secrets (`PROJECT_SECRET`),
configures the internal database, and launches the containers.
Ensure the CLI is installed first. If it isn’t, follow the instructions [here](/docs/cli#installation).
Create the Dashboard [#create-the-dashboard]
Run the following command. This will create a folder containing the configuration.
```bash
# Syntax: portabase dashboard
portabase dashboard my-dashboard
```
By default, the interface will be on port **8887**. You can change it with the `--port` option:
```bash
portabase dashboard my-dashboard --port 8887
```
Start the service [#start-the-service]
If you didn't use the `--start` option during creation, start the service manually:
```bash
portabase start my-dashboard
```
Access the interface [#access-the-interface]
Open your browser: **[http://localhost:8887](http://localhost:8887)** (or the chosen port).
If you don't want to use the CLI, you can deploy the stack with Docker Run. It is recommended for testing but not for production use, as you will be using the internal PostgreSQL database.
Ensure you already installed Docker engine.
Environment variables [#environment-variables]
Create the `.env` file. **Warning**, you must generate passwords and secrets yourself.
```bash title=".env"
# --- App Configuration ---
HOST_PORT=8887
PROJECT_NAME=portabase-dashboard
PROJECT_URL=http://localhost:8887
# ⚠️ GENERATE A STRONG SECRET (e.g., openssl rand -hex 32)
# This secret is used to encrypt communications with agents.
PROJECT_SECRET=change_me_please_generate_a_secure_hex_token
```
Start the Dashboard [#start-the-dashboard]
Run the following command to start the Portabase service.
```bash
docker run -d \
--name portabase-app-prod \
-p 8887:80 \
--restart unless-stopped \
-e TZ="Europe/Paris" \
--env-file .env \
-v ./portabase-data:/data \
portabase/portabase:latest
```
Access the interface [#access-the-interface-1]
Open your browser: **[http://localhost:8887](http://localhost:8887)** (or the chosen port).
If you don't want to use the CLI, you can deploy the stack manually.
File structure [#file-structure]
Create a folder and place two files in it: `docker-compose.yml` and `.env`.
```bash
mkdir portabase-dashboard && cd portabase-dashboard
```
Docker configuration [#docker-configuration]
```bash
mkdir portabase-dashboard && cd portabase-dashboard
```
Docker configuration [#docker-configuration-1]
```yaml title="docker-compose.yml"
name: portabase-dashboard
services:
portabase:
container_name: portabase-app
image: portabase/portabase:latest
restart: always
env_file: .env
environment:
- TZ=Europe/Paris
ports:
- "${HOST_PORT:-8887}:80"
volumes:
- portabase-data:/data
depends_on:
db:
condition: service_healthy
db:
container_name: portabase-pg
image: postgres:17-alpine
restart: always
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres-data:
portabase-data:
```
Environment variables [#environment-variables-1]
Create the `.env` file. **Warning**, you must generate passwords and secrets yourself.
```bash title=".env"
# --- App Configuration ---
HOST_PORT=8887
PROJECT_NAME=portabase-dashboard
PROJECT_URL=http://localhost:8887
# ⚠️ GENERATE A STRONG SECRET (e.g., openssl rand -hex 32)
# This secret is used to encrypt communications with agents.
PROJECT_SECRET=change_me_please_generate_a_secure_hex_token
# --- Internal Database Configuration ---
POSTGRES_DB=portabase
POSTGRES_USER=portabase
POSTGRES_PASSWORD=change_me_secure_db_password
POSTGRES_HOST=db
# Connection URL (do not modify the structure)
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}?schema=public
```
Startup [#startup]
```bash
docker compose up -d
```
Access the interface [#access-the-interface-2]
Open your browser: **[http://localhost:8887](http://localhost:8887)** (or the chosen port).
***
Development [#development]
If you want to contribute to the Dashboard or run it from source:
Clone the repository [#clone-the-repository]
```bash
git clone https://github.com/Portabase/portabase.git
cd portabase
```
Install dependencies [#install-dependencies]
```bash
pnpm install
```
Environment configuration [#environment-configuration]
Copy the example environment file and adjust values if necessary:
```bash
cp .env.example .env
```
Start in development mode [#start-in-development-mode]
```bash
make up
```
Daily management (CLI) [#daily-management-cli]
The CLI offers convenient shortcuts to manage your dashboard's lifecycle without having to type complex Docker commands.
| Action | Command | Description |
| :------------ | :--------------------------- | :----------------------------------------------------------- |
| **Start** | `portabase start ` | Launches containers in the background (`up -d`). |
| **Stop** | `portabase stop ` | Stops containers cleanly. |
| **Restart** | `portabase restart ` | Restarts the complete stack. |
| **Logs** | `portabase logs ` | Displays logs in real time (`-f` option enabled by default). |
| **Uninstall** | `portabase uninstall ` | ⚠️ Removes containers **and** data volumes. |
# Supported Databases
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
The Portabase agent is designed to be agnostic and modular. It natively supports several database engines, whether for local (Docker) or remote backups.
Supported Databases [#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 |
Global Configuration [#global-configuration]
Regardless of the database, the configuration follows the same pattern. You must tell the agent how to connect (host, port, credentials).
This is the simplest method. The agent has a dedicated command to add a configuration without errors.
```bash
# Inside your agent directory
portabase db add .
```
The wizard will ask for:
1. The database **type** (e.g., `postgresql`).
2. The **name** (e.g., `prod-app`).
3. The **host** (`localhost` or IP).
4. The **credentials**.
You can also edit the `databases.json` (or `.toml`) file mounted in the container.
```json title="databases.json"
{
"databases": [
{
"name": "my-db",
"type": "postgresql",
"host": "db-prod",
"port": 5432,
"username": "admin",
"password": "secret_password",
"generated_id": "uuid-v4-unique"
}
]
}
```
For more details on each engine, check the dedicated pages in this section.
# MongoDB
The agent will use `mongodump` to perform backups and `mongorestore` to restore backups.
Configuration with Auth [#configuration-with-auth]
```json
{
"name": "my-mongo-auth",
"type": "mongodb",
"host": "db-mongodb-auth",
"port": 27017,
"username": "username",
"password": "password",
"database": "testdbauth",
"generated_id": "..."
}
```
Configuration without Authentication [#configuration-without-authentication]
```json
{
"name": "my-mongo",
"type": "mongodb",
"host": "db-mongodb",
"port": 27017,
"username": "",
"password": "",
"database": "testdb",
"generated_id": "..."
}
```
Docker Compose Example [#docker-compose-example]
Example with a MongoDB image.
```yaml title="docker-compose.yml"
services:
db-mongodb-auth:
container_name: db-mongodb-auth
image: mongo:latest
ports:
- "27082:27017"
environment:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: rootpassword
MONGO_INITDB_DATABASE: testdbauth
command: mongod --auth
networks:
- portabase
volumes:
- mongodb-data-auth:/data/db
healthcheck:
test: [ "CMD", "mongo", "--eval", "db.adminCommand('ping')" ]
interval: 5s
timeout: 5s
retries: 10
db-mongodb:
container_name: db-mongodb
image: mongo:latest
ports:
- "27083:27017"
volumes:
- mongodb-data:/data/db
healthcheck:
test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ]
interval: 5s
timeout: 5s
retries: 10
environment:
MONGO_INITDB_DATABASE: testdb
networks:
- portabase
agent:
image: portabase/agent:latest
# ... agent configuration ...
depends_on:
- db-mongodb
- db-mongodb-auth
networks:
- portabase
networks:
portabase:
external: true
volumes:
mongodb-data:
mongodb-data-auth:
```
If you use `localhost` as the host (because the agent is on the host machine and not in Docker, or via `host-gateway`), ensure your database is listening on all interfaces (`0.0.0.0`) or is accessible from the agent.
# MySQL & MariaDB
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
The agent supports both MySQL and MariaDB via the same driver.
Configuration [#configuration]
When running `portabase db add`, select `mysql` or `mariadb` (it uses the same driver).
**Specific parameters asked:**
* **Database Name**: The name of the database to backup.
In your `databases.json` file, use the `mysql` type for both databases.
```json title="databases.json"
{
"name": "my-wp-site",
"type": "mysql",
"host": "mariadb",
"port": 3306,
"username": "root",
"password": "root_password",
"database": "wordpress",
"generated_id": "..."
}
```
**Specific Parameters:**
* **database**: (Required) The name of the database.
Docker Compose Example [#docker-compose-example]
Example with a MariaDB image.
```yaml title="docker-compose.yml"
services:
mariadb:
image: mariadb:10.6
container_name: my-mariadb
restart: always
environment:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: wordpress
MYSQL_USER: wp_user
MYSQL_PASSWORD: wp_password
volumes:
- db_data:/var/lib/mysql
networks:
- portabase
agent:
image: portabase/agent:latest
# ... agent configuration ...
depends_on:
- mariadb
networks:
- portabase
networks:
portabase:
external: true
volumes:
db_data:
```
If you use `localhost` as the host (because the agent is on the host machine and not in Docker, or via `host-gateway`), ensure your database is listening on all interfaces (`0.0.0.0`) or is accessible from the agent.
# PostgreSQL
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
PostgreSQL is fully supported by the Portabase agent. We use native `pg_dump` tools to ensure consistent and reliable backups.
Configuration [#configuration]
When running `portabase db add`, select `postgresql` as the database type.
**Specific parameters asked:**
* **Database Name**: The exact name of the database to backup (e.g., `app_db`). Unlike other engines, you must target a specific database.
In your `databases.json` (or `.toml`) file, configure the following block.
```json title="databases.json"
{
"name": "my-app-postgres",
"type": "postgresql",
"host": "postgres",
"port": 5432,
"username": "postgres",
"password": "mysecretpassword",
"database": "app_db",
"generated_id": "..."
}
```
**Specific Parameters:**
* **database**: (Required) The exact name of the database to dump.
Docker Compose Example [#docker-compose-example]
Here is how to configure a PostgreSQL service alongside the agent.
```yaml title="docker-compose.yml"
services:
postgres:
image: postgres:15-alpine
container_name: my-postgres
restart: always
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: mysecretpassword
POSTGRES_DB: app_db
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- portabase
agent:
image: portabase/agent:latest
# ... agent configuration ...
depends_on:
- postgres
networks:
- portabase
networks:
portabase:
external: true
volumes:
postgres_data:
```
Note that in this example, the host (`host`) to enter in the agent configuration will be `postgres` (the service name), not `localhost`.
# Environment Variables
import {Callout} from 'fumadocs-ui/components/callout';
Portabase provides flexibility through environment variables. These let you customize application behavior, database connection, authentication and storage.
If you use Docker Compose, set these variables in your `.env` file at the root of the project.
***
Project [#project]
General instance configuration.
| Variable | Type | Default | Description |
| :-------------------- | :------- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `PROJECT_NAME` | `string` | `Portabase` | Display name in the UI (site title). |
| `PROJECT_DESCRIPTION` | `string` | `Manage all your database instances from one place !` | Project tagline or description. |
| `PROJECT_URL` | `string` | `http://localhost:8887` | Public URL of your dashboard (e.g. `https://backups.my-domain.com`). Important for generated links. |
| `PROJECT_SECRET` | `string` | `None` | **Critical.** Secret used to encrypt sensitive data. Generate with `openssl rand -hex 32`. |
| `RETENTION_CRON` | `string` | `0 7 * * *` | Schedule for automatic deletion of backups according to the retention policies. |
***
Database [#database]
Configuration for the internal Portabase PostgreSQL connection.
| Variable | Type | Default | Description |
| :------------------ | :------- | :---------------------------------------------------------------------------------------- | :-------------------------------------- |
| `POSTGRES_DB` | `string` | `devdb` | Database name. |
| `POSTGRES_USER` | `string` | `devuser` | PostgreSQL user. |
| `POSTGRES_PASSWORD` | `string` | `changeme` | User password. |
| `DATABASE_URL` | `string` | `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?schema=public` | Full connection string used by the app. |
***
Email (SMTP) [#email-smtp]
Configuration for transactional email delivery (alerts, invitations).
If no configuration is provided, email-related features will be limited (no password reset, no email verification).
| Variable | Type | Default | Description |
| :-------------- | :------- | :------ | :---------------------------------------------------- |
| `SMTP_HOST` | `string` | `None` | SMTP server address (e.g. `smtp.resend.com`). |
| `SMTP_PORT` | `string` | `None` | SMTP server port (e.g. `587`). |
| `SMTP_USER` | `string` | `None` | SMTP username. |
| `SMTP_PASSWORD` | `string` | `None` | SMTP password. |
| `SMTP_FROM` | `string` | `None` | From email address (e.g. `no-reply@your-domain.com`). |
| `SMTP_SECURE` | `string` | `false` | |
***
Google Authentication (OAuth2) [#google-authentication-oauth2]
Enable login via Google (SSO).
| Variable | Type | Default | Description |
| :------------------- | :------- | :------ | :-------------------------------------------------------- |
| `AUTH_GOOGLE_METHOD` | `string` | `false` | Enable (`true`) or disable (`false`) the Google provider. |
| `AUTH_GOOGLE_ID` | `string` | `None` | Your Google Cloud OAuth2 Client ID. |
| `AUTH_GOOGLE_SECRET` | `string` | `None` | Your Google Cloud OAuth2 Client Secret. |
# Reverse Proxy
import {Tab, Tabs} from "fumadocs-ui/components/tabs";
import {Callout} from "fumadocs-ui/components/callout";
By default, the Portabase Dashboard listens on `http://localhost:8887`. To make it accessible from the outside (e.g. `backup.my-company.com`) and secure it with HTTPS, use a **Reverse Proxy**.
***
This setup assumes you already run a **Traefik** instance on your server and it watches the Docker network
(commonly `traefik_network` or `proxy`).
Docker Compose changes [#docker-compose-changes]
Modify your `docker-compose.yml` to:
1. Remove direct host port exposure (no `8887:80`).
2. Connect the container to Traefik's network.
3. Add Traefik labels.
```yaml title="docker-compose.yml"
name: portabase-dashboard
services:
portabase:
container_name: portabase-app
image: portabase/portabase:latest
restart: always
env_file: .env
expose:
- 80
volumes:
- portabase-private:/app/private
depends_on:
db:
condition: service_healthy
networks:
- traefik_network # Network where Traefik lives
- default # To talk to the local database
labels:
- "traefik.enable=true"
- "traefik.http.routers.portabase.entrypoints=web,websecure"
- "traefik.http.routers.portabase.rule=Host(`portabase.example.com`)"
- "traefik.http.routers.portabase.tls.certresolver=myresolver"
db:
container_name: portabase-pg
image: postgres:17-alpine
restart: always
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
networks:
- default
volumes:
postgres-data:
portabase-private:
networks:
traefik_network:
external: true
```
If you host **multiple dashboards** on the same Traefik server, change the router name in labels to unique
values:
* Instance 1: `traefik.http.routers.portabase-prod...`
* Instance 2: `traefik.http.routers.portabase-dev...`
If you use a traditional web server like Nginx, Apache or Caddy on the host:
1. Portabase configuration [#1-portabase-configuration]
Keep the default config that binds the service to localhost.
```yaml
ports:
- "127.0.0.1:8887:80" # Listen only on localhost
```
2. Nginx example [#2-nginx-example]
Create a server block that proxies requests to the local port 8887.
```nginx title="/etc/nginx/sites-available/portabase"
server {
server_name portabase.example.com;
location / {
proxy_pass http://portabase:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
🚧 Work in progress 🚧
***
PROJECT_URL environment variable [#project_url-environment-variable]
Whatever reverse proxy you use, update the `.env` file so generated links and emails use the correct public URL.
```bash title=".env"
# Before
PROJECT_URL=http://localhost:8887
# After (your public domain)
PROJECT_URL=https://portabase.example.com
```
Restart the dashboard after changing this:
```bash
portabase restart .
```
```bash
docker-compose down && docker-compose up -d
```
# Google Drive
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
By default, Portabase stores backups on the local disk of the Dashboard server.
For production environments, we strongly recommend using external storage to:
* Separate compute (Dashboard) from storage.
* Benefit from virtually unlimited capacity.
* Protect data if the Dashboard server is lost.
Creation of a new OAuth Client in the Google Cloud Console [#creation-of-a-new-oauth-client-in-the-google-cloud-console]
Navigate to [Google Cloud Console](https://console.cloud.google.com).
2. Open the sidebar menu and go to **API & Services > Credentials**.
Click **Create Credentials > OAuth Client ID**.
Select **Web Application** as the application type and configure the **Authorized JavaScript origins** and **Authorized redirect URIs** according to your domain.
Click **Create**, then note the generated **Client ID** and **Client Secret**.
Configuration on the dashboard [#configuration-on-the-dashboard]
In **Storage > Channels**, click on **+ Add Storage Channel** and choose **Google Drive**.
Enter the credentials previously generated in the Google Cloud Console.
Click **Connect Google Drive** to initiate the OAuth 2.0 authentication flow.
Click **Add Channel** to finalize the configuration.
# Local Storage
import { Callout } from "fumadocs-ui/components/callout";
By default, Portabase is configured to use **Local Storage**. This means that backups sent by your agents are stored on the disk of the machine where the dashboard is running.
This method is ideal for:
* Testing and discovery.
* Small infrastructures.
* Using a network mount (NFS, EFS) already attached to the server.
Data Persistence [#data-persistence]
If you are using **Docker**, it is crucial to use a volume to ensure your backups are not lost when the container is restarted or updated.
The default `docker-compose.yml` provided by the CLI already includes a volume for the `private` folder:
```yaml title="docker-compose.yml"
services:
portabase:
# ...
volumes:
- portabase-private:/app/private
```
Backups are stored inside `/app/private/backups`.
Using a Custom Path [#using-a-custom-path]
If you want to store backups in a specific folder on your host machine (e.g., an external hard drive or a dedicated partition), you can use a **bind mount** in your `docker-compose.yml`:
```yaml title="docker-compose.yml"
services:
portabase:
# ...
volumes:
- /mnt/backups/portabase:/app/private/backups
```
Make sure the user running the Docker container (usually `node` or `root`) has write permissions on the host folder.
# Object Storage (S3)
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
By default, Portabase stores backups on the local disk of the server. For production environments, we strongly recommend using external storage to:
* Decouple storage from compute resources.
* Benefit from virtually unlimited capacity.
* Ensure data protection through the reliability of dedicated storage solutions.
***
Provider configuration (if self-hosted) [#provider-configuration-if-self-hosted]
This adds a **MinIO** service to your Docker Compose stack, typically behind Traefik.
Docker Compose changes [#docker-compose-changes]
MinIO exposes two ports:
* **9000**: S3 API (used by Portabase).
* **9001**: Web Console (admin UI).
```yaml title="docker-compose.yml"
name: portabase-stack
services:
portabase:
image: portabase/portabase:latest
container_name: portabase-app
env_file: .env
volumes:
- portabase-private:/app/private
depends_on:
db:
condition: service_healthy
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
- "traefik.http.routers.portabase.rule=Host(`dashboard.example.com`)"
- "traefik.http.routers.portabase.entrypoints=websecure"
- "traefik.http.routers.portabase.tls.certresolver=myresolver"
# ... standard DB service ...
s3:
image: docker.io/bitnami/minio:latest
container_name: portabase-minio
expose:
- 9000
- 9001
volumes:
- minio-data:/data
environment:
- MINIO_ROOT_USER=${S3_ACCESS_KEY}
- MINIO_ROOT_PASSWORD=${S3_SECRET_KEY}
- MINIO_DEFAULT_BUCKETS=${S3_BUCKET_NAME}
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
- "traefik.http.routers.api-s3.rule=Host(`api.s3.example.com`)"
- "traefik.http.routers.api-s3.entrypoints=websecure"
- "traefik.http.routers.api-s3.tls.certresolver=myresolver"
- "traefik.http.services.api-s3.loadbalancer.server.port=9000"
- "traefik.http.routers.webui-s3.rule=Host(`console.s3.example.com`)"
- "traefik.http.routers.webui-s3.entrypoints=websecure"
- "traefik.http.services.webui-s3.loadbalancer.server.port=9001"
volumes:
portabase-private:
postgres-data:
minio-data:
networks:
traefik_network:
external: true
```
You can run a single-node RustFS instance using Docker Compose.
1. Docker Compose configuration [#1-docker-compose-configuration]
```yaml title="docker-compose.yml"
name: portabase-stack
services:
# ... other services (portabase, db) ...
rustfs:
image: rustfs/rustfs:latest
container_name: portabase-rustfs
expose:
- 9000
- 9001
environment:
- RUSTFS_ADDRESS=0.0.0.0:9000
- RUSTFS_CONSOLE_ADDRESS=0.0.0.0:9001
- RUSTFS_CONSOLE_ENABLE=true
- RUSTFS_ACCESS_KEY=${S3_ACCESS_KEY}
- RUSTFS_SECRET_KEY=${S3_SECRET_KEY}
volumes:
- rustfs-data:/data
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
# Route 1: S3 API
- "traefik.http.routers.rustfs-api.rule=Host(`s3.example.com`)"
- "traefik.http.routers.rustfs-api.entrypoints=websecure"
- "traefik.http.routers.rustfs-api.tls.certresolver=myresolver"
- "traefik.http.services.rustfs-api.loadbalancer.server.port=9000"
# Route 2: Web Console
- "traefik.http.routers.rustfs-console.rule=Host(`console.s3.example.com`)"
- "traefik.http.routers.rustfs-console.entrypoints=websecure"
- "traefik.http.routers.rustfs-console.tls.certresolver=myresolver"
- "traefik.http.services.rustfs-console.loadbalancer.server.port=9001"
volumes:
rustfs-data:
networks:
traefik_network:
external: true
```
Configuration on the dashboard [#configuration-on-the-dashboard]
In **Storage > Channels**, click on **+ Add Storage Channel** choose **S3**.
Enter the credentials.
Click **Add Channel** to finalize the configuration.
***
Verification [#verification]
1. Restart the dashboard:
```bash
portabase restart .
```
```bash
docker-compose down && docker-compose up -d
```
2. Log into the web UI.
3. Trigger a manual backup on an agent.
4. Check your bucket (or MinIO console) to confirm the backup file exists.
# Discord
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
Discord notifications use the platform's native Webhook system to post messages to a specific channel.
Discord server configuration [#discord-server-configuration]
In Discord, go to **Server Settings > Integrations > Webhooks**.
Create a new Webhook and copy its **URL**.
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Discord**.
Enter the Discord webhook URL obtained earlier (e.g., `https://discord.com/api/webhooks/...`) and click **Add Channel**.
To test the configuration, click the channel's edit icon, then click **Test Channel**. Verify that a test message appears in the selected Discord channel.
# Email (SMTP)
import {Callout} from "fumadocs-ui/components/callout";
import {Step, Steps} from "fumadocs-ui/components/steps";
import Image from "next/image";
Email notifications are the most standard way to stay informed about your backups. To use them, you need to provide your own SMTP server credentials.
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Email**.
* **SMTP Host**: The address of your mail server (e.g., `smtp.gmail.com` or `smtp.sendgrid.net`).
* **SMTP Port**: Usually `587` (TLS) or `465` (SSL).
* **Username**: Your email account username.
* **Password**: Your email account password or an App Password.
* **From Address**: The email address that will appear as the sender (e.g., `noreply@yourdomain.com`).
If you are using Gmail, you likely need to generate an **App Password** in your Google Account security
settings instead of using your main password.
To test the configuration, click the channel's edit icon, then click **Test Channel**. Portabase will attempt to
send a test email to the configured administrator email address.
# Gotify
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
[Gotify](https://gotify.net) is a simple server for sending and receiving messages in real-time (WebSocket).
Configuration on your Gotify instance [#configuration-on-your-gotify-instance]
1. Log in to your Gotify instance.
2. Create a new **Application** (e.g., "Portabase").
3. Copy the **Token** generated for this application.
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Gotify**.
Enter the following information:
* **Server URL**: The full URL of your Gotify instance (e.g., `https://gotify.yourdomain.com`).
* **App Token**: The application token you just created.
To test the configuration, click the channel's edit icon, then click **Test Channel**. The message should appear instantly in your Gotify interface or on your mobile.
# Ntfy
import { Callout } from "fumadocs-ui/components/callout";
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
[Ntfy](https://ntfy.sh) is a simple HTTP notification service. You can use the official public server or your own self-hosted instance.
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **ntfy.sh**.
Enter the following information:
* **Server URL**: Your server address. Default: `https://ntfy.sh`.
* **Topic**: The name of the topic to subscribe to (e.g., `my-project-alerts`).
* **Token** (Optional): If your topic or server is protected by authentication.
If you use the public server `ntfy.sh`, be aware that topics are public if not protected. Choose a complex name or configure access rights.
To test the configuration, click the channel's edit icon, then click **Test Channel**. The message should appear instantly in your Ntfy interface or on your mobile.
# Slack
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
Portabase allows you to send real-time notifications to a Slack channel when a backup succeeds or fails.
Configuration on Slack API [#configuration-on-slack-api]
Create a Slack App [#create-a-slack-app]
1. Go to [api.slack.com/apps](https://api.slack.com/apps).
2. Click **Create New App** and select **From scratch**.
3. Name your app (e.g., "Portabase Bot") and select your workspace.
Activate Incoming Webhooks [#activate-incoming-webhooks]
1. In the left sidebar, click on **Incoming Webhooks**.
2. Toggle the switch to **On**.
3. Click the **Add New Webhook to Workspace** button at the bottom.
4. Select the channel where you want notifications to appear and click **Allow**.
Copy the Webhook URL [#copy-the-webhook-url]
You will see a URL that looks like this:
`https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`
Copy this URL.
[//]: # "### Configure Portabase"
[//]: #
[//]: # "1. Open your **Portabase Dashboard**."
[//]: # "2. Go to **Notifications > Channels**."
[//]: # "3. Click on **Add notification channel** and select **Slack**."
[//]: # "4. Paste the **Webhook URL**."
[//]: # "5. Click **Save** and **Test** to ensure it works."
[//]: # ""
[//]: # ""
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Slack**.
Enter the Slack webhook URL obtained earlier `https://hooks.slack.com/services/...` and click **Add Channel**.
To test the configuration, click the channel's edit icon, then click **Test Channel**. Verify that a test message appears in the selected Slack channel.
# Telegram
import {Step, Steps} from "fumadocs-ui/components/steps";
import Image from "next/image";
To receive notifications on Telegram, you need to create a bot and obtain its access token as well as the recipient chat ID.
Configuration of Telegram Bot [#configuration-of-telegram-bot]
Contact [@BotFather](https://t.me/botfather) on Telegram to create a new bot and get your **Token** (e.g.,
`123456:ABC-DEF1234...`).
Start a conversation with your bot (click "Start").
Retrieve your **Chat ID** (you can use a bot like `@userinfobot` to find it).
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Telegram**.
Enter the following information:
* **Bot Token**: The token provided by BotFather.
* **Chat ID**: The numeric identifier of the conversation or group.
To test the configuration, click the channel's edit icon, then click **Test Channel**. Your bot should send you
a test message immediately.
# Webhook
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
Webhook notifications allow you to send HTTP (POST) requests to a URL of your choice when an event occurs. This is the ideal solution for connecting Portabase to automation tools or custom scripts.
Configuration on the dashboard [#configuration-on-the-dashboard]
Go to **Notifications > Channels**, click on **+ Add Notification Channel**, and choose **Webhook**.
Enter the following information:
* **Webhook URL**: The URL that will receive the POST request.
* **Header** (optional): HTTP headers to secure or identify your requests (for example, `Authorization` to provide an authentication token). By default, Portabase sends `X-Webhook-Secret`.
To test the configuration, click the channel's edit icon, then click **Test Channel**. Verify that your endpoint responds correctly.
# Référence CLI
import { TypeTable } from "fumadocs-ui/components/type-table";
import { Callout } from "fumadocs-ui/components/callout";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";
Le **Portabase CLI** est l'outil d'orchestration central. Il agit comme une surcouche intelligente au-dessus de Docker Compose pour :
1. **Générer** des configurations valides et sécurisées.
2. **Gérer** le cycle de vie des conteneurs (start/stop/logs).
3. **Administrer** les connexions aux bases de données sans éditer de JSON manuellement.
***
Installation [#installation]
```bash
curl -sL https://portabase.io/install | bash
```
Vérifier la version installée :
```bash
portabase --version
```
***
Développement [#développement]
Si vous souhaitez contribuer au CLI ou tester vos modifications localement :
Cloner le dépôt [#cloner-le-dépôt]
```bash
git clone https://github.com/Portabase/cli.git
cd cli
```
Installer les dépendances [#installer-les-dépendances]
```bash
uv sync
```
Lier pour les tests locaux [#lier-pour-les-tests-locaux]
Pour utiliser votre version locale du CLI globalement :
```bash
pip install -e .
```
Désormais, la commande `portabase` pointera vers votre version de développement locale.
Initialisation des Composants [#initialisation-des-composants]
Ces commandes génèrent la structure de dossiers, les fichiers `docker-compose.yml`, les configurations `.env` et les clés de sécurité.
agent [#agent]
Crée un nouvel agent de sauvegarde. L'agent est le connecteur qui s'installe sur vos serveurs de base de données.
```bash
portabase agent [OPTIONS] NAME
```
**Arguments**
| Argument | Requis | Description |
| :------- | :----: | :-------------------------------------------- |
| `NAME` | Oui | Le nom du dossier à créer (ex: `prod-db-01`). |
**Options**
| Option | Alias | Description |
| :------------ | :---: | :-------------------------------------------------------------------------------------- |
| `--key ` | `-k` | La **Edge Key** fournie par le Dashboard. Si omise, elle sera demandée interactivement. |
| `--start` | `-s` | Démarrer l'agent immédiatement après la création. |
Si vous lancez simplement `portabase agent my-agent`, le CLI lancera un assistant pour :
1. Demander la clé.
2. Vous proposer d'ajouter des conteneurs de base de données (Postgres/MariaDB) automatiquement.
dashboard [#dashboard]
Crée une instance du Dashboard (l'interface web de gestion).
```bash
portabase dashboard [OPTIONS] NAME
```
**Options**
| Option | Alias | Description | Défaut |
| :------------- | :---: | :----------------------------------------------------- | :------ |
| `--port ` | | Le port d'écoute web de l'interface. | `8887` |
| `--start` | `-s` | Démarrer le dashboard immédiatement après la création. | `False` |
***
Gestion des Bases de Données (db) [#gestion-des-bases-de-données-db]
Le module `db` permet de modifier la configuration `databases.json` d'un agent sans risque d'erreur de syntaxe.
Ces commandes modifient la configuration. Pour qu'elles soient prises en compte, vous devez redémarrer l'agent (`portabase restart <agent>`).
db list [#db-list]
Affiche un tableau récapitulatif des bases de données configurées pour un agent donné.
```bash
portabase db list
```
db add [#db-add]
Lance un assistant interactif pour ajouter une nouvelle connexion à la configuration.
```bash
portabase db add
```
L'assistant vous demandera :
* **Type** : PostgreSQL, MySQL, MariaDB.
* **Host** : L'adresse IP ou le nom d'hôte (utilisez `localhost` pour une DB sur le même serveur).
* **Port** : Le port d'écoute (ex: 5432).
* **Credentials** : Nom d'utilisateur et mot de passe.
db remove [#db-remove]
Supprime une base de données de la configuration via un menu de sélection interactif.
```bash
portabase db remove
```
***
Cycle de Vie (Opérations) [#cycle-de-vie-opérations]
Ces commandes remplacent l'utilisation directe de `docker compose`. Elles doivent cibler le dossier d'un composant (Agent ou Dashboard).
Si vous êtes déjà dans le dossier du composant, vous pouvez utiliser `.` comme chemin. Exemple : `portabase logs .`
start [#start]
Démarre les conteneurs en mode détaché (arrière-plan). Équivalent à `docker compose up -d`.
```bash
portabase start
```
stop [#stop]
Arrête les conteneurs proprement.
```bash
portabase stop
```
restart [#restart]
Redémarre l'ensemble des services. Utile après une modification de configuration (`db add` ou changement dans `.env`).
```bash
portabase restart
```
logs [#logs]
Affiche les logs des conteneurs.
```bash
portabase logs [OPTIONS]
```
**Options**
| Option | Alias | Description |
| :------------------------- | :---: | :----------------------------------------------------------------------------- |
| `--follow` / `--no-follow` | `-f` | Suit les logs en temps réel (activé par défaut). Faites `Ctrl+C` pour quitter. |
uninstall [#uninstall]
Supprime tout le déploiement.
```bash
portabase uninstall [OPTIONS]
```
**Options**
| Option | Alias | Description |
| :-------- | :---: | :------------------------------------------------- |
| `--force` | `-f` | Ne demande pas de confirmation avant de supprimer. |
Cette commande effectue un `docker compose down -v`. Cela **supprime les conteneurs ET les volumes de données** (bases de données locales, configurations).
Cette action est irréversible.
***
Résolution de problèmes fréquents [#résolution-de-problèmes-fréquents]
Le CLI a besoin de communiquer avec Docker. Assurez-vous que Docker est lancé :
* **Mac/Windows** : Lancez Docker Desktop.
* **Linux** : Vérifiez le service (`sudo systemctl status docker`).
Sur Linux, si vous n'avez pas ajouté votre utilisateur au groupe `docker`, vous devrez peut-être lancer les commandes avec `sudo`. *Recommandé : Ajoutez
votre utilisateur au groupe docker pour éviter d'utiliser sudo.*
Si les logs de l'agent indiquent qu'il n'arrive pas à joindre le serveur :
1. Vérifiez que votre **Edge Key** est correcte.
2. Vérifiez que l'URL du dashboard (dans la config de l'agent) est accessible depuis le serveur de l'agent.
# Contribuer
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
Nous adorons les contributions ! Portabase est un projet open-source, et nous accueillons avec plaisir toute aide sur le Tableau de Bord, l'Agent ou le CLI.
Que vous souhaitiez corriger un bug, ajouter une fonctionnalité ou améliorer la documentation, voici comment vous pouvez commencer le développement pour chaque composant.
} description="Contribuez à l'interface web en Next.js. Apprenez à la lancer localement et à gérer la base de données." />
} description="Améliorez l'agent en Python qui gère les sauvegardes et la communication avec le dashboard." />
} description="Aidez à améliorer l'outil en ligne de commande en Go qui orchestre tout l'écosystème." />
***
Flux de travail général [#flux-de-travail-général]
1. **Forkez** le dépôt auquel vous souhaitez contribuer.
2. **Clonez** votre fork localement.
3. **Créez une branche** pour vos modifications.
4. **Commitez** votre travail avec des messages clairs et concis.
5. **Poussez** sur votre fork et **ouvrez une Pull Request**.
Merci de nous aider à rendre Portabase meilleur !
# Bien démarrer
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
Portabase est composé de trois parties principales. Pour commencer, nous vous recommandons d'installer le **Tableau de Bord** en premier, puis votre premier **Agent**.
} description="Configurez l'interface centrale pour gérer toutes vos sauvegardes et vos agents." />
} description="Déployez un agent léger sur vos serveurs de base de données pour gérer les tâches de sauvegarde." />
} description="Apprenez à utiliser la CLI Portabase pour automatiser l'installation et la gestion." />
***
Installation rapide (CLI) [#installation-rapide-cli]
Si vous respectez déjà les prérequis, vous pouvez installer le CLI directement :
```bash
curl -sL https://portabase.io/install | bash
```
# Introduction
import VideoDialog from "../../src/features/common/components/video-dialog";
import { Cards, Card } from "fumadocs-ui/components/card";
import { DatabaseIcon, ShieldCheckIcon, WaypointsIcon, TerminalIcon } from "lucide-react";
Bienvenue sur Portabase [#bienvenue-sur-portabase]
**Portabase** est une solution conçue pour simplifier la **sauvegarde** et la **restauration** de vos bases de données.
Nous savons que gérer des sauvegardes manuellement est risqué et fastidieux. Portabase automatise ce processus en installant des connecteurs intelligents (les **Agents**) sur vos serveurs. Ces agents s'occupent de tout : ils sécurisent vos données et les envoient vers des espaces de stockage prédéfinies, sans que vous ayez besoin de compétences techniques avancées.
Plus besoin d'écrire de scripts complexes. Portabase connecte vos serveurs à un tableau de bord unique pour une gestion sereine de vos données.
***
Fonctionnalités [#fonctionnalités]
Bases de données supportées [#bases-de-données-supportées]
| Base de données | Support | Versions testées |
| :-------------- | :------- | :--------------------------- |
| **PostgreSQL** | ✅ Stable | 12, 13, 14, 15, 16, 17 et 18 |
| **MySQL** | ✅ Stable | 5.7, 8 et 9 |
| **MariaDB** | ✅ Stable | 10 et 11 |
| **MongoDB** | ✅ Stable | 4, 5, 6, 7 et 8 |
Sauvegardes planifiées [#sauvegardes-planifiées]
* **Planification Cron** : Contrôle total sur la fréquence.
* **Déclenchement manuel** : Support des sauvegardes à la demande.
Solutions de stockage [#solutions-de-stockage]
* **Système de fichiers local** : Sauvegardes stockées directement sur le serveur.
* **Compatible S3** : AWS S3, Minio, RustFS, etc ([documentation](/docs/dashboard/advanced/storage/s3)).
* **Google Drive** : à venir.
* **Azure Blob Storage** : à venir.
* **Google Cloud Storage** : à venir.
Notifications intelligentes [#notifications-intelligentes]
* **Multi-canal** : Email, Slack, Discord, Telegram, Ntfy, Gotify, webhooks.
* **Temps réel** : Alertes immédiates sur les succès et les échecs.
* **Politiques personnalisées** : Règles de notification par base de données.
* **Pour les équipes** : Conçu pour les flux DevOps et la gestion d'incidents.
Conçu pour le travail en équipe [#conçu-pour-le-travail-en-équipe]
* **Espaces de travail** : Organisation par projets et organisations.
* **Contrôle d'accès** : Permissions fines basées sur les rôles (RBAC).
* **Rôles** : Membre, Admin, Propriétaire (niveaux système et organisation).
Auto-hébergé & sécurisé [#auto-hébergé--sécurisé]
* **Conteneurisé** : Déploiement Docker pour une installation fiable.
* **Privacy by design** : Tout reste dans votre infrastructure.
* **Open Source** : Licence Apache 2.0 — code entièrement auditable.
Agent Portabase [#agent-portabase]
* **Architecture Headless** : S'exécute localement pour gérer les opérations.
* **Multi-cibles** : Un seul agent pour plusieurs bases de données.
* **Léger** : Empreinte minimale, contrôle maximal.
* **Sécurisé** : Communications chiffrées avec le dashboard.
***
Comment ça marche ? [#comment-ça-marche-]
L'écosystème repose sur trois éléments simples :
} description="L'interface web pour piloter vos sauvegardes, consulter l'historique et restaurer vos données si besoin." />
} description="Le connecteur qui s'installe sur vos serveurs. Il travaille en arrière-plan pour gérer vos bases de données." />
} description="Un outil simple à lancer sur votre ordinateur pour installer et configurer vos agents en quelques secondes." />
# Prérequis
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
Pour utiliser Portabase, vous devez avoir installé les éléments suivants sur votre système :
1. Docker & Docker Compose [#1-docker--docker-compose]
Portabase fonctionne sous forme de conteneurs Docker. Vous devez avoir Docker Engine (version 20.10+) et Docker Compose (version 2.0+) installés.
Ubuntu / Debian / Fedora [#ubuntu--debian--fedora]
Le moyen le plus simple d'installer Docker sur Linux est d'utiliser le script officiel :
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
**Étapes post-installation :**
Pour utiliser Docker sans `sudo`, ajoutez votre utilisateur au groupe `docker` :
```bash
sudo usermod -aG docker $USER
```
*Vous devrez peut-être vous déconnecter et vous reconnecter pour que ce changement soit pris en compte.*
Docker Desktop [#docker-desktop]
Pour macOS, la méthode recommandée est d'installer **Docker Desktop**. Il inclut Docker Engine, la CLI Docker et Docker Compose.
1. Téléchargez l'installateur depuis le [site officiel de Docker](https://docs.docker.com/desktop/install/mac-install/).
2. Glissez-déposez Docker dans votre dossier Applications.
3. Lancez Docker depuis vos Applications.
***
2. Système d'exploitation [#2-système-dexploitation]
* **Linux** : Toute distribution moderne (Ubuntu 22.04+, Debian 11+, CentOS, etc.).
* **macOS** : Catalina 10.15 ou plus récent.
***
3. Configuration réseau [#3-configuration-réseau]
* **Port Local** : Par défaut, le tableau de bord utilise le port `8887`. Assurez-vous qu'il n'est pas utilisé par un autre service.
* **Accès Internet** : Requis pour télécharger les images Docker et pour que l'agent puisse communiquer avec le tableau de bord (si hébergé à distance).
Vous pouvez vérifier si Docker est correctement installé en tapant `docker compose version` dans votre terminal.
***
4. Prérequis pour le développement (optionnel) [#4-prérequis-pour-le-développement-optionnel]
Si vous prévoyez de contribuer à Portabase ou de le compiler à partir des sources, vous aurez besoin des outils suivants :
Agent (Rust) [#agent-rust]
L'agent est développée en Rust pour garantir performance et sécurité.
* **Rust** : Version 1.75+ (dernière version stable recommandée).
* **Gestionnaire de paquets** : `cargo`, inclus avec la chaîne d'outils Rust.
CLI (Python) [#cli-python]
Le CLI est écrit en Python avec Typer.
* **Python** : version 3.12+.
* **Gestionnaire de paquets** : `uv`
Dashboard (TypeScript) [#dashboard-typescript]
Le tableau de bord est une application web moderne construite avec Next.js.
* **Node.js** : Version 20+.
* **Gestionnaire de paquet** : `pnpm` version 9+.
# Roadmap
Si vous n'êtes pas redirigé, [cliquez ici](https://github.com/orgs/Portabase/projects/1).
# Fichier de Configuration
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
L'Agent Portabase a besoin de savoir où se trouvent vos bases de données pour s'y connecter. Cette configuration se fait via un fichier (généralement nommé `databases.json`) qui est monté dans le conteneur Docker.
Vous pouvez gérer ce fichier de deux manières :
1. **Via le CLI** (Commande `portabase db add`) : C'est la méthode recommandée, car elle génère les IDs et valide la syntaxe pour vous.
2. **Manuellement** : Utile pour l'automatisation (Ansible, Terraform) ou si vous préférez éditer vos fichiers à la main.
L'agent supporte deux formats : **JSON** (standard) et **TOML** (plus lisible).
***
Structure du fichier [#structure-du-fichier]
Vous pouvez définir plusieurs bases de données dans un seul fichier. Cela permet à un unique agent de sauvegarder, par exemple, votre environnement de `staging` et de `production` simultanément.
Le format standard utilisé par le CLI.
```json title="databases.json"
{
"databases": [
{
"name": "mon-site-prod",
"database": "ma_base_prod",
"type": "postgresql",
"host": "localhost",
"port": 5432,
"username": "admin_prod",
"password": "super_secure_password",
"generated_id": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "mon-site-dev",
"database": "ma_base_dev",
"type": "mysql",
"host": "192.168.1.50",
"port": 3306,
"username": "root",
"password": "dev_password",
"generated_id": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
```
Un format souvent préféré pour sa lisibilité humaine.
```toml title="databases.toml"
[[databases]]
name = "mon-site-prod"
type = "postgresql"
host = "localhost"
port = 5432
username = "admin_prod"
password = "super_secure_password"
generated_id = "550e8400-e29b-41d4-a716-446655440000"
[[databases]]
name = "mon-site-dev"
type = "mysql"
host = "192.168.1.50"
port = 3306
username = "root"
password = "dev_password"
generated_id = "123e4567-e89b-12d3-a456-426614174000"
```
***
Référence des champs [#référence-des-champs]
Voici la signification de chaque paramètre de configuration :
| Champ | Requis | Description |
| :------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Oui | Le nom de la base de données à sauvegarder (ex: "prod\_api"). |
| `type` | Oui | Le type de moteur de base de données. Valeurs acceptées : `postgresql`, `mysql`, `mariadb` (utilisez `mysql` pour le driver MariaDB). |
| `host` | Oui | L'adresse IP ou le nom d'hôte. Si l'agent est sur le même serveur que la DB, utilisez `localhost` (avec `extra_hosts` dans Docker) ou l'IP locale. |
| `port` | Oui | Le port d'écoute (Défaut : `5432` pour Postgres, `3306` pour MySQL). |
| `username` | Oui | L'utilisateur qui a les droits de lecture (dump) sur la base. |
| `password` | Oui | Le mot de passe de cet utilisateur. |
| `generated_id` | **Oui** | Un identifiant unique universel (UUID v4). Voir ci-dessous. |
***
La règle du generatedId [#la-règle-du-generatedid]
Chaque base de données doit avoir un **ID unique**. C'est cet ID qui permet au Dashboard de reconnaître l'historique des sauvegardes d'une base spécifique, même si vous changez son nom.
Si vous créez ce fichier manuellement, vous **devez** générer vous-même un UUID v4 valide. N'inventez pas une chaîne aléatoire simple.
**Comment générer un UUID valide ?**
* **Via terminal** : `uuidgen` (sur Mac/Linux).
* **Via Python** : `python3 -c "import uuid; print(uuid.uuid4())"`.
* **En ligne** : Utilisez un générateur comme [uuidgenerator.net](https://www.uuidgenerator.net/).
***
Montage dans Docker [#montage-dans-docker]
Si vous modifiez ce fichier manuellement, assurez-vous qu'il est bien monté dans le volume du conteneur Docker de l'agent.
```yaml title="docker-compose.yml"
services:
agent:
# ...
volumes:
# Montage du fichier local vers le chemin interne de l'agent
- ./databases.json:/config/config.json
```
Après toute modification manuelle de ce fichier, vous devez redémarrer l'agent pour que les changements soient pris en compte : `docker compose restart
agent`
# Installation
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
L'**Agent Portabase** est un connecteur léger qui s'exécute sur vos serveurs. Son rôle est de :
1. Sécuriser la connexion avec le Dashboard.
2. Exécuter les tâches de sauvegarde.
3. Gérer les bases de données locales (ou distantes).
Il peut gérer des bases de données existantes (déjà installées sur votre serveur) ou en créer de nouvelles via Docker.
***
Mise à jour à venir, se référer à l’installation via Docker Compose.
Le CLI vous guide pas à pas : il configure l'agent et vous propose d'ajouter immédiatement des bases de données.
Assurez-vous que le CLI est installé en premier. Si ce n’est pas le cas, suivez les instructions [ici](/docs/cli#installation).
Récupérer votre Edge Key [#récupérer-votre-edge-key]
Avant de commencer, rendez-vous sur votre **Dashboard Portabase**, créez un nouvel Agent et copiez sa **Edge Key**.
Créer l'Agent [#créer-lagent]
Lancez la commande sur le serveur où vous souhaitez installer l'agent :
```bash
portabase agent my-agent
```
Le CLI vous demandera votre **Edge Key**. Collez-la et validez.
Configurer les Bases de Données [#configurer-les-bases-de-données]
L'assistant vous demandera si vous souhaitez configurer une base de données. Vous aurez deux choix :
* **Docker (New Local Container)** : Le CLI va ajouter un conteneur PostgreSQL ou MariaDB dans le fichier `docker-compose.yml` de l'agent. C'est idéal pour démarrer un nouveau projet propre.
* **Manual (External/Existing)** : Pour connecter une base de données déjà existante sur votre serveur (ou sur un serveur distant RDS/Managed). Vous devrez fournir l'hôte, le port et les identifiants.
Démarrer [#démarrer]
Si vous n'avez pas démarré l'agent à la fin de l'installation :
```bash
portabase start my-agent
```
Pour une installation manuelle, vous devez créer la structure de fichiers et configurer la connexion réseau pour que l'agent puisse voir vos bases de données locales.
Structure des fichiers [#structure-des-fichiers]
Créez un dossier et préparez les fichiers nécessaires :
```bash
mkdir portabase-agent && cd portabase-agent
touch docker-compose.yml .env databases.json
```
Le fichier `databases.json` doit exister, même vide, avant de lancer le conteneur, sinon l'agent ne pourra pas démarrer correctement.
Initialisez le fichier JSON avec un objet vide :
```bash
echo '{"databases": []}' > databases.json
```
Configuration Docker [#configuration-docker]
Créez le fichier `docker-compose.yml`. Notez l'utilisation de `extra_hosts` qui permet à l'agent d'accéder aux services de l'hôte via `localhost`.
```yaml title="docker-compose.yml"
name: portabase-agent
services:
app:
container_name: portabase-agent
image: portabase/agent:latest
restart: always
volumes:
# Montage du fichier de configuration des DBs
# - ./databases.toml:/config/config.toml
- ./databases.json:/config/config.json
extra_hosts:
# Permet à l'agent de contacter le 'localhost' de la machine hôte
- "localhost:host-gateway"
environment:
LOG: info
# DATABASES_CONFIG_FILE: "config.toml"
TZ: "UTC"
POLLING: 5
APP_ENV: production
DATA_PATH: "/data"
EDGE_KEY: "${EDGE_KEY}"
networks:
- portabase
networks:
portabase:
name: portabase_network
external: true
```
*Note : Vous devez créer le réseau `portabase_network` manuellement si ce n'est pas fait : `docker network create portabase_network`.*
Variables d'environnement [#variables-denvironnement]
Ajoutez votre clé et les configurations optionnelles dans le fichier `.env` :
```bash title=".env"
EDGE_KEY=coller_votre_clé_ici
TZ=UTC
POLLING=5
APP_ENV=production
DATA_PATH=/data
```
| Variable | Description | Défaut |
| :---------- | :------------------------------------------------------------- | :----------- |
| `EDGE_KEY` | La clé unique de votre agent récupérée sur le dashboard. | **Requis** |
| `TZ` | Fuseau horaire de l'agent (ex: `UTC`, `Europe/Paris`). | `UTC` |
| `POLLING` | Fréquence (en secondes) de vérification des nouvelles tâches. | `5` |
| `APP_ENV` | Type d'environnement (`production`, `staging`, `development`). | `production` |
| `DATA_PATH` | Chemin interne où l'agent stocke ses données. | `/data` |
Démarrage [#démarrage]
```bash
docker compose up -d
```
***
[//]: # "## Gestion des Bases de Données"
[//]: #
[//]: # "Pour une liste complète des bases supportées et des configurations détaillées, consultez la section [Bases de Données](./db)."
[//]: #
[//]: # "Une fois l'agent installé, vous devez lui dire quelles bases de données sauvegarder. Le CLI offre un module dédié `db` pour gérer le fichier de configuration `databases.json` sans risque d'erreur de syntaxe."
[//]: #
[//]: # "### Ajouter une base de données"
[//]: #
[//]: # "Cette commande lance un assistant interactif pour ajouter une connexion (Postgres, MySQL, MariaDB)."
[//]: #
[//]: # "```bash"
[//]: # "# Syntaxe : portabase db add "
[//]: # "portabase db add my-agent"
[//]: # "```"
[//]: #
[//]: # "Vous devrez renseigner :"
[//]: #
[//]: # "- **Type** : PostgreSQL, MySQL ou MariaDB."
[//]: # "- **Host** : `localhost` (si sur la même machine) ou une IP."
[//]: # "- **Port** : ex: `5432`."
[//]: # "- **Credentials** : User et Password."
[//]: #
[//]: # "### Lister les bases configurées"
[//]: #
[//]: # "Pour voir quelles bases sont actuellement gérées par cet agent :"
[//]: #
[//]: # "```bash"
[//]: # "portabase db list my-agent"
[//]: # "```"
[//]: #
[//]: # "### Supprimer une base"
[//]: #
[//]: # "```bash"
[//]: # "portabase db remove my-agent"
[//]: # "```"
[//]: #
[//]: # ""
[//]: # " Après avoir ajouté ou supprimé une base de données, il est recommandé de redémarrer l'agent pour que la configuration soit prise en compte immédiatement :"
[//]: # " `portabase restart my-agent`"
[//]: # ""
Développement [#développement]
Pour mettre en place l'agent dans un environnement de développement :
Cloner le dépôt [#cloner-le-dépôt]
```bash
git clone https://github.com/Portabase/agent-rust.git
cd agent-rust
```
Compiler l'agent [#compiler-lagent]
```bash
cargo build
```
Démarrer en mode développement [#démarrer-en-mode-développement]
```bash
docker compose up
```
***
Commandes de cycle de vie [#commandes-de-cycle-de-vie]
Comme pour le dashboard, vous pouvez piloter l'agent avec les commandes standards :
| Commande | Description |
| :--------------------------- | :----------------------------------------------------------------- |
| `portabase start ` | Démarre l'agent. |
| `portabase stop ` | Arrête l'agent. |
| `portabase logs ` | Vérifie si l'agent est bien connecté au dashboard ("Ping server"). |
| `portabase uninstall ` | Supprime l'agent et sa configuration. |
# Installation
import {Tab, Tabs} from "fumadocs-ui/components/tabs";
import {Step, Steps} from "fumadocs-ui/components/steps";
import {Callout} from "fumadocs-ui/components/callout";
Le **Dashboard Portabase** est l'interface centrale qui vous permet de gérer vos agents, configurer vos sauvegardes et visualiser l'état de votre infrastructure.
Vous avez deux méthodes pour l'installer :
1. **Via CLI** : Idéal pour démarrer rapidement en local.
2. **Via Docker Compose** : Recommandé pour les environnements de production avancés ou GitOps.
***
Le CLI s'occupe de tout : il télécharge les templates, génère les secrets de chiffrement (`PROJECT_SECRET`),
configure la base de données interne et lance les conteneurs.
Assurez-vous que le CLI est installé en premier. Si ce n’est pas le cas, suivez les instructions
[ici](/docs/cli#installation).
Créer le Dashboard [#créer-le-dashboard]
Lancez la commande suivante. Cela créera un dossier contenant la configuration.
```bash
# Syntaxe : portabase dashboard
portabase dashboard my-dashboard
```
Par défaut, l'interface sera sur le port **8887**. Vous pouvez le changer avec l'option `--port` :
```bash
portabase dashboard my-dashboard --port 8887
```
Démarrer le service [#démarrer-le-service]
Si vous n'avez pas utilisé l'option `--start` lors de la création, lancez le service manuellement :
```bash
portabase start my-dashboard
```
Accéder à l'interface [#accéder-à-linterface]
Ouvrez votre navigateur : **[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
Si vous ne souhaitez pas utiliser la CLI, vous pouvez déployer la stack avec Docker Run. Cela est recommandé pour les tests, mais pas pour un usage en production, car vous utiliserez la base de données PostgreSQL interne.
Assurez-vous d’avoir déjà installé le moteur Docker.
Variables d'environnement [#variables-denvironnement]
Créez le fichier `.env`. **Attention**, vous devez générer vous-même les mots de passe et secrets.
```bash title=".env"
# --- Configuration App ---
HOST_PORT=8887
PROJECT_NAME=portabase-dashboard
PROJECT_URL=http://localhost:8887
# ⚠️ GÉNÉREZ UN SECRET FORT (ex: openssl rand -hex 32)
# Ce secret sert à chiffrer les communications avec les agents.
PROJECT_SECRET=change_me_please_generate_a_secure_hex_token
```
Démarrer le tableau de bord [#démarrer-le-tableau-de-bord]
Exécutez la commande suivante pour lancer le service Portabase.
```bash
docker run -d \
--name portabase-app-prod \
-p 8887:80 \
--restart unless-stopped \
-e TZ="Europe/Paris" \
--env-file .env \
-v ./portabase-data:/data \
portabase/portabase:latest
```
Démarrage [#démarrage]
```bash
docker compose up -d
```
Accéder à l'interface [#accéder-à-linterface-1]
Ouvrez votre navigateur : **[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
Si vous ne souhaitez pas utiliser le CLI, vous pouvez déployer la stack manuellement.
Structure des fichiers [#structure-des-fichiers]
Créez un dossier et placez-y deux fichiers : `docker-compose.yml` et `.env`.
```bash
mkdir portabase-dashboard && cd portabase-dashboard
```
Configuration Docker [#configuration-docker]
```bash
mkdir portabase-dashboard && cd portabase-dashboard
```
Configuration Docker [#configuration-docker-1]
```yaml title="docker-compose.yml"
name: portabase-dashboard
services:
portabase:
container_name: portabase-app
image: portabase/portabase:latest
restart: always
env_file: .env
environment:
- TZ=Europe/Paris
ports:
- "${HOST_PORT:-8887}:80"
volumes:
- portabase-data:/data
depends_on:
db:
condition: service_healthy
db:
container_name: portabase-pg
image: postgres:17-alpine
restart: always
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres-data:
portabase-data:
```
Variables d'environnement [#variables-denvironnement-1]
Créez le fichier `.env`. **Attention**, vous devez générer vous-même les mots de passe et secrets.
```bash title=".env"
# --- Configuration App ---
HOST_PORT=8887
PROJECT_NAME=portabase-dashboard
PROJECT_URL=http://localhost:8887
# ⚠️ GÉNÉREZ UN SECRET FORT (ex: openssl rand -hex 32)
# Ce secret sert à chiffrer les communications avec les agents.
PROJECT_SECRET=change_me_please_generate_a_secure_hex_token
# --- Configuration Database Interne ---
POSTGRES_DB=portabase
POSTGRES_USER=portabase
POSTGRES_PASSWORD=change_me_secure_db_password
POSTGRES_HOST=db
# URL de connexion (ne pas modifier la structure)
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}?schema=public
```
Démarrage [#démarrage-1]
```bash
docker compose up -d
```
Accéder à l'interface [#accéder-à-linterface-2]
Ouvrez votre navigateur : **[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
***
Développement [#développement]
Si vous souhaitez contribuer au Dashboard ou l'exécuter depuis les sources :
Cloner le dépôt [#cloner-le-dépôt]
```bash
git clone https://github.com/Portabase/portabase.git
cd portabase
```
Installer les dépendances [#installer-les-dépendances]
```bash
pnpm install
```
Configuration de l'environnement [#configuration-de-lenvironnement]
Copiez le fichier d'environnement d'exemple et ajustez les valeurs si nécessaire :
```bash
cp .env.example .env
```
Démarrer en mode développement [#démarrer-en-mode-développement]
```bash
make up
```
Gestion quotidienne (CLI) [#gestion-quotidienne-cli]
Le CLI offre des raccourcis pratiques pour gérer le cycle de vie de votre dashboard sans avoir à taper des commandes Docker complexes.
| Action | Commande | Description |
| :--------------- | :--------------------------- | :----------------------------------------------------------- |
| **Démarrer** | `portabase start ` | Lance les conteneurs en arrière-plan (`up -d`). |
| **Arrêter** | `portabase stop ` | Arrête les conteneurs proprement. |
| **Redémarrer** | `portabase restart ` | Redémarre la stack complète. |
| **Logs** | `portabase logs ` | Affiche les logs en direct (option `-f` activée par défaut). |
| **Désinstaller** | `portabase uninstall ` | ⚠️ Supprime les conteneurs **et** les volumes de données. |
# Bases de Données Supportées
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
L'agent Portabase est conçu pour être agnostique et modulaire. Il supporte nativement plusieurs moteurs de bases de données, que ce soit pour des sauvegardes locales (Docker) ou distantes.
Bases supportées [#bases-supportées]
| Base de données | Clé Type | Support | Versions testées |
| :-------------- | :----------- | :------- | :---------------------------- |
| **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 |
Configuration Globale [#configuration-globale]
Quelle que soit la base de données, la configuration suit le même schéma. Vous devez dire à l'agent comment s'y connecter (hôte, port, identifiants).
C'est la méthode la plus simple. L'agent possède une commande dédiée pour ajouter une configuration sans erreur.
```bash
# Dans le dossier de votre agent
portabase db add .
```
L'assistant vous demandera :
1. Le **type** de base (ex: `postgresql`).
2. Le **nom** (ex: `prod-app`).
3. L'**hôte** (`localhost` ou IP).
4. Les **identifiants**.
Vous pouvez aussi éditer le fichier `databases.json` (ou `.toml`) monté dans le conteneur.
```json title="databases.json"
{
"databases": [
{
"name": "ma-base",
"type": "postgresql",
"host": "db-prod",
"port": 5432,
"username": "admin",
"password": "secret_password",
"generated_id": "uuid-v4-unique"
}
]
}
```
Pour plus de détails sur chaque moteur, consultez les pages dédiées dans cette section.
# MongoDB
L'agent utilisera `mongodump` pour réaliser les sauvegardes et `mongorestore` pour les restaurations.
Configuration avec authentification. [#configuration-avec-authentification]
```json
{
"name": "my-mongo-auth",
"type": "mongodb",
"host": "db-mongodb-auth",
"port": 27017,
"username": "username",
"password": "password",
"database": "testdbauth",
"generated_id": "..."
}
```
Configuration sans authentification. [#configuration-sans-authentification]
```json
{
"name": "my-mongo",
"type": "mongodb",
"host": "db-mongodb",
"port": 27017,
"username": "",
"password": "",
"database": "testdb",
"generated_id": "..."
}
```
Docker Compose [#docker-compose]
```yaml title="docker-compose.yml"
services:
db-mongodb-auth:
container_name: db-mongodb-auth
image: mongo:latest
ports:
- "27082:27017"
environment:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: rootpassword
MONGO_INITDB_DATABASE: testdbauth
command: mongod --auth
networks:
- portabase
volumes:
- mongodb-data-auth:/data/db
healthcheck:
test: [ "CMD", "mongo", "--eval", "db.adminCommand('ping')" ]
interval: 5s
timeout: 5s
retries: 10
db-mongodb:
container_name: db-mongodb
image: mongo:latest
ports:
- "27083:27017"
volumes:
- mongodb-data:/data/db
healthcheck:
test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ]
interval: 5s
timeout: 5s
retries: 10
environment:
MONGO_INITDB_DATABASE: testdb
networks:
- portabase
agent:
image: portabase/agent:latest
# ... agent configuration ...
depends_on:
- db-mongodb
- db-mongodb-auth
networks:
- portabase
networks:
portabase:
external: true
volumes:
mongodb-data:
mongodb-data-auth:
```
Si vous utilisez `localhost` comme hôte (parce que l'agent est sur la machine hôte et non dans Docker, ou via `host-gateway`), assurez-vous que votre base de données écoute bien sur toutes les interfaces (`0.0.0.0`) ou est accessible depuis l'agent.
# MySQL & MariaDB
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
L'agent supporte MySQL et MariaDB via le même driver.
Configuration [#configuration]
Lorsque vous exécutez `portabase db add`, sélectionnez `mysql` ou `mariadb` (c'est le même driver).
**Paramètres spécifiques demandés :**
* **Database Name** : Le nom de la base de données à sauvegarder.
Dans votre fichier `databases.json`, utilisez le type `mysql` pour les deux bases de données.
```json title="databases.json"
{
"name": "mon-site-wp",
"type": "mysql",
"host": "mariadb",
"port": 3306,
"username": "root",
"password": "root_password",
"database": "wordpress",
"generated_id": "..."
}
```
**Paramètres spécifiques :**
* **database** : (Requis) Le nom de la base de données.
Exemple Docker Compose [#exemple-docker-compose]
Exemple avec une image MariaDB.
```yaml title="docker-compose.yml"
services:
mariadb:
image: mariadb:10.6
container_name: my-mariadb
restart: always
environment:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: wordpress
MYSQL_USER: wp_user
MYSQL_PASSWORD: wp_password
volumes:
- db_data:/var/lib/mysql
networks:
- portabase
agent:
image: portabase/agent:latest
# ... configuration de l'agent ...
depends_on:
- mariadb
networks:
- portabase
networks:
portabase:
external: true
volumes:
db_data:
```
Si vous utilisez `localhost` comme hôte (parce que l'agent est sur la machine hôte et non dans Docker, ou via `host-gateway`), assurez-vous que votre base de données écoute bien sur toutes les interfaces (`0.0.0.0`) ou est accessible depuis l'agent.
# PostgreSQL
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Callout } from "fumadocs-ui/components/callout";
PostgreSQL est entièrement supporté par l'agent Portabase. Nous utilisons les outils natifs `pg_dump` pour garantir des sauvegardes cohérentes et fiables.
Configuration [#configuration]
Lorsque vous exécutez `portabase db add`, sélectionnez `postgresql` comme type de base de données.
**Paramètres spécifiques demandés :**
* **Database Name** : Le nom exact de la base de données à sauvegarder (ex: `app_db`). Contrairement à d'autres moteurs, vous devez cibler une base précise.
Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.
```json title="databases.json"
{
"name": "mon-app-postgres",
"type": "postgresql",
"host": "postgres",
"port": 5432,
"username": "postgres",
"password": "mysecretpassword",
"database": "app_db",
"generated_id": "..."
}
```
**Paramètres spécifiques :**
* **database** : (Requis) Le nom exact de la base de données à dumper.
Exemple Docker Compose [#exemple-docker-compose]
Voici comment configurer un service PostgreSQL aux côtés de l'agent.
```yaml title="docker-compose.yml"
services:
postgres:
image: postgres:15-alpine
container_name: my-postgres
restart: always
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: mysecretpassword
POSTGRES_DB: app_db
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- portabase
agent:
image: portabase/agent:latest
# ... configuration de l'agent ...
depends_on:
- postgres
networks:
- portabase
networks:
portabase:
external: true
volumes:
postgres_data:
```
Notez que dans cet exemple, l'hôte (`host`) à renseigner dans la configuration de l'agent sera `postgres` (le nom du service), et non `localhost`.
# Variables d'Environnement
import {Callout} from 'fumadocs-ui/components/callout';
Portabase offre une grande flexibilité grâce aux variables d'environnement. Ces variables permettent de personnaliser le comportement de l'application, la connexion à la base de données, l'authentification et le stockage.
Si vous utilisez Docker Compose, ces variables doivent être définies dans votre fichier `.env` à la racine du
projet.
***
Projet [#projet]
Configuration générale de l'instance Portabase.
| Variable | Type | Défaut | Description |
| :-------------------- | :------- | :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `PROJECT_NAME` | `string` | `Portabase` | Le nom affiché dans l'interface (titre du site). |
| `PROJECT_DESCRIPTION` | `string` | `Manage all your database instances from one place!` | La description ou baseline du projet. |
| `PROJECT_URL` | `string` | `http://localhost:8887` | L'URL publique de votre dashboard (ex: `https://backups.mon-domaine.com`). Important pour les liens générés. |
| `PROJECT_SECRET` | `string` | `None` | **Critique.** Clé secrète utilisée pour chiffrer les données sensibles. Générez-la avec `openssl rand -hex 32`. |
| `PORT` | `string` | `80` | Port interne de l'application. |
| `RETENTION_CRON` | `string` | `0 7 * * *` | Planification de la purge automatique des sauvegarde conformément aux politiques de rétention. |
***
Base de données [#base-de-données]
Configuration de la connexion à la base de données PostgreSQL interne de Portabase.
| Variable | Type | Défaut | Description |
| :------------------ | :------- | :---------------------------------------------------------------------------------------- | :---------------------------------------------------------- |
| `POSTGRES_DB` | `string` | `devdb` | Le nom de la base de données. |
| `POSTGRES_USER` | `string` | `devuser` | L'utilisateur PostgreSQL. |
| `POSTGRES_PASSWORD` | `string` | `changeme` | Le mot de passe de l'utilisateur. |
| `DATABASE_URL` | `string` | `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?schema=public` | La chaîne de connexion complète utilisée par l'application. |
***
Email (SMTP) [#email-smtp]
Configuration pour l'envoi d'emails transactionnels (alertes, invitations).
Si aucune configuration n’est fournie, les fonctionnalités liées aux emails seront limitées (pas de réinitialisation
de mot de passe, pas de vérification de l'email).
| Variable | Type | Défaut | Description |
| :-------------- | :------- | :------ | :------------------------------------------------------------- |
| `SMTP_HOST` | `string` | `None` | L'adresse du serveur SMTP (ex: `smtp.resend.com`). |
| `SMTP_PORT` | `string` | `None` | Le port du serveur SMTP (ex: `587`). |
| `SMTP_USER` | `string` | `None` | Nom d'utilisateur SMTP. |
| `SMTP_PASSWORD` | `string` | `None` | Mot de passe SMTP. |
| `SMTP_FROM` | `string` | `None` | L'adresse email d'expédition (ex: `no-reply@mon-domaine.com`). |
| `SMTP_SECURE` | `string` | `false` | |
***
Authentification Google (OAuth2) [#authentification-google-oauth2]
Pour permettre la connexion via Google.
| Variable | Type | Défaut | Description |
| :------------------- | :------- | :------ | :--------------------------------------------------------- |
| `AUTH_GOOGLE_METHOD` | `string` | `false` | Active (`true`) ou désactive (`false`) le provider Google. |
| `AUTH_GOOGLE_ID` | `string` | `None` | Client ID Google Cloud. |
| `AUTH_GOOGLE_SECRET` | `string` | `None` | Client Secret Google Cloud. |
# Reverse Proxy
import {Tab, Tabs} from "fumadocs-ui/components/tabs";
import {Callout} from "fumadocs-ui/components/callout";
Par défaut, le Dashboard Portabase écoute sur `http://localhost:8887`. Pour le rendre accessible depuis l'extérieur (via un nom de domaine comme `portabase.mon-entreprise.com`) et sécurisé avec HTTPS, il est recommandé d'utiliser un **Reverse Proxy**.
***
Cette configuration suppose que vous avez déjà une instance **Traefik** qui tourne sur votre serveur et qu'elle
surveille le réseau Docker (souvent appelé `traefik_network` ou `proxy`).
Configuration Docker Compose [#configuration-docker-compose]
Modifiez votre fichier `docker-compose.yml` pour :
1. Supprimer l'exposition directe du port.
2. Connecter le conteneur au réseau de Traefik.
3. Ajouter les `labels` Traefik.
```yaml title="docker-compose.yml"
name: portabase-dashboard
services:
portabase:
container_name: portabase-app
image: portabase/portabase:latest
restart: always
env_file: .env
expose:
- 80
volumes:
- portabase-private:/app/private
depends_on:
db:
condition: service_healthy
networks:
- traefik_network # Le réseau où se trouve Traefik
- default # Pour parler à la base de données locale
# Configuration Traefik
labels:
- "traefik.enable=true"
# Remplacez 'portabase' par un nom unique si vous avez plusieurs instances
- "traefik.http.routers.portabase.entrypoints=web,websecure"
- "traefik.http.routers.portabase.rule=Host(`backup.exemple.com`)"
- "traefik.http.routers.portabase.tls.certresolver=myresolver" # Si vous utilisez Let's Encrypt
db:
container_name: portabase-pg
image: postgres:17-alpine
restart: always
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
networks:
- default
volumes:
postgres-data:
portabase-private:
networks:
# Déclaration du réseau externe
traefik_network:
external: true
```
Si vous hébergez **plusieurs dashboards** sur le même serveur Traefik, assurez-vous de changer le nom du
routeur dans les labels :
* Instance 1 : `traefik.http.routers.portabase-prod...`
* Instance 2 : `traefik.http.routers.portabase-dev...`
1. Configuration Portabase [#1-configuration-portabase]
Modifiez votre fichier `docker-compose.yml` pour supprimer l'exposition directe du port.
2. Configuration Nginx [#2-configuration-nginx]
Créez un bloc serveur (vhost) qui proxy les requêtes vers le port interne.
```nginx title="/etc/nginx/sites-available/portabase"
server {
server_name backup.example.com;
location / {
proxy_pass http://portabase:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
🚧 En cours de construction 🚧
***
Variable d'environnement PROJECT_URL [#variable-denvironnement-project_url]
Quelle que soit la méthode choisie (Traefik, Nginx, etc.), n'oubliez pas de mettre à jour votre fichier `.env`. C'est crucial pour que les liens générés dans les emails ou les invitations soient corrects.
```bash title=".env"
# Avant
PROJECT_URL=http://localhost:8887
# Après (Votre domaine public)
PROJECT_URL=https://backup.exemple.com
```
Une fois modifié, redémarrez le dashboard :
```bash
portabase restart .
```
```bash
docker-compose down && docker-compose up -d
```
# Google Drive
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
Par défaut, Portabase stocke les sauvegardes sur le système de fichiers local du serveur.
Pour la production, il est fortement recommandé d'utiliser un stockage externe.
Cela permet de :
* Séparer le stockage et l'applicatif.
* Bénéficier d'une capacité très importante à un coût réduit.
* Sécuriser les données grâce à la fiabilité des stockages objet.
Création d'un client OAuth dans la Google Cloud Console [#création-dun-client-oauth-dans-la-google-cloud-console]
Allez sur la [Google Cloud Console](https://console.cloud.google.com).
Dans le menu latéral, accédez à **API et services > Identifiants**.
Cliquez sur **Créer des identifiants > ID client OAuth**.
Sélectionnez le type **Application web**, puis configurez en fonction de votre nom de domaine :
* **Origines JavaScript autorisées**
* **URL de redirection autorisés**
Cliquez sur **Créer**, puis notez l’**ID client** et le **Code secret du client** générés.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Storage > Channels**, cliquez sur **+ Add Storage Channel** et sélectionnez **Google Drive**.
Entrer les identifiants précédemment générés.
Cliquez sur **Connect Google Drive** pour lancer le flux d’authentification OAuth 2.0.
Cliquez sur **Add Channel** pour finaliser la configuration.
# Stockage Local
import { Callout } from "fumadocs-ui/components/callout";
Par défaut, Portabase est configuré pour utiliser le **Stockage Local**. Cela signifie que les sauvegardes envoyées par vos agents sont stockées sur le disque de la machine où s'exécute le dashboard.
Cette méthode est idéale pour :
* Les tests et la découverte.
* Les petites infrastructures.
* L'utilisation d'un montage réseau (NFS, EFS) déjà attaché au serveur.
Persistance des données [#persistance-des-données]
Si vous utilisez **Docker**, il est crucial d'utiliser un volume pour garantir que vos sauvegardes ne sont pas perdues lors du redémarrage ou de la mise à jour du conteneur.
Le `docker-compose.yml` par défaut fourni par le CLI inclut déjà un volume pour le dossier `private` :
```yaml title="docker-compose.yml"
services:
portabase:
# ...
volumes:
- portabase-private:/app/private
```
Les sauvegardes sont stockées à l'intérieur de `/app/private/backups`.
Utiliser un chemin personnalisé [#utiliser-un-chemin-personnalisé]
Si vous souhaitez stocker les sauvegardes dans un dossier spécifique sur votre machine hôte (ex: un disque dur externe ou une partition dédiée), vous pouvez utiliser un **bind mount** dans votre `docker-compose.yml` :
```yaml title="docker-compose.yml"
services:
portabase:
# ...
volumes:
- /mnt/sauvegardes/portabase:/app/private/backups
```
Assurez-vous que l'utilisateur qui exécute le conteneur Docker (généralement `node` ou `root`) possède les droits d'écriture sur le dossier hôte.
# Stockage objet (S3)
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
Par défaut, Portabase stocke les sauvegardes sur le système de fichiers local du serveur. Pour la production, il est fortement recommandé d'utiliser un stockage externe.
Cela permet de :
* Séparer le stockage et l'applicatif.
* Bénéficier d'une capacité très importante à un coût réduit.
* Sécuriser les données grâce à la fiabilité des stockages objet.
***
Configuration du stockage (si auto-hébergé) [#configuration-du-stockage-si-auto-hébergé]
Cette configuration ajoute une instance **MinIO** directement dans votre stack Docker Compose, derrière Traefik.
Modifiez votre `docker-compose.yml` pour ajouter le service `s3`.
MinIO utilise deux ports :
* **9000** : L'API S3 (C'est ce que Portabase utilise).
* **9001** : La Console Web (Interface d'administration pour vous).
```yaml title="docker-compose.yml"
name: portabase-stack
services:
portabase:
image: portabase/portabase:latest
container_name: portabase-app
env_file: .env
volumes:
- portabase-private:/app/private
depends_on:
db:
condition: service_healthy
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
- "traefik.http.routers.portabase.rule=Host(`dashboard.exemple.com`)"
- "traefik.http.routers.portabase.entrypoints=websecure"
- "traefik.http.routers.portabase.tls.certresolver=myresolver"
# ... (Service DB standard) ...
s3:
image: docker.io/bitnami/minio:latest
container_name: portabase-minio
expose:
- 9000
- 9001
volumes:
- minio-data:/data
environment:
- MINIO_ROOT_USER=${S3_ACCESS_KEY}
- MINIO_ROOT_PASSWORD=${S3_SECRET_KEY}
# Crée automatiquement le bucket au démarrage
- MINIO_DEFAULT_BUCKETS=${S3_BUCKET_NAME}
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
# Routeur 1 : API S3 (Port 9000)
- "traefik.http.routers.api-s3.rule=Host(`api.s3.exemple.com`)"
- "traefik.http.routers.api-s3.entrypoints=websecure"
- "traefik.http.routers.api-s3.tls.certresolver=myresolver"
- "traefik.http.services.api-s3.loadbalancer.server.port=9000"
# Routeur 2 : Console Web (Port 9001)
- "traefik.http.routers.webui-s3.rule=Host(`console.s3.exemple.com`)"
- "traefik.http.routers.webui-s3.entrypoints=websecure"
- "traefik.http.routers.webui-s3.tls.certresolver=myresolver"
- "traefik.http.services.webui-s3.loadbalancer.server.port=9001"
volumes:
portabase-private:
postgres-data:
minio-data: # Volume persistant pour MinIO
networks:
traefik_network:
external: true
```
Vous pouvez lancer une instance **RustFS** à nœud unique en utilisant Docker Compose.
```yaml title="docker-compose.yml"
name: portabase-stack
services:
# ... autres services (portabase, db) ...
rustfs:
image: rustfs/rustfs:latest
container_name: portabase-rustfs
expose:
- 9000
- 9001
environment:
- RUSTFS_ADDRESS=0.0.0.0:9000
- RUSTFS_CONSOLE_ADDRESS=0.0.0.0:9001
- RUSTFS_CONSOLE_ENABLE=true
- RUSTFS_ACCESS_KEY=${S3_ACCESS_KEY}
- RUSTFS_SECRET_KEY=${S3_SECRET_KEY}
volumes:
- rustfs-data:/data
networks:
- traefik_network
- default
labels:
- "traefik.enable=true"
# Route 1 : API S3
- "traefik.http.routers.rustfs-api.rule=Host(`s3.exemple.com`)"
- "traefik.http.routers.rustfs-api.entrypoints=websecure"
- "traefik.http.routers.rustfs-api.tls.certresolver=myresolver"
- "traefik.http.services.rustfs-api.loadbalancer.server.port=9000"
# Route 2 : Console Web
- "traefik.http.routers.rustfs-console.rule=Host(`console.s3.exemple.com`)"
- "traefik.http.routers.rustfs-console.entrypoints=websecure"
- "traefik.http.routers.rustfs-console.tls.certresolver=myresolver"
- "traefik.http.services.rustfs-console.loadbalancer.server.port=9001"
volumes:
rustfs-data:
networks:
traefik_network:
external: true
```
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Storage > Channels**, cliquez sur **+ Add Storage Channel** et sélectionnez **S3**.
Entrer les identifiants précédemment générés.
Cliquez sur **Add Channel** pour finaliser la configuration.
***
Vérification [#vérification]
Pour vérifier que la connexion fonctionne :
1. Redémarrez votre dashboard :
```bash
portabase restart .
```
```bash
docker-compose down && docker-compose up -d
```
2. Connectez-vous à l'interface web.
3. Lancez une sauvegarde manuelle sur un agent.
4. Si la sauvegarde réussit, vérifiez dans votre bucket S3 (ou via la console MinIO `console.s3.exemple.com`) que le fichier est bien présent.
# Discord
import Image from "next/image";
import { Step, Steps } from "fumadocs-ui/components/steps";
Les notifications Discord utilisent le système de Webhooks natif de la plateforme pour poster des messages dans un canal spécifique.
Configuration du serveur Discord [#configuration-du-serveur-discord]
Dans Discord, allez dans les **Paramètres du serveur** > **Intégrations** > **Webhooks**.
Créez un nouveau Webhook et copiez son **URL**.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez **Discord**.
Saisissez l'URL du webhook Discord obtenue précédemment (ex. : `https://discord.com/api/webhooks/...`) et cliquez sur **Add Channel**.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Vérifiez qu'un message de test apparaît bien dans le canal Discord choisi.
# Email (SMTP)
import {Callout} from "fumadocs-ui/components/callout";
import {Step, Steps} from "fumadocs-ui/components/steps";
import Image from "next/image";
Les notifications par email sont le moyen le plus standard de rester informé de l'état de vos sauvegardes. Pour les utiliser, vous devez fournir les identifiants de votre propre serveur SMTP.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez **Email**.
* **Hôte SMTP** : L'adresse de votre serveur mail (ex: `smtp.gmail.com` ou `smtp.sendgrid.net`).
* **Port SMTP** : Généralement `587` (TLS) ou `465` (SSL).
* **Utilisateur** : Le nom d'utilisateur de votre compte mail.
* **Mot de passe** : Le mot de passe de votre compte ou un mot de passe d'application.
* **Adresse d'expédition** : L'adresse email qui apparaîtra comme expéditeur (ex: `noreply@votredomaine.com`).
Si vous utilisez Gmail, vous devrez probablement générer un **Mot de passe d'application** dans les
paramètres de sécurité de votre compte Google au lieu d'utiliser votre mot de passe principal.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Portabase
tentera d'envoyer un email de test à l'adresse email de l'administrateur configurée.
# Gotify
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
[Gotify](https://gotify.net) est un serveur simple pour envoyer et recevoir des messages en temps réel (WebSocket).
Configuration sur votre instance Gotify [#configuration-sur-votre-instance-gotify]
Connectez-vous à votre instance Gotify.
Créez une nouvelle **Application** (ex: "Portabase").
Copiez le **Token** généré pour cette application.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez **Gotify**.
Entrer les informations suivantes :
* **Serveur URL** : L'URL complète de votre instance Gotify (ex: `https://gotify.mondomaine.com`).
* **App Token** : Le jeton de l'application que vous venez de créer.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Le message devrait apparaître instantanément dans votre interface Gotify ou sur votre mobile.
# Ntfy
import { Callout } from "fumadocs-ui/components/callout";
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
[Ntfy](https://ntfy.sh) est un service de notification HTTP simple. Vous pouvez utiliser le serveur public officiel ou votre propre instance auto-hébergée.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez
**ntfy.sh**.
Entrer les informations suivantes :
* **Serveur URL** : L'adresse de votre serveur. Par défaut : `https://ntfy.sh`.
* **Topic** : Le nom du sujet (topic) auquel s'abonner (ex: `mon-projet-alertes`).
* **Token** (Optionnel) : Si votre sujet ou serveur est protégé par authentification.
Si vous utilisez le serveur public `ntfy.sh`, sachez que les topics sont publics s'ils ne sont pas protégés. Choisissez un nom complexe ou configurez des droits d'accès.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Le message devrait apparaître instantanément dans votre interface Ntfy ou sur votre mobile.
# Slack
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
Portabase vous permet d'envoyer des notifications en temps réel vers un canal Slack lorsqu'un évènement (sauvegarde, restauration) réussit ou échoue.
Configuration sur l'API Slack [#configuration-sur-lapi-slack]
Créer une App Slack [#créer-une-app-slack]
1. Allez sur [api.slack.com/apps](https://api.slack.com/apps).
2. Cliquez sur **Create New App** et choisissez **From scratch**.
3. Nommez votre application (ex: "Portabase Bot") et sélectionnez votre espace de travail.
Activer les Webhooks Entrants [#activer-les-webhooks-entrants]
1. Dans le menu de gauche, cliquez sur **Incoming Webhooks**.
2. Basculez l'interrupteur sur **On**.
3. Cliquez sur le bouton **Add New Webhook to Workspace** en bas de page.
4. Sélectionnez le canal où les notifications doivent apparaître et cliquez sur **Allow**.
Copier l'URL du Webhook [#copier-lurl-du-webhook]
Vous verrez une URL ressemblant à ceci :
`https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`
Copiez cette URL.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez **Slack**.
Saisissez l'URL du webhook Slack obtenue précédemment `https://hooks.slack.com/services/...` et cliquez sur **Add Channel**.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Vérifiez qu'un message de test apparaît bien dans le canal Slack choisi.
# Telegram
import {Step, Steps} from "fumadocs-ui/components/steps";
import Image from "next/image";
Pour recevoir des notifications sur Telegram, vous devez créer un bot et obtenir son jeton d'accès ainsi que l'identifiant du chat destinataire.
Configuration du Bot Telegram [#configuration-du-bot-telegram]
Contactez [@BotFather](https://t.me/botfather) sur Telegram pour créer un nouveau bot et obtenir votre
**Token** (ex: `123456:ABC-DEF1234...`).
Démarrez une conversation avec votre bot (cliquez sur "Start").
Récupérez votre **Chat ID** (vous pouvez utiliser un bot comme `@userinfobot` pour le trouver).
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez
**Telegram**.
Entrer les informations suivantes :
* **Bot Token** : Le jeton fourni par BotFather.
* **Chat ID** : L'identifiant numérique de la conversation ou du groupe.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Votre bot
devrait vous envoyer un message de test immédiatement.
# Webhook
import { Step, Steps } from "fumadocs-ui/components/steps";
import Image from "next/image";
Les notifications par Webhook vous permettent d'envoyer des requêtes HTTP (POST) vers l'URL de votre choix lorsqu'un événement survient. C'est la solution idéale pour connecter Portabase à des outils d'automatisation ou des scripts personnalisés.
Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]
Allez dans **Notifications > Channels**, cliquez sur **+ Add Notification Channel** et sélectionnez **Webhook**.
Entrer les informations suivantes :
* **URL du Webhook** : L'adresse qui recevra la requête POST.
* **Header** (optionnel) : En-tête HTTP permettant de sécuriser ou d’identifier vos requêtes (par exemple, `Authorization` pour fournir un token d’authentification). Par défaut, Portabase envoie `X-Webhook-Secret`.
Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Vérifiez qu'un message de test est bien reçu.