# CLI Reference 



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:

<Steps>
  <Step>
    ### Clone the repository [#clone-the-repository]

    ```bash
    git clone https://github.com/Portabase/cli.git
    cd cli
    ```
  </Step>

  <Step>
    ### Install dependencies [#install-dependencies]

    ```bash
    uv sync
    ```
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

<Callout type="tip">
  You can also run commands directly without installing the package by using:

  ```bash
  uv run main.py [COMMAND]
  ```
</Callout>

## 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                                                                                 | Default      |
| :------------------ | :---: | :------------------------------------------------------------------------------------------ | :----------- |
| `--key <str>`       |  `-k` | The **Edge Key** provided by the Dashboard. If omitted, it will be requested interactively. | `None`       |
| `--tz <str>`        |       | Timezone for the agent.                                                                     | `UTC`        |
| `--polling <int>`   |       | Polling frequency in seconds.                                                               | `5`          |
| `--env <str>`       |       | Application environment (e.g., `production`, `development`).                                | `production` |
| `--data-path <str>` |       | Internal data path within the container.                                                    | `/data`      |
| `--start`           |  `-s` | Start the agent immediately after creation.                                                 | `False`      |

<Callout type="info" title="Interactive Assistant">
  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.
</Callout>

### `dashboard` [#dashboard]

Creates a Dashboard instance (the web management interface).

```bash
portabase dashboard [OPTIONS] NAME
```

**Options**

| Option         | Alias | Description                                     | Default |
| :------------- | :---: | :---------------------------------------------- | :------ |
| `--port <int>` |       | 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.

<Callout type="warn">
  These commands modify the configuration. For them to take effect, you must restart the agent (`portabase restart <AGENT_PATH>`).
</Callout>

### `db list` [#db-list]

Displays a summary table of databases configured for a given agent.

```bash
portabase db list <AGENT_PATH>
```

### `db add` [#db-add]

Launches an interactive assistant to add a new connection to the configuration.

```bash
portabase db add <AGENT_PATH>
```

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 <AGENT_PATH>
```

***

## Lifecycle (Operations) [#lifecycle-operations]

These commands replace direct use of `docker compose`. They must target the folder of a component (Agent or Dashboard).

<Callout type="tip" title="Productivity Tip">
  If you are already in the component folder, you can use `.` as the path. Example: `portabase logs .`
</Callout>

### `start` [#start]

Starts containers in detached mode (background). Equivalent to `docker compose up -d`.

```bash
portabase start <PATH>
```

### `stop` [#stop]

Stops containers cleanly.

```bash
portabase stop <PATH>
```

### `restart` [#restart]

Restarts all services. Useful after a configuration change (`db add` or modification in `.env`).

```bash
portabase restart <PATH>
```

### `logs` [#logs]

Displays container logs.

```bash
portabase logs [OPTIONS] <PATH>
```

**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] <PATH>
```

**Options**

| Option    | Alias | Description                                    |
| :-------- | :---: | :--------------------------------------------- |
| `--force` |  `-f` | Does not ask for confirmation before deleting. |

<Callout type="danger">
  This command performs a `docker compose down -v`. This **removes containers AND data volumes** (local databases, configurations).
  This action is irreversible.
</Callout>

***

## Backup Decryption (`decrypt`) [#backup-decryption-decrypt]

Decrypts Portabase `.enc` backup files (AES-256-GCM) and restores the original archive. Works on a single file or on a whole folder of `.enc` files.

```bash
portabase decrypt [OPTIONS] INPUT_PATH [OUTPUT_PATH]
```

**Arguments**

| Argument      | Required | Description                                                                        |
| :------------ | :------: | :--------------------------------------------------------------------------------- |
| `INPUT_PATH`  |    Yes   | A `.enc` file, or a folder containing `.enc` files (top level; all are decrypted). |
| `OUTPUT_PATH` |    No    | Output file or folder, matching the input type. Defaults to the input's directory. |

**Options**

| Option         | Alias | Description                                                      | Default            |
| :------------- | :---: | :--------------------------------------------------------------- | :----------------- |
| `--key <path>` |  `-k` | Path to the master key file (raw 32-byte or Base64 AES-256 key). | `./master_key.bin` |

Decrypt a single file:

```bash
portabase decrypt backup.tar.gz.enc backup.tar.gz --key master_key.bin
```

Decrypt every `.enc` in a folder into another folder:

```bash
portabase decrypt ./backups ./restored --key master_key.bin
```

Omit the output to write next to the input, and omit `--key` to use `master_key.bin` from the current directory:

```bash
portabase decrypt backup.tar.gz.enc
```

<Callout type="info" title="Master key">
  The master key is the same 32-byte AES-256 key used for encryption. Download it from the dashboard under **Settings → Storage**. When `--key` is not provided, the CLI looks for `master_key.bin` in the current directory.
</Callout>

<Callout type="tip" title="Folder mode is resilient">
  When decrypting a folder, each file is handled independently: one corrupt or wrong-key file does not stop the batch. A summary lists which files succeeded and which failed (with the reason), and the command exits with a non-zero code if any failed.
</Callout>

<Callout type="info" title="Large backups">
  Decryption is fully streaming: files are processed chunk by chunk, so memory stays bounded (tens of MB) even for multi-gigabyte (>2 GB) backups. The output is written atomically, so a failure never leaves a partial file behind.
</Callout>

## Maintenance and Troubleshooting [#maintenance-and-troubleshooting]

Manage the global behavior and settings of the Portabase CLI.

### `config channel` [#config-channel]

Changes the update channel to switch between stable and beta versions.

```bash
portabase config channel <stable|beta>
```

### `config show` [#config-show]

Displays the current CLI configuration, including the active update channel.

```bash
portabase config show
```

### `update` [#update]

Updates the CLI to the latest available version. This command checks for updates on the official repository and applies security patches or new features.

```bash
portabase update
```

***

## Common Troubleshooting [#common-troubleshooting]

<Accordions>
  <Accordion title="portabase: command not found">
    The CLI is installed in `/usr/local/bin`, but some shells (especially `root` shells on minimal distributions, or non-login shells) do not include that directory in their `PATH`.

    First, check that the binary is really there:

    ```bash
    ls -l /usr/local/bin/portabase
    ```

    If the file exists, add the directory to your `PATH` and reload your shell configuration:

    ```bash
    echo 'export PATH="/usr/local/sbin:/usr/local/bin:$PATH"' >> /root/.bashrc
    source /root/.bashrc
    ```

    <Callout type="info" title="Adapt to your user and your shell">
      Replace `/root/.bashrc` with the profile file of the user actually running the command:

      * **bash (non-root user)**: `~/.bashrc`
      * **zsh**: `~/.zshrc`
      * **fish**: `fish_add_path /usr/local/bin`

      Then reload it with `source <file>` (or open a new terminal).
    </Callout>

    Check that it worked:

    ```bash
    which portabase
    portabase --version
    ```

    If the binary is missing from `/usr/local/bin`, the installation did not complete: run the install script again and read its output.
  </Accordion>

  <Accordion title="Docker Daemon not running">
    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`).
  </Accordion>

  <Accordion title="Permission Denied">
    On Linux, if you haven't added your user to the `docker` group, you may need to run commands with `sudo`. &#x2A;Recommended: Add
    your user to the docker group to avoid using sudo.*
  </Accordion>

  <Accordion title="Ping server failed (Agent Logs)">
    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.
  </Accordion>
</Accordions>


# Contributing 



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.

<Cards>
  <Card href="#dashboard-development" title="Dashboard Development" icon="<DatabaseIcon />" description="Contribute to the Next.js web interface. Learn how to run it locally and manage the database." />

  <Card href="#agent-development" title="Agent Development" icon="<WaypointsIcon />" description="Improve the Rust-based agent that handles backups and communication with the dashboard." />

  <Card href="/docs/cli#development" title="CLI Development" icon="<TerminalIcon />" description="Help enhance the Python command-line tool that orchestrates the entire ecosystem." />

  <Card href="https://github.com/Portabase/e2e-tests" title="E2E Tests" icon="<FlaskConicalIcon />" description="Maintain the shared end-to-end test suite, reused to validate both the Dashboard and the Agent." />
</Cards>

***

### Dashboard development [#dashboard-development]

Run the Dashboard from source:

<Steps>
  <Step>
    #### Clone the repository [#clone-the-repository]

    ```bash
    git clone https://github.com/Portabase/portabase.git
    cd portabase
    ```
  </Step>

  <Step>
    #### Install dependencies [#install-dependencies]

    ```bash
    pnpm install
    ```
  </Step>

  <Step>
    #### Environment configuration [#environment-configuration]

    Copy the example environment file and adjust values if necessary:

    ```bash
    cp .env.example .env
    ```
  </Step>

  <Step>
    #### Start in development mode [#start-in-development-mode]

    ```bash
    make up
    ```
  </Step>
</Steps>

### Agent development [#agent-development]

Set up the agent in a development environment:

<Steps>
  <Step>
    #### Clone the repository [#clone-the-repository-1]

    ```bash
    git clone https://github.com/Portabase/agent.git
    cd agent
    ```
  </Step>

  <Step>
    #### Build the agent [#build-the-agent]

    ```bash
    cargo build
    ```
  </Step>

  <Step>
    #### Start in development mode [#start-in-development-mode-1]

    ```bash
    docker compose up
    ```
  </Step>
</Steps>

See the [development requirements](/docs/requirements#4-development-requirements-optional) for the toolchain versions.

***

### 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. **Run the tests** and make sure they pass, including the [end-to-end tests](https://github.com/Portabase/e2e-tests) where relevant (see [Testing](#testing) below).
6. **Push** to your fork and **open a Pull Request**.

Thank you for helping make Portabase better!

***

### Testing [#testing]

Portabase ships with an automated test pipeline that runs on every pull request.

The **end-to-end (E2E) tests** are maintained in a dedicated repository, [`Portabase/e2e-tests`](https://github.com/Portabase/e2e-tests), rather than inside the main project repositories. Keeping them separate makes them easier to maintain and lets us reuse the same suite for agent-side testing.

<Cards>
  <Card href="https://github.com/Portabase/e2e-tests" title="Dashboard" icon="<DatabaseIcon />" description="Currently relies exclusively on end-to-end tests. Unit tests are not yet included." />

  <Card href="https://github.com/Portabase/e2e-tests" title="Agent" icon="<WaypointsIcon />" description="Includes unit tests run on every pull request with a code coverage report, alongside the end-to-end tests." />
</Cards>

### Useful Development Commands [#useful-development-commands]

To make managing the development environment easier, `make` commands are available to handle authentication provider data.

<Cards>
  <Card title="Seed authentication test data">
    <p>
      This command loads test data for Keycloak and Pocket ID. It is an alias for 

      `make seed-keycloak`

       and 

      `make seed-pocket`

      .
    </p>

    ```bash
    make seed-auth
    ```
  </Card>

  <Card title="Seed Keycloak test data">
    <p>
      Resets and loads test data for Keycloak from 

      `seeds/keycloak/*.json`

      .
    </p>

    ```bash
    make seed-keycloak
    ```
  </Card>

  <Card title="Seed Pocket ID test data">
    <p>
      Resets and loads test data for Pocket ID from 

      `seeds/pocket-id/portabase.zip`

      .
    </p>

    ```bash
    make seed-pocket
    ```
  </Card>

  <Card title="Export Keycloak data">
    <p>
      Exports Keycloak configuration and users to 

      `seeds/keycloak/`

      .
    </p>

    ```bash
    make export-keycloak
    ```
  </Card>

  <Card title="Export Pocket ID data">
    <p>
      Exports Pocket ID data to 

      `seeds/pocket-id/portabase.zip`

      .
    </p>

    ```bash
    make export-pocket
    ```
  </Card>

  <Card title="Generate Pocket ID access token">
    <p>
      Generates a one-time access token for the Pocket ID administrator.
    </p>

    ```bash
    make pocket-token
    ```
  </Card>
</Cards>


# FAQ 



<Accordions type="single">
  {docsFaqEntries.en.map((item) => (
          <Accordion key={item.question} title={item.question}>
              {item.answer}
          </Accordion>
      ))}
</Accordions>


# Introduction 



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

<Callout type="info" title="Simplicity First">
  No more writing complex scripts. Portabase connects your servers to a unique dashboard for serene data management.
</Callout>

<div className="mt-8 flex justify-center">
  <div className="w-full max-w-2xl aspect-video">
    <VideoDialog animationStyle="top-in-bottom-out" videoSrc="https://www.youtube.com/embed/nSTzT27GgAg" thumbnailSrc="/static/img/thumbnail-portabase-video.png" thumbnailAlt="Portabase Video - Youtube" />
  </div>
</div>

***

## Architecture [#architecture]

The central server provides the graphical interface and acts as the control plane: it allows users to declare agents, configure backups, launch restores, and connect third-party systems such as storage backends and notification services.

The agent is deployed as close as possible to the databases: it executes backup and restore tasks.

This architectural choice is important: the central server never contacts the agents directly. Therefore, there is no need to open inbound ports into the environments where the databases reside. Instead, the agents periodically contact the central server.

This approach reduces the network exposure surface and limits the consequences of a compromise of the central server.

<div className="align-middle justify-items-center bg-white pl-4 pr-8 py-1 rounded-2xl">
  <Image src="/static/architecture.png" alt="Google Drive configuration" width="1280" height="1080" className="w-256" />
</div>

## Features [#features]

### Supported databases [#supported-databases]

| Database          | Support  | Tested versions              | Restore |
| :---------------- | :------- | :--------------------------- | :------ |
| **PostgreSQL**    | ✅ Stable | 12, 13, 14, 15, 16, 17 et 18 | Yes     |
| **MySQL**         | ✅ Stable | 5.7, 8 et 9                  | Yes     |
| **MariaDB**       | ✅ Stable | 10 et 11                     | Yes     |
| **MongoDB**       | ✅ Stable | 4, 5, 6, 7 et 8              | Yes     |
| **SQLite**        | ✅ Stable | 3.x                          | Yes     |
| **Redis**         | ✅ Stable | 2.8+                         | No      |
| **Valkey**        | ✅ Stable | 7.2+                         | No      |
| **Firebird**      | ✅ Stable | 3.0, 4.0, 5.0                | Yes     |
| **MSSQL Server**  | ✅ Stable | -                            | Yes     |
| **Docker Volume** | ✅ Stable | Docker Engine 20.10+         | Yes     |

### 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.
* ✅ **Google Drive**
* ✅ **Azure Blob Storage**
* ✅ **Google Cloud Storage**

<Callout type="info" title="Important Note">
   Portabase allows sending the same backup to 

  **multiple destinations simultaneously**

  . You can combine local storage, private cloud, and S3 services, ensuring maximum redundancy and enhanced security in case one storage point fails. 
</Callout>

### 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.
* **Advanced Encryption**: Backups protected with AES-GCM to ensure data confidentiality and integrity.

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

***

## How it works? [#how-it-works]

The ecosystem relies on three simple elements:

<Cards>
  <Card href="/docs/installation" title="The Dashboard" icon="<DatabaseIcon />" description="The web interface to control your backups, view history, and restore your data if needed." />

  <Card href="/docs/installation#agent-coverage" title="The Agent" icon="<WaypointsIcon />" description="The connector that installs on your servers. It works in the background to protect your databases." />

  <Card href="/docs/cli" title="The Assistant (CLI)" icon="<TerminalIcon />" description="A simple tool to run on your computer to install and configure your agents in seconds." />
</Cards>


# Requirements 



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.

<Tabs items="[&#x22;Linux&#x22;, &#x22;macOS&#x22;]">
  <Tab value="Linux">
    ### 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.*
  </Tab>

  <Tab value="macOS">
    ### 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.
  </Tab>
</Tabs>

***

## 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).

<Callout type="info">
  You can check if Docker is correctly installed by running `docker compose version` in your terminal.
</Callout>

***

## 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+.


# Configuration File 



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.

<Tabs items="[&#x22;JSON (Default)&#x22;, &#x22;TOML&#x22;]">
  <Tab value="JSON (Default)">
    Standard format used by the CLI.

    ```json title="databases.json"
    {
      "databases": [
        {
          "name": "my-site-prod (readable name)",
          "database": "devdb",
          "type": "postgresql",
          "host": "localhost",
          "port": 5432,
          "username": "admin_prod",
          "password": "super_secure_password",
          "generated_id": "550e8400-e29b-41d4-a716-446655440000"
        },
        {
          "name": "my-site-dev (readable name)",
          "database": "mariadb",
          "type": "mysql",
          "host": "192.168.1.50",
          "port": 3306,
          "username": "root",
          "password": "dev_password",
          "generated_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
    ```
  </Tab>

  <Tab value="TOML">
    A format often preferred for its human readability.

    ```toml title="databases.toml"
    [[databases]]
    name = "my-site-prod"
    database = "devdb"
    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"
    database = "mariadb"
    type = "mysql"
    host = "192.168.1.50"
    port = 3306
    username = "root"
    password = "dev_password"
    generated_id = "123e4567-e89b-12d3-a456-426614174000"
    ```
  </Tab>
</Tabs>

***

## Field reference [#field-reference]

Here is the meaning of each configuration parameter:

| Field          |        Required        | Description                                                                                                            |
| :------------- | :--------------------: | :--------------------------------------------------------------------------------------------------------------------- |
| `name`         |           Yes          | The Readable name.                                                                                                     |
| `database`     | Depends on the engine. | The database to back up (e.g. "prod\_api").                                                                            |
| `type`         |           Yes          | Engine type: `postgresql`,`sqlite`, `mysql`, `mariadb` (use `mysql` for MariaDB).                                      |
| `host`         | Depends on the engine. | Host IP or name. If the agent runs on the same server, use `localhost` (with `extra_hosts` in Docker) or the local IP. |
| `port`         | Depends on the engine. | Listening port (`5432` for Postgres, `3306` for MySQL).                                                                |
| `username`     | Depends on the engine. | User with read/dump permissions.                                                                                       |
| `password`     | Depends on the engine. | 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.

<Callout type="warn" title="Attention">
  If you create this file manually, you **must** generate a valid UUID. Do not invent a simple random string.
</Callout>

<UUIDGenerator />

***

## 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
```

<Callout type="info">
  After any manual change, restart the agent so it picks up the new configuration:
  `docker compose restart agent`
</Callout>


# Environment Variables 



Portabase provides flexibility through environment variables. These let you customize application behavior, database connection, authentication and storage.

<Callout type="info">
  If you use Docker Compose, set these variables in your `.env` file at the root of the project.
</Callout>

***

| Variable           | Type     | Optional | Default | Description                                                                                                                                                                                                                    |
| :----------------- | :------- | :------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EDGE_KEY`         | `string` | No       | `None`  | Your agent's unique key from the dashboard.                                                                                                                                                                                    |
| `TZ`               | `string` | Yes      | `UTC`   | Timezone for the agent (e.g. `UTC`, `Europe/Paris`).                                                                                                                                                                           |
| `POLLING`          | `number` | Yes      | `5`     | Frequency (in seconds) to check for new tasks.                                                                                                                                                                                 |
| `DATA_PATH`        | `string` | Yes      | `/data` | Internal path where the agent stores its data.                                                                                                                                                                                 |
| `TMPDIR`           | `string` | Yes      | `/tmp`  | Directory where the agent builds the temporary backup/restore archive. Point it at a disk with enough free space for your largest volume (see [Docker Volume](/docs/agent/db/docker-volume#temporary-storage-and-disk-space)). |
| `RETRY_ATTEMPTS`   | `number` | Yes      | `3`     | Total attempts (not retries after the first) for a database dump, each storage upload, and the restore download. `3` means one initial try plus two retries. Must be between 3 and 5.                                          |
| `RETRY_BACKOFF_MS` | `number` | Yes      | `1000`  | Base delay between retry attempts. Doubles each attempt, with equal jitter and a 30s ceiling per wait, so the default spends at most \~3s sleeping per seam. Must be between 100 and 30000.                                    |
| `SSL_CERT_FILE`    | `string` | Yes      | `None`  | Path to a CA bundle used for the agent's outgoing TLS connections. Needed when the agent must trust an internal certificate authority (see below).                                                                             |

***

<Callout type="warn" title="Internal certificate authority: update-ca-certificates has no effect">
  The agent is written in Rust and uses `rustls`, which does **not** read the system CA directory. Dropping your
  certificate into `/usr/local/share/ca-certificates/` and running `update-ca-certificates` satisfies tools such as
  `curl`, but the agent keeps failing with `InvalidCertificate(UnknownIssuer)`.

  Mount a CA bundle and point `SSL_CERT_FILE` at it instead:

  ```yaml title="docker-compose.yml"
  volumes:
    - ./ca-bundle.crt:/etc/ssl/certs/portabase-ca-bundle.crt:ro
  environment:
    - SSL_CERT_FILE=/etc/ssl/certs/portabase-ca-bundle.crt
  ```

  `SSL_CERT_FILE` **replaces** the default root store, it does not add to it. The bundle must therefore contain the
  standard Mozilla root certificates concatenated with your internal CA — otherwise the agent stops trusting public
  hosts, such as your S3 storage.
</Callout>


# Overview 

Database backup tools vary significantly in architecture and operational scope. Some solutions focus on a single database engine and rely primarily on command-line tooling, while others provide broader platform capabilities such as web interfaces, multi-database support, and team-oriented management features.

## Overview of existing solutions [#overview-of-existing-solutions]

Traditional tools like [Barman](https://pgbarman.org/), [pgBackRest](https://pgbackrest.org/), and [WAL-G](https://wal-g.readthedocs.io/) offer robust backup and recovery capabilities but are typically aimed at infrastructure specialists, requiring configuration via files and command-line interfaces.

Newer platforms such as [Databasus](https://databasus.com/) and [Databasement](https://david-crty.github.io/databasement/) simplify backup management through graphical interfaces and guided configuration, making them more accessible to development teams.

Enterprise solutions like [Veeam](https://www.veeam.com/) provide comprehensive backup across multiple systems but are proprietary and primarily targeted at large organizations.

Portabase adopts a different approach: an open-source, lightweight platform with agent-based architecture, a web interface, and multi-database support. It is fully self-hosted and designed to simplify backup management for teams handling multiple databases.

## Feature Comparison [#feature-comparison]

| Feature                     | Portabase | Barman | pgBackRest | WAL-G | Databasus | Databasement | Veeam |
| --------------------------- | :-------: | :----: | :--------: | :---: | :-------: | :----------: | :---: |
| Multiple DBMS supported     |     ✅     |    ❌   |      ❌     |   ✅   |     ✅     |       ✅      |   ✅   |
| Web UI                      |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ✅      |   ✅   |
| Agent Architecture          |     ✅     |    ❌   |      ❌     |   ❌   |     ❌     |       ❌      |   ✅   |
| Organizations/Teams         |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ❌      |   ✅   |
| Built-in notifications      |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ✅      |   ✅   |
| OIDC/OAuth2                 |     ✅     |    ❌   |      ❌     |   ❌   |     ❌     |       ❌      |   ✅   |
| Docker installation         |     ✅     |    ❌   |      ❌     |   ✅   |     ✅     |       ✅      |   ❌   |
| Self-hosted support         |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ❌   |
| Encryption                  |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ✅   |
| Built-in retention policies |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ✅   |
| Open-Source                 |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ❌   |

[//]: # "\"pages\": [\"overview\",\"dump\",\"veeam\",\"wal-g\",\"databasus\"]"


# Getting Started 



Portabase is composed of three main parts. To get started, we recommend installing the **Dashboard** first, then your first **Agent**.

<div className="mt-8 flex justify-center">
  <div className="w-full max-w-2xl aspect-video">
    <VideoDialog animationStyle="top-in-bottom-out" videoSrc="https://www.youtube.com/embed/42NCH5JHjdE" thumbnailSrc="/static/img/thumbnail-portabase-onboarding.png" thumbnailAlt="Portabase Onboarding - Youtube" />
  </div>
</div>

<Cards>
  <Card href="/docs/installation" title="Install the Dashboard" icon="<DatabaseIcon />" description="Set up the central management interface to manage all your backups and agents." />

  <Card href="/docs/installation#agent-coverage" title="Install an Agent" icon="<WaypointsIcon />" description="Deploy a lightweight agent on your database servers to handle backup tasks." />

  <Card href="/docs/cli" title="CLI Reference" icon="<TerminalIcon />" description="Learn how to use the Portabase CLI to automate installation and management." />
</Cards>

***

### 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
```


# CLI 



The CLI is the recommended way to install Portabase. It downloads the templates, generates the encryption secret (`PROJECT_SECRET`) and starts the containers for you.

<Callout type="warn">
  Install the CLI first. If it isn't installed yet, follow the instructions [here](/docs/cli#installation).
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Create the Dashboard [#create-the-dashboard]

        Run the following command. This will create a folder containing the configuration.

        ```bash
        # Syntax: portabase dashboard <folder-name>
        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
        ```
      </Step>

      <Step>
        ### 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
        ```
      </Step>

      <Step>
        ### Access the interface [#access-the-interface]

        Open your browser: &#x2A;*[http://localhost:8887](http://localhost:8887)** (or the chosen port).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    The CLI guides you step by step: it configures the agent and offers to add databases immediately.

    <Steps>
      <Step>
        ### Retrieve your Edge Key [#retrieve-your-edge-key]

        Before starting, go to your **Portabase Dashboard**, create a new Agent and copy its **Edge Key**.
      </Step>

      <Step>
        ### 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.
      </Step>

      <Step>
        ### 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.
      </Step>

      <Step>
        ### Start [#start]

        If you didn't start the agent at the end of installation:

        ```bash
        portabase start my-agent
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Daily management [#daily-management]

The CLI offers convenient shortcuts to manage the lifecycle of a dashboard or an agent without typing complex Docker commands. `<path>` is the folder created at installation.

| Action        | Command                      | Description                                                                                                                                 |
| :------------ | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **Start**     | `portabase start <path>`     | Launches containers in the background (`up -d`).                                                                                            |
| **Stop**      | `portabase stop <path>`      | Stops containers cleanly.                                                                                                                   |
| **Restart**   | `portabase restart <path>`   | Restarts the complete stack.                                                                                                                |
| **Logs**      | `portabase logs <path>`      | Displays logs in real time (`-f` option enabled by default). For an agent, use it to check the connection to the dashboard ("Ping server"). |
| **Uninstall** | `portabase uninstall <path>` | ⚠️ Removes containers **and** data volumes.                                                                                                 |

***

## Next steps [#next-steps]

* [Environment variables](/docs/dashboard/configuration/environment) for the Dashboard, or [Agent environment](/docs/agent/environment).
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) to expose the Dashboard behind a domain.
* [Getting started](/docs/dashboard/getting-started) to create your first backup.


# Coolify 



[Coolify](https://coolify.io) is an open-source, self-hosted PaaS - a Heroku/Netlify/Vercel alternative you run on your own servers. Portabase is published in its **service catalogue**, so the Dashboard and its PostgreSQL database deploy together in a few clicks, with no `docker-compose.yml` to write.

Useful links: [Coolify website](https://coolify.io) · [Coolify documentation](https://coolify.io/docs) · [Coolify on GitHub](https://github.com/coollabsio/coolify)

<Callout type="warn">
  You need a working Coolify instance with at least one server connected, and a domain pointing at
  it if you want HTTPS. See the [requirements](/docs/requirements) for the rest.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Create the resource [#create-the-resource]

        In your Coolify dashboard, open the project and environment you want to deploy into,
        then click **+ New** and pick the **Service** tab.
      </Step>

      <Step>
        ### Pick Portabase from the catalogue [#pick-portabase-from-the-catalogue]

        Search for **Portabase** in the list of one-click services and select it.

        Coolify creates the Portabase container together with its PostgreSQL database, and
        pre-fills the generated values (database credentials, `PROJECT_SECRET`).
      </Step>

      <Step>
        ### Set the domain [#set-the-domain]

        Open the service settings and set the **Domain** (FQDN) of the Portabase container,
        for example `https://portabase.example.com`. Coolify handles the reverse proxy and
        the TLS certificate, so you do not need our own
        [reverse proxy guide](/docs/dashboard/configuration/reverse-proxy) here.

        Make sure the `PROJECT_URL` environment variable matches that exact public URL,
        scheme included. Agents use it to reach the Dashboard.
      </Step>

      <Step>
        ### Review the secret [#review-the-secret]

        <Callout type="warn">
          `PROJECT_SECRET` encrypts everything the agents exchange with the Dashboard, and
          the credentials stored in it. Keep it backed up, and **never change it once agents
          are connected** - previously encrypted data would no longer be readable.
        </Callout>

        If it wasn't generated for you, set it to a strong random value:

        ```bash
        openssl rand -hex 32
        ```

        The full list of what you can tune is on the
        [environment variables](/docs/dashboard/configuration/environment) page.
      </Step>

      <Step>
        ### Deploy [#deploy]

        Click **Deploy** and wait for the container to become healthy, then open your domain
        and follow [getting started](/docs/dashboard/getting-started).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      The Agent is not deployed through Coolify. It has to run next to your databases, on the
      host itself, so it can reach them over the local network - including databases Coolify
      does not manage.
    </Callout>

    Install it directly on the database server with the [CLI](/docs/installation/cli) or
    [Docker Compose](/docs/installation/docker), then read
    [backing up Coolify-managed databases](#backing-up-coolify-managed-databases) below.
  </Tab>
</Tabs>

***

## Backing up Coolify-managed databases [#backing-up-coolify-managed-databases]

Coolify runs each database as a Docker container on its own Docker network. For the Portabase Agent
to reach them, connect the agent container to that network as well:

```bash
# List the networks Coolify created, then attach the agent to the right one
docker network ls
docker network connect <coolify-network> portabase-agent
```

Then declare the database in the Dashboard using the **container name** as the host, and its normal
port. Databases running on the host rather than in a container are reachable through the
`extra_hosts` mapping already present in the [agent compose file](/docs/installation/docker).

Per-engine settings - required grants, dump options, restore behaviour - are documented in the
[databases section](/docs/agent/db).

***

## Troubleshooting [#troubleshooting]

* **The agent shows as offline.** Check that `PROJECT_URL` is the public HTTPS URL of the Dashboard, not an internal container name, then review the [agent configuration](/docs/agent/configuration).
* **The agent cannot reach a database.** It is almost always a Docker network issue - see the section above.
* **You changed `PROJECT_SECRET`.** Existing encrypted data cannot be recovered. Restore the previous value.

More answers in the [FAQ](/docs/faq).

***

## Related pages [#related-pages]

<Cards>
  <Card href="/docs/installation/dokploy" title="Dokploy" icon="<DatabaseIcon />" description="The same one-click deploy, on the Dokploy PaaS." />

  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Install the Agent next to your databases with Docker Compose." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentication" icon="<ShieldCheckIcon />" description="Add OAuth2 or OIDC providers in front of your Dashboard." />

  <Card href="/docs/agent/db" title="Databases" icon="<WaypointsIcon />" description="Per-engine configuration for every database Portabase supports." />
</Cards>


# Docker 



Deploy Portabase yourself, without the CLI. Use **Docker Run** for a quick test and **Docker Compose** for anything you intend to keep.

<Callout type="warn">
  Make sure the Docker engine is already installed on the host.
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    ## Docker Run [#docker-run]

    Recommended for testing only, not for production: this uses the bundled internal database.

    <Steps>
      <Step>
        ### Environment variables [#environment-variables]

        Create the `.env` file. **Warning**, you must generate passwords and secrets yourself.

        ```bash title=".env"
        # --- App Configuration ---
        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
        ```
      </Step>

      <Step>
        ### Start the Dashboard [#start-the-dashboard]

        ```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
        ```
      </Step>

      <Step>
        ### Access the interface [#access-the-interface]

        Open your browser: &#x2A;*[http://localhost:8887](http://localhost:8887)** (or the chosen port).
      </Step>
    </Steps>

    ## Docker Compose [#docker-compose]

    Recommended for production and GitOps workflows: the Dashboard runs alongside a dedicated PostgreSQL container.

    <Steps>
      <Step>
        ### 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
        ```
      </Step>

      <Step>
        ### Docker configuration [#docker-configuration]

        ```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:
              - "8887:80"
            volumes:
              - portabase-data:/data
            depends_on:
              db:
                condition: service_healthy
            healthcheck:
                test: ["CMD-SHELL", "curl -f http://localhost/api/health"]
                interval: 30s
                timeout: 5s
                retries: 3
                start_period: 60s

          db:
            container_name: portabase-pg
            image: postgres:17-alpine
            restart: 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:
        ```
      </Step>

      <Step>
        ### Environment variables [#environment-variables-1]

        Create the `.env` file. **Warning**, you must generate passwords and secrets yourself.

        ```bash title=".env"
        # --- App Configuration ---
        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

        # --- Database URL ---
        POSTGRES_USER=portabase
        POSTGRES_PASSWORD=changeme
        POSTGRES_HOST=db
        POSTGRES_PORT=5432
        POSTGRES_DB=portabase

        DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public
        ```
      </Step>

      <Step>
        ### Startup [#startup]

        ```bash
        docker compose up -d
        ```
      </Step>

      <Step>
        ### Access the interface [#access-the-interface-1]

        Open your browser: &#x2A;*[http://localhost:8887](http://localhost:8887)** (or the chosen port).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    For a manual installation, create the file structure and configure the network so the agent can reach your local databases.

    <Steps>
      <Step>
        ### File structure [#file-structure-1]

        Create a folder and prepare required files:

        ```bash
        mkdir portabase-agent && cd portabase-agent
        touch docker-compose.yml .env databases.json
        ```

        <Callout type="warn">
          The `databases.json` file must exist (even empty) before starting the container, otherwise the agent may fail to start.
        </Callout>

        Initialize the JSON file with an empty object:

        ```bash
        echo '{"databases": []}' > databases.json
        ```
      </Step>

      <Step>
        ### Docker configuration [#docker-configuration-1]

        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
                    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`.*
      </Step>

      <Step>
        ### Environment variables [#environment-variables-2]

        Retrieve the **Edge Key** of the agent you created in the Dashboard, then add it to the `.env` file:

        ```bash title=".env"
        EDGE_KEY=your_edge_key_here
        ```

        For the full list of available environment variables, see the [Environment](/docs/agent/environment) page.
      </Step>

      <Step>
        ### Start [#start]

        ```bash
        docker compose up -d
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Next steps [#next-steps]

* [Environment variables](/docs/dashboard/configuration/environment) for the Dashboard, or [Agent environment](/docs/agent/environment).
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) to expose the Dashboard behind a domain.
* [Getting started](/docs/dashboard/getting-started) to create your first backup.


# Dokploy 



[Dokploy](https://dokploy.com) is an open-source, self-hosted PaaS built on Docker and Traefik - a Vercel/Netlify/Heroku alternative for your own servers. Portabase is published in its **template catalogue**, so the Dashboard and its PostgreSQL database deploy together in a few clicks, with no `docker-compose.yml` to write.

Useful links: [Dokploy website](https://dokploy.com) · [Dokploy documentation](https://docs.dokploy.com) · [Dokploy on GitHub](https://github.com/Dokploy/dokploy)

<Callout type="warn">
  You need a working Dokploy instance, and a domain pointing at it if you want HTTPS. See the
  [requirements](/docs/requirements) for the rest.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Create the service [#create-the-service]

        Open the project you want to deploy into, click **Create Service** and choose **Template**.
      </Step>

      <Step>
        ### Pick Portabase from the catalogue [#pick-portabase-from-the-catalogue]

        Search for **Portabase** in the template list and create it.

        Dokploy provisions the Portabase container together with its PostgreSQL database, and
        pre-fills the generated values (database credentials, `PROJECT_SECRET`).
      </Step>

      <Step>
        ### Set the domain [#set-the-domain]

        In the service's **Domains** tab, add the public host of the Portabase container, for
        example `portabase.example.com`, targeting port **80**. Enable HTTPS so Dokploy issues
        the certificate through Traefik - our own
        [reverse proxy guide](/docs/dashboard/configuration/reverse-proxy) is not needed here.

        Make sure the `PROJECT_URL` environment variable matches that exact public URL,
        scheme included. Agents use it to reach the Dashboard.
      </Step>

      <Step>
        ### Review the secret [#review-the-secret]

        <Callout type="warn">
          `PROJECT_SECRET` encrypts everything the agents exchange with the Dashboard, and
          the credentials stored in it. Keep it backed up, and **never change it once agents
          are connected** - previously encrypted data would no longer be readable.
        </Callout>

        If it wasn't generated for you, set it to a strong random value:

        ```bash
        openssl rand -hex 32
        ```

        The full list of what you can tune is on the
        [environment variables](/docs/dashboard/configuration/environment) page.
      </Step>

      <Step>
        ### Deploy [#deploy]

        Click **Deploy** and wait for the container to become healthy, then open your domain
        and follow [getting started](/docs/dashboard/getting-started).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      The Agent is not deployed through Dokploy. It has to run next to your databases, on the
      host itself, so it can reach them over the local network - including databases Dokploy
      does not manage.
    </Callout>

    Install it directly on the database server with the [CLI](/docs/installation/cli) or
    [Docker Compose](/docs/installation/docker), then read
    [backing up Dokploy-managed databases](#backing-up-dokploy-managed-databases) below.
  </Tab>
</Tabs>

***

## Backing up Dokploy-managed databases [#backing-up-dokploy-managed-databases]

Dokploy runs each database as a Docker container on its own Docker network. For the Portabase Agent
to reach them, connect the agent container to that network as well:

```bash
# List the networks Dokploy created, then attach the agent to the right one
docker network ls
docker network connect <dokploy-network> portabase-agent
```

Then declare the database in the Dashboard using the **container name** as the host, and its normal
port. Databases running on the host rather than in a container are reachable through the
`extra_hosts` mapping already present in the [agent compose file](/docs/installation/docker).

Per-engine settings - required grants, dump options, restore behaviour - are documented in the
[databases section](/docs/agent/db).

***

## Troubleshooting [#troubleshooting]

* **The agent shows as offline.** Check that `PROJECT_URL` is the public HTTPS URL of the Dashboard, not an internal container name, then review the [agent configuration](/docs/agent/configuration).
* **The agent cannot reach a database.** It is almost always a Docker network issue - see the section above.
* **You changed `PROJECT_SECRET`.** Existing encrypted data cannot be recovered. Restore the previous value.

More answers in the [FAQ](/docs/faq).

***

## Related pages [#related-pages]

<Cards>
  <Card href="/docs/installation/coolify" title="Coolify" icon="<DatabaseIcon />" description="The same one-click deploy, on the Coolify PaaS." />

  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Install the Agent next to your databases with Docker Compose." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentication" icon="<ShieldCheckIcon />" description="Add OAuth2 or OIDC providers in front of your Dashboard." />

  <Card href="/docs/agent/db" title="Databases" icon="<WaypointsIcon />" description="Per-engine configuration for every database Portabase supports." />
</Cards>


# Overview 



Portabase ships as two components, and both are installed from this section:

* The **Dashboard** - the control plane. Install it once, wherever you want to manage things from.
* The **Agent** - the connector. Install one on each server that holds databases to back up.

Start with the Dashboard, then install your first Agent. Every page below covers both, in a **Dashboard** and an **Agent** tab.

<Callout type="warn">
  Check the [Requirements](/docs/requirements) before you start.
</Callout>

***

## Choose a method [#choose-a-method]

| Method                                          | Best for                                                | Internal database        | Support       | Status       |
| :---------------------------------------------- | :------------------------------------------------------ | :----------------------- | :------------ | :----------- |
| [**CLI**](/docs/installation/cli)               | Getting started, and the fastest path on a plain server | -                        | Official      | ✅ Tested     |
| [**Docker**](/docs/installation/docker)         | Manual control, GitOps, existing Docker hosts           | Bundled or external      | Official      | ✅ Tested     |
| [**Kubernetes**](/docs/installation/kubernetes) | Existing clusters, Helm-based workflows                 | Bundled or external      | Official      | ✅ Tested     |
| [**Coolify**](/docs/installation/coolify)       | Self-hosted PaaS users who want a one-click deploy      | Managed by Coolify       | Official      | ✅ Tested     |
| [**Dokploy**](/docs/installation/dokploy)       | Self-hosted PaaS users who want a one-click deploy      | Managed by Dokploy       | Official      | ✅ Tested     |
| [**Unraid**](/docs/installation/unraid)         | Unraid servers, install from Community Applications     | External (PostgreSQL 17) | Official      | ✅ Tested     |
| [**Proxmox VE**](/docs/installation/proxmox)    | Proxmox hosts, LXC via the community helper script      | Installed in the LXC     | ⚠️ Unofficial | ❌ Not tested |

**Support** - *Official* methods are published and maintained by the Portabase team. *Unofficial* ones are maintained by a third party; we do not control what they install or when they change.

**Status** - *Tested* means we run the method ourselves before each release. *Not tested* means we have not verified it.

If you have no strong preference, use the **CLI**. It generates the encryption secret and starts the containers for you.

<Cards>
  <Card href="/docs/installation/cli" title="CLI" icon="<TerminalIcon />" description="One command to create and start the Dashboard or an Agent. Recommended." />

  <Card href="/docs/installation/docker" title="Docker" icon="<ContainerIcon />" description="Docker Run for a quick test, Docker Compose for production." />

  <Card href="/docs/installation/kubernetes" title="Kubernetes" icon="<ShipIcon />" description="Install the Helm chart from the OCI registry." />

  <Card href="/docs/installation/coolify" title="Coolify" icon="<CloudIcon />" description="Deploy the Dashboard from the Coolify service catalogue." />

  <Card href="/docs/installation/dokploy" title="Dokploy" icon="<LayersIcon />" description="Deploy the Dashboard from the Dokploy template catalogue." />

  <Card href="/docs/installation/unraid" title="Unraid" icon="<HardDriveIcon />" description="Install the Dashboard from the Community Applications catalogue." />

  <Card href="/docs/installation/proxmox" title="Proxmox VE" icon="<ServerIcon />" description="Community helper script that builds a Debian LXC. Unofficial, untested." />
</Cards>

***

## Agent coverage [#agent-coverage]

The Agent runs next to your databases, so it is installed directly on the host rather than through a PaaS or a cluster.

| Method     | Dashboard | Agent                                                                        |
| :--------- | :-------- | :--------------------------------------------------------------------------- |
| CLI        | ✅         | ✅                                                                            |
| Docker     | ✅         | ✅                                                                            |
| Kubernetes | ✅         | ❌ - use [Docker](/docs/installation/docker)                                  |
| Coolify    | ✅         | ❌ - use [CLI](/docs/installation/cli) or [Docker](/docs/installation/docker) |
| Dokploy    | ✅         | ❌ - use [CLI](/docs/installation/cli) or [Docker](/docs/installation/docker) |
| Unraid     | ✅         | ❌ - use [Docker](/docs/installation/docker)                                  |
| Proxmox VE | ✅         | ❌ - use [CLI](/docs/installation/cli) or [Docker](/docs/installation/docker) |

***

## After installing [#after-installing]

Once the Dashboard is up, continue with:

* [Environment variables](/docs/dashboard/configuration/environment) - external database, mail, storage limits.
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) - put it behind a domain with HTTPS.
* [Authentication](/docs/dashboard/configuration/auth/configuration) - OAuth2 and OIDC providers.
* [Getting started](/docs/dashboard/getting-started) - create your first agent and backup.


# Kubernetes 



For Kubernetes deployments, install the Dashboard directly from the OCI registry with Helm.

<Callout type="warn">
  Requires a working cluster, `kubectl` configured against it, and Helm 3.8+ (OCI support).
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    ## With ClusterIP + port-forward (for development/testing) [#with-clusterip--port-forward-for-developmenttesting]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set project.secret=$(openssl rand -hex 32)
    ```

    ```bash
    kubectl port-forward svc/portabase 8887:80 -n portabase
    # Access at http://localhost:8887
    ```

    ## With LoadBalancer (for cloud environments) [#with-loadbalancer-for-cloud-environments]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set service.type=LoadBalancer \
    --set project.secret=$(openssl rand -hex 32)
    ```

    ```bash
    kubectl get svc portabase -n portabase
    # Access at http://<EXTERNAL-IP>:8887
    ```

    ## With Ingress (domain-based access) [#with-ingress-domain-based-access]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set ingress.enabled=true \
    --set ingress.hosts[0].host=portabase.example.com \
    --set project.secret=$(openssl rand -hex 32)
    ```
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      There is no Helm chart for the Agent. The Agent is meant to run next to your databases,
      on the host itself, so it can reach them over the local network.
    </Callout>

    Install it on the database server with the [CLI](/docs/installation/cli) or
    [Docker Compose](/docs/installation/docker) instead.
  </Tab>
</Tabs>

***

## Next steps [#next-steps]

* [Environment variables](/docs/dashboard/configuration/environment) - point the Dashboard at an external PostgreSQL.
* [Authentication](/docs/dashboard/configuration/auth/configuration) - OAuth2 and OIDC providers.
* [Getting started](/docs/dashboard/getting-started) - create your first backup.


# Proxmox VE 



[Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment) is an open-source virtualisation platform. The [community-scripts](https://community-scripts.org) project maintains a helper script that creates a Debian 13 LXC container and installs the Portabase Dashboard in it - PostgreSQL, tusd, nginx and the systemd services included.

Useful links: [Portabase helper script](https://community-scripts.org/scripts/portabase) · [community-scripts website](https://community-scripts.org) · [Proxmox VE documentation](https://pve.proxmox.com/pve-docs/)

<Callout type="error">
  **Unofficial and untested.** This script is maintained by the community-scripts project, not by
  the Portabase team, and it is currently in their **development** repository - marked as *in
  active development*, *may be unstable, incomplete, or subject to breaking changes*, and **not
  recommended for production use**. It is also the only installation method we have not tested
  ourselves. For a supported deployment, use the [CLI](/docs/installation/cli) or
  [Docker](/docs/installation/docker) instead.
</Callout>

***

## What the script installs [#what-the-script-installs]

| Item              | Value                                                  |
| :---------------- | :----------------------------------------------------- |
| Container type    | Unprivileged LXC                                       |
| OS                | Debian 13                                              |
| Default resources | 4 vCPU · 8192 MB RAM · 15 GB disk                      |
| Port              | `3000` (nginx in front of the app on `127.0.0.1:8887`) |
| Database          | PostgreSQL 17, installed inside the container          |
| Uploads           | tusd, as the `portabase-tusd` service                  |
| Config file       | `/opt/portabase/.env`                                  |
| Services          | `portabase`, `portabase-tusd`                          |

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Run the script from the Proxmox VE shell [#run-the-script-from-the-proxmox-ve-shell]

        Open the **Shell** of your Proxmox VE node and run:

        ```bash
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/portabase.sh)"
        ```

        <Callout type="info">
          Always read the script before running it. The current, authoritative command is
          shown on the [script page](https://community-scripts.org/scripts/portabase) -
          check it there if the URL above has moved.
        </Callout>

        Accept the defaults, or pick **Advanced** to change the CPU, RAM, disk and network
        settings.
      </Step>

      <Step>
        ### Open the Dashboard [#open-the-dashboard]

        When the script finishes it prints the URL, `http://<container-ip>:3000`.

        Sign in with the default account it created:

        | User                | Password        |
        | :------------------ | :-------------- |
        | `admin@example.com` | `Portabase123!` |

        <Callout type="warn">
          Change this password immediately after the first login, and set
          `AUTH_SIGNUP_ENABLED=false` in `/opt/portabase/.env` once your account exists.
        </Callout>
      </Step>

      <Step>
        ### Review the configuration [#review-the-configuration]

        The script generates `PROJECT_SECRET` for you and writes it to `/opt/portabase/.env`,
        alongside `DATABASE_URL`, `PROJECT_URL` and `TRUSTED_DOMAINS` - both set to
        `http://<container-ip>:3000`.

        <Callout type="warn">
          `PROJECT_SECRET` encrypts everything the agents exchange with the Dashboard, and
          the credentials stored in it. Back up `/opt/portabase/.env`, and **never change the
          secret once agents are connected** - previously encrypted data would no longer be
          readable.
        </Callout>

        SMTP, storage backends and auth providers go in the same file - see
        [environment variables](/docs/dashboard/configuration/environment). Apply changes with:

        ```bash
        systemctl restart portabase
        ```

        If you put the Dashboard behind a domain with HTTPS - see the
        [reverse proxy guide](/docs/dashboard/configuration/reverse-proxy) - update
        `PROJECT_URL` and `TRUSTED_DOMAINS` to that public URL.
      </Step>

      <Step>
        ### Updating [#updating]

        Re-run the same command and choose **Update**. The script stops the services, backs up
        `/opt/portabase/.env`, deploys the new release, rebuilds the app and restores your
        configuration.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      The helper script installs the Dashboard only. The Agent has to run next to your
      databases, so it is installed directly on the host that holds them.
    </Callout>

    Install it with the [CLI](/docs/installation/cli) or
    [Docker Compose](/docs/installation/docker) - in the LXC container or VM that runs the
    database, or on the Proxmox host itself if the databases live there.
  </Tab>
</Tabs>

***

## Backing up databases hosted on Proxmox VE [#backing-up-databases-hosted-on-proxmox-ve]

Databases usually run in other LXC containers or VMs on the same node. Install one Agent per
container or VM, then declare each database in the Dashboard using the container or VM IP and the
database port. Make sure the Proxmox firewall allows the Agent to reach it.

Per-engine settings - required grants, dump options, restore behaviour - are documented in the
[databases section](/docs/agent/db).

***

## Troubleshooting [#troubleshooting]

* **The Dashboard does not answer on port 3000.** Check both services: `systemctl status portabase portabase-tusd`, and the logs with `journalctl -u portabase -f`.
* **The agent shows as offline.** `PROJECT_URL` must be the URL the agent can actually reach. Update it in `/opt/portabase/.env` and restart. See the [agent configuration](/docs/agent/configuration).
* **Uploads or restores fail.** The `portabase-tusd` service is down, or `TUSD_BEHIND_PROXY` was changed. Restart it with `systemctl restart portabase-tusd`.
* **The script itself fails.** It is a community-scripts issue, not a Portabase one - report it on [their GitHub](https://github.com/community-scripts/ProxmoxVED/issues) with the advanced verbose-mode logs.

More answers in the [FAQ](/docs/faq).

***

## Related pages [#related-pages]

<Cards>
  <Card href="/docs/installation/cli" title="CLI" icon="<TerminalIcon />" description="The supported one-command install, on any Linux host." />

  <Card href="/docs/installation/unraid" title="Unraid" icon="<DatabaseIcon />" description="Install the Dashboard from the Community Applications catalogue." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentication" icon="<ShieldCheckIcon />" description="Add OAuth2 or OIDC providers in front of your Dashboard." />

  <Card href="/docs/agent/db" title="Databases" icon="<WaypointsIcon />" description="Per-engine configuration for every database Portabase supports." />
</Cards>


# Unraid 



[Unraid](https://unraid.net) is a NAS operating system with a Docker-based application store. Portabase is published as an **official template** in [Community Applications](https://ca.unraid.net/apps/portabase-dashboard-1sdc97m05ufd7q), so the Dashboard installs from the Apps tab with no `docker-compose.yml` to write.

Useful links: [Portabase on Community Applications](https://ca.unraid.net/apps/portabase-dashboard-1sdc97m05ufd7q) · [Unraid website](https://unraid.net) · [Unraid documentation](https://docs.unraid.net)

<Callout type="warn">
  The template does **not** ship a database. You need a reachable **PostgreSQL 17** instance before
  you install - either the PostgreSQL container from Community Applications, or an external server.
  See the [requirements](/docs/requirements) for the rest.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Install PostgreSQL 17 [#install-postgresql-17]

        From the **Apps** tab, install a PostgreSQL 17 container and create a database and a
        user for Portabase. Note the host, port, database name, user and password - you need
        them in the next step.
      </Step>

      <Step>
        ### Add the Portabase template [#add-the-portabase-template]

        Still in the **Apps** tab, search for **Portabase**, then select
        **Portabase-Dashboard** and click **Install**.

        The template uses the official `portabase/portabase:latest` image, in **bridge**
        network mode.
      </Step>

      <Step>
        ### Fill in the required variables [#fill-in-the-required-variables]

        | Field                  | Default                                 | Notes                                                                         |
        | :--------------------- | :-------------------------------------- | :---------------------------------------------------------------------------- |
        | WebUI port             | `8887` → container `80`                 | Change the host port if `8887` is taken                                       |
        | `/data`                | `/mnt/user/appdata/portabase/dashboard` | Persistent data, keep it on the array                                         |
        | `DATABASE_URL`         | -                                       | `postgresql://user:password@host:5432/portabase`                              |
        | `PROJECT_SECRET`       | -                                       | Strong random hex value, see below                                            |
        | `PROJECT_URL`          | -                                       | The Dashboard URL **as the agents reach it**, e.g. `http://192.168.1.10:8887` |
        | `AUTH_SIGNUP_ENABLED`  | -                                       | Turn it off once your account exists                                          |
        | `AUTH_PASSKEY_ENABLED` | `true`                                  | Passkey authentication                                                        |

        Optional variables - `PROJECT_NAME`, `AUTH_DEFAULT_USER_NAME`, `AUTH_DEFAULT_USER`,
        `AUTH_DEFAULT_PASSWORD`, the SMTP settings and `RETENTION_CRON` - are documented on
        the [environment variables](/docs/dashboard/configuration/environment) page.
      </Step>

      <Step>
        ### Generate the secret [#generate-the-secret]

        <Callout type="warn">
          `PROJECT_SECRET` encrypts everything the agents exchange with the Dashboard, and
          the credentials stored in it. Keep it backed up, and **never change it once agents
          are connected** - previously encrypted data would no longer be readable.
        </Callout>

        From the Unraid terminal:

        ```bash
        openssl rand -hex 32
        ```
      </Step>

      <Step>
        ### Apply and open the WebUI [#apply-and-open-the-webui]

        Click **Apply**, wait for the container to start, then open
        `http://<unraid-ip>:8887` and follow
        [getting started](/docs/dashboard/getting-started).

        To expose it on a domain with HTTPS, put it behind a reverse proxy - see the
        [reverse proxy guide](/docs/dashboard/configuration/reverse-proxy) - and set
        `PROJECT_URL` to that public URL.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      There is no Community Applications template for the Agent yet. It has to run next to your
      databases, on the host itself, so it can reach them over the local network.
    </Callout>

    To back up databases hosted **on the Unraid server**, install the Agent there with
    [Docker Compose](/docs/installation/docker) from the Unraid terminal. For databases on other
    machines, install one Agent per machine with the [CLI](/docs/installation/cli) or
    [Docker](/docs/installation/docker).
  </Tab>
</Tabs>

***

## Backing up databases running on Unraid [#backing-up-databases-running-on-unraid]

Unraid runs each database as a Docker container. For the Agent to reach one, both containers need to
share a network:

```bash
# List the Docker networks, then attach the agent to the right one
docker network ls
docker network connect <network> portabase-agent
```

Then declare the database in the Dashboard using the **container name** as the host, and its normal
port. Containers on the default `bridge` network are also reachable at the Unraid IP on their
published port.

Per-engine settings - required grants, dump options, restore behaviour - are documented in the
[databases section](/docs/agent/db).

***

## Troubleshooting [#troubleshooting]

* **The container restarts in a loop.** `DATABASE_URL` is wrong or PostgreSQL is unreachable. Check the container log from the Unraid UI.
* **The agent shows as offline.** `PROJECT_URL` must be the URL the agent can actually reach - the Unraid LAN IP, or the public HTTPS URL if you use a reverse proxy. See the [agent configuration](/docs/agent/configuration).
* **The agent cannot reach a database.** Almost always a Docker network issue - see the section above.
* **You changed `PROJECT_SECRET`.** Existing encrypted data cannot be recovered. Restore the previous value.

More answers in the [FAQ](/docs/faq).

***

## Related pages [#related-pages]

<Cards>
  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Install the Agent next to your databases with Docker Compose." />

  <Card href="/docs/installation/proxmox" title="Proxmox VE" icon="<DatabaseIcon />" description="Deploy the Dashboard in an LXC container with the community helper script." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentication" icon="<ShieldCheckIcon />" description="Add OAuth2 or OIDC providers in front of your Dashboard." />

  <Card href="/docs/agent/db" title="Databases" icon="<WaypointsIcon />" description="Per-engine configuration for every database Portabase supports." />
</Cards>


# Docker Volume 



The `docker-volume` type lets the agent back up a Docker named volume directly, without going through a database driver. It is useful for engines with no dedicated dump tool, or for protecting any container's data volume as-is.

Backup and restore are performed **on the fly, hot**, without stopping the target container.

<Callout type="warn">
  This provider requires the agent to have access to the Docker socket. You must mount `/var/run/docker.sock:/var/run/docker.sock` on the agent container, otherwise it cannot inspect or archive the volume.
</Callout>

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `docker-volume` as the database type.

    **Specific parameters asked:**

    * **Volume Name**: The exact name of the Docker volume to back up (e.g., `databases_sqlite-data`).
    * **Container Name**: (Optional, but recommended) The name of the container currently using the volume. Provide it so the agent can automatically restart that container after a restore.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Test database 14 - Docker Volume",
      "type": "docker-volume",
      "volume_name": "<volume_name>",
      "generated_id": "...",
      "container_name": "<container_name>"
    }
    ```

    <UUIDGenerator />

    **Specific Parameters:**

    * **volume\_name**: (Required) The name of the Docker volume to back up.
    * **container\_name**: (Optional, but recommended) The name of the container the volume is attached to. Without it the backup/restore still works, but the agent cannot restart the container automatically after a restore.
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

The agent needs access to the Docker socket to inspect and archive volumes. Mount it alongside your regular agent configuration.

```yaml title="docker-compose.yml"
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      # Required: gives the agent access to the Docker daemon
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
    networks:
      - portabase

networks:
  portabase:
    name: portabase_network
    external: true
```

<Callout type="info">
  Without the Docker socket mounted, the agent cannot resolve or archive the volume and the backup job will fail.
</Callout>

## Temporary storage and disk space [#temporary-storage-and-disk-space]

During a `docker-volume` backup, the agent builds the backup archive in a **temporary directory** inside the agent container, using the system temp location, `/tmp` by default.

If `/tmp` sits on a cramped root filesystem, backing up a large volume fails with:

```
No space left on device
```

<Callout type="warn">
  The temporary archive needs roughly the size of the volume being backed up. A 20 GB volume needs about 20 GB free at the temp location, not just at the destination.
</Callout>

### Redirect the temp directory [#redirect-the-temp-directory]

The agent honors the standard `TMPDIR` environment variable. Point it at a directory backed by a bigger disk, and mount host storage there:

```yaml title="docker-compose.yml"
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      - /var/run/docker.sock:/var/run/docker.sock
      # Host dir with enough free space
      - /mnt/bigdisk:/scratch
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
      # Tell the agent to build temp archives here instead of /tmp
      TMPDIR: /scratch
```

Use a host path (`/mnt/bigdisk`) with more free space than the backup size. The temp archive is built there instead of the cramped root filesystem.

<Callout type="info">
  The temp archive is deleted automatically once the backup finishes. The same applies to **restores**: they unpack into the same temp location, so `TMPDIR` must point at a disk large enough for them too.
</Callout>


# Firebird 



Firebird is fully supported by the Portabase agent. We use native `gbak` and `isql` tools to ensure consistent and reliable backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `firebird` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Database - Firebird",
      "database": "/var/lib/firebird/data/mirror.fdb",
      "type": "firebird",
      "username": "alice",
      "password": "fake_password",
      "port": 3050,
      "host": "db-firebird",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

Here is how to configure a Firebird service alongside the agent.

```yaml title="docker-compose.yml"
services:
  db-firebird:
    image: firebirdsql/firebird
    container_name: db-firebird
    restart: always
    environment:
      - FIREBIRD_ROOT_PASSWORD=fake_root_password
      - FIREBIRD_USER=alice
      - FIREBIRD_PASSWORD=fake_password
      - FIREBIRD_DATABASE=mirror.fdb
      - FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8
    volumes:
      - firebird-data:/var/lib/firebird/data
    ports:
      - "3060:3050"
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... agent configuration ...
    depends_on:
      - db-firebird
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  firebird-data:
```

<Callout type="warn">
  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.
</Callout>


# Supported Databases 



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               | Restore |
| :---------------- | :-------------- | :------- | :---------------------------- | :------ |
| **PostgreSQL**    | `postgresql`    | ✅ Stable | 12, 13, 14, 15, 16, 17 and 18 | Yes     |
| **MySQL**         | `mysql`         | ✅ Stable | 5.7, 8 and 9                  | Yes     |
| **MariaDB**       | `mysql`         | ✅ Stable | 10 and 11                     | Yes     |
| **MongoDB**       | `mongodb`       | ✅ Stable | 4, 5, 6, 7 and 8              | Yes     |
| **SQLite**        | `sqlite`        | ✅ Stable | 3.x                           | Yes     |
| **Redis**         | `redis`         | ✅ Stable | 2.8+                          | No      |
| **Valkey**        | `valkey`        | ✅ Stable | 7.2+                          | No      |
| **Firebird**      | `firebird`      | ✅ Stable | 3.0, 4.0, 5.0                 | Yes     |
| **MSSQL Server**  | `mssql`         | ✅ Stable | -                             | Yes     |
| **Docker Volume** | `docker-volume` | ✅ Stable | Docker Engine 20.10+          | Yes     |

## 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).

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    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**.
  </Tab>

  <Tab value="Manual" id="docker">
    You can also edit the `databases.json` (or `.toml`) file mounted in the container.

    ```json title="databases.json"
    {
      "databases": [
        {
          "name": "Database 1 - PostgreSQL",
          "database": "my-db",
          "type": "postgresql",
          "host": "db-prod",
          "port": 5432,
          "username": "admin",
          "password": "secret_password",
          "generated_id": "uuid-v4-unique"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<UUIDGenerator />

<Callout type="info">
  For more details on each engine, check the dedicated pages in this section.
</Callout>


# MariaDB 



The agent will use `mariadb-dump` to perform backups and restore backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `mariadb` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Database - MariaDB",
      "database": "mariadb",
      "type": "mariadb",
      "username": "mariadb",
      "password": "changeme",
      "port": 3306,
      "host": "db-mariadb",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

Example with a MariaDB image.

```yaml title="docker-compose.yml"
services:
  db-mariadb:
    container_name: db-mariadb
    image: mariadb:latest
    ports:
      - "3311:3306"
    environment:
      - MYSQL_DATABASE=mariadb
      - MYSQL_USER=mariadb
      - MYSQL_PASSWORD=changeme
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... agent configuration ...
    depends_on:
      - db-mariadb
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mariadb-data:
```

<Callout type="warn">
  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.
</Callout>


# MongoDB 



The agent will use `mongodump` to perform backups and `mongorestore` to restore backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `mongodb` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ### With Authentication [#with-authentication]

    ```json title="databases.json"
    {
      "name": "Database - MongoDB Auth",
      "database": "testdbauth",
      "type": "mongodb",
      "username": "username",
      "password": "password",
      "port": 27017,
      "host": "db-mongodb-auth",
      "generated_id": "..."
    }
    ```

    ### Without Authentication [#without-authentication]

    ```json title="databases.json"
    {
      "name": "my-mongo",
      "type": "mongodb",
      "host": "db-mongodb",
      "port": 27017,
      "database": "testdb",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## MongoDB Atlas / Cloud (SRV) [#mongodb-atlas--cloud-srv]

Managed MongoDB clusters (MongoDB Atlas and equivalents) are reached through a DNS `SRV` record instead of a fixed host and port. The connection string uses the `mongodb+srv://` scheme.

To use an SRV connection, **omit the `port` field** (or set it to `0`). The agent detects this and automatically switches to `mongodb+srv://`. Use the cluster hostname (ending in `.mongodb.net`) as the `host`.

Via CLI: run `portabase db add`, choose `mongodb`, then leave the port empty to enable the SRV connection.

```json title="databases.json"
{
  "name": "MongoDB Cluster Cloud",
  "database": "mydb",
  "type": "mongodb",
  "username": "username",
  "password": "password",
  "host": "cluster0.abcde.mongodb.net",
  "generated_id": "..."
}
```

<UUIDGenerator />

<Callout type="info">
  No `port` is set for SRV connections. When `port` is absent (or `0`), the agent builds a `mongodb+srv://user:password@host/database?authSource=admin` URI. With authentication, the credentials are URL-encoded automatically and `authSource=admin` is appended. Without a username and password, the URI is built without credentials or query string.
</Callout>

## 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:
```

<Callout type="warn">
  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.
</Callout>


# MsSQL 



MsSQL is fully supported by the Portabase agent. We use native `sqlpackage` tool to ensure consistent and reliable backups and restorations.

<Callout type="warn">
  MsSQL has strict password complexity requirements. Your password must be at least 8 characters long and contain characters from three of the following four categories: Latin uppercase letters, Latin lowercase letters, digits (0 through 9), and non-alphanumeric characters (e.g., !, $, #, %). Failure to meet these requirements will cause the container to crash.
</Callout>

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `mssql` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Database - MsSQL",
      "database": "myappdb",
      "type": "mssql",
      "username": "sa",
      "password": "Password!Strong1",
      "port": 1433,
      "host": "db-mssql",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

Here is how to configure a MsSQL service alongside the agent.

```yaml title="docker-compose.yml"
services:
  db-mssql:
    container_name: db-mssql
    image: mcr.microsoft.com/azure-sql-edge:latest
    ports:
      - "1433:1433"
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "Password!Strong1"
    volumes:
      - mssql-data:/var/opt/mssql
    networks:
      - portabase
    healthcheck:
      test: ["CMD-SHELL", "cat /proc/net/tcp6 | grep -q '059901' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 20

  agent:
    image: portabase/agent:latest
    # ... agent configuration ...
    depends_on:
      - db-mssql
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mssql-data:
```

<Callout type="warn">
  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.
</Callout>


# MySQL 



The agent will use `mysqldump` to perform backups and restore backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `mysql`.

    **Specific parameters asked:**

    * **Database Name**: The name of the database to backup.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` file, use the `mysql` type.

    ```json title="databases.json"
    {
        "name": "Test database 11 - Mysql",
        "database": "mysqldb",
        "type": "mysql",
        "username": "mysqldb",
        "password": "changeme",
        "port": 3306,
        "host": "db-mysql",
        "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Specific Parameters:**

    * **database**: (Required) The name of the database.
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

Example with a MySQL image.

```yaml title="docker-compose.yml"
services:
  db-mysql:
    container_name: db-mysql
    image: mysql:9.5
    ports:
      - "3312:3306"
    environment:
      - MYSQL_DATABASE=mysqldb
      - MYSQL_USER=mysqldb
      - MYSQL_PASSWORD=changeme
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... agent configuration ...
    depends_on:
      - db-mysql
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mysql-data:
```

<Callout type="warn">
  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.
</Callout>


# PostgreSQL 



PostgreSQL is fully supported by the Portabase agent. We use native `pg_dump` tools to ensure consistent and reliable backups.

Two modes are available:

* **`postgresql`**: Single database backup using `pg_dump`. Targets one specific database.
* **`postgresql-cluster`**: Full cluster backup using `pg_dumpall`. Dumps every database in the instance **plus global objects** (roles, ownership, grants, tablespaces). Useful when advanced roles and ownership are configured at the cluster level.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    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.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Database - PostgreSQL",
      "type": "postgresql",
      "host": "postgres",
      "port": 5432,
      "username": "postgres",
      "password": "mysecretpassword",
      "database": "app_db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Specific Parameters:**

    * **database**: (Required) The exact name of the database to dump.
  </Tab>
</Tabs>

## Options [#options]

The following optional fields can be set under an `options` key in the database configuration.

| Option           | Type      | Default   | Description                                                                                                                                                                                                                                                                                                |
| ---------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep_ownership` | `boolean` | `false`   | When `true`, omits `--no-owner` and `--no-privileges` from the dump. Ownership and role assignments are preserved in the output. By default these flags are applied, keeping restores portable across different users and environments, for example, when migrating from one database instance to another. |
| `clean_mode`     | `string`  | `"clean"` | Controls how the target database is cleaned **before a restore**. One of `none`, `clean`, `drop_schemas`, `drop_database`. See [Clean mode](#clean-mode) below.                                                                                                                                            |

```json title="databases.json (with options)"
{
  "name": "Database - PostgreSQL",
  "type": "postgresql",
  "host": "postgres",
  "port": 5432,
  "username": "postgres",
  "password": "mysecretpassword",
  "database": "app_db",
  "generated_id": "...",
  "options": {
    "keep_ownership": true,
    "clean_mode": "drop_schemas"
  }
}
```

### Clean mode [#clean-mode]

`pg_restore --clean` only drops objects that exist in the backup's own table of contents. Anything already present in the target that the dump does not know about survives and can collide with the restore, so restoring into a **populated** database can partially fail (`already exists`, constraint or key errors). `clean_mode` lets you guarantee a clean target before restoring.

| Value           | Behaviour                                                                                    | Use case                                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `none`          | No pre-clean and no `--clean`.                                                               | Restore into a known-empty database. Fastest, least destructive.                                                                    |
| `clean`         | Current behaviour: `pg_restore --clean --if-exists`. &#x2A;*Default.**                       | Existing setups. Not a full reset (see above).                                                                                      |
| `drop_schemas`  | Drops every non-system schema `CASCADE`, then restores.                                      | **Recommended for new setups.** Works on managed Postgres (RDS, Cloud SQL, Neon, Supabase) where the role cannot drop the database. |
| `drop_database` | `DROP DATABASE` + `CREATE DATABASE` preserving encoding, collation and owner, then restores. | Full reset on self-hosted Postgres where the role has `CREATEDB` + ownership, or is superuser.                                      |

If the value is absent or unrecognized, the agent falls back to `clean`. `drop_database` is never applied by default.

<Callout type="warning">
  `drop_schemas` and `drop_database` are **destructive and have no rollback**. If the agent stops between the drop and the restore, the target is left empty or gone. `drop_database` additionally requires that the connecting role is the database owner **and** holds `CREATEDB`, or is a superuser, otherwise the restore fails a preflight check before anything is dropped. Prefer `drop_schemas` on managed providers where you cannot drop the database.
</Callout>

<Callout type="info">
  `drop_schemas` is schema-scoped: it does not remove database- or cluster-scoped objects (event triggers, publications/subscriptions, database-level settings, roles, tablespaces). Extensions installed into a dropped schema are recreated on restore only if the restoring role has permission (superuser-only extensions such as `pg_stat_statements` are not). For a fully pristine target including global objects, use `drop_database`.
</Callout>

```json title="databases.json (drop and recreate before restore)"
{
  "name": "Database - PostgreSQL",
  "type": "postgresql",
  "host": "postgres",
  "port": 5432,
  "username": "postgres",
  "password": "mysecretpassword",
  "database": "app_db",
  "generated_id": "...",
  "options": {
    "clean_mode": "drop_database"
  }
}
```

## Cluster Backup (`pg_dumpall`) [#cluster-backup-pg_dumpall]

Use the cluster mode when you need to back up the **entire instance**: all databases together with global objects such as roles, ownership and grants. This is the recommended choice when advanced roles and ownership are configured at the database cluster level, since a single `pg_dump` does not capture cluster-wide global objects.

<Callout type="info">
  User specified in the configuration must be a superadmin for `pg_dumpall` to dump all databases and global objects.
</Callout>

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `postgresql-cluster` 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.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "Database - PostgreSQL Cluster",
      "type": "postgresql-cluster",
      "host": "postgres",
      "port": 5432,
      "username": "postgres",
      "password": "mysecretpassword",
      "database": "app_db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Specific Parameters:**

    * **username**: (Required) Must be a superuser to dump all databases and global objects.
    * **database**: (Optional) The connection database used to run `pg_dumpall`. Defaults to `"postgres"` if omitted. This does **not** limit the dump scope - `pg_dumpall` always dumps every database in the instance regardless of this value.
  </Tab>
</Tabs>

<Callout type="warning">
  Cluster backups can be significantly larger and slower than single-database backups, since every database in the instance is included. Restoring a `pg_dumpall` output recreates roles and ownership globally.
</Callout>

## 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:
```

<Callout type="info">
  Note that in this example, the host (`host`) to enter in the agent configuration will be `postgres` (the service name), not `localhost`.
</Callout>


# Redis 



The agent will use `redis-cli` to perform backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `redis` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ### With Authentication [#with-authentication]

    ```json title="databases.json"
    {
      "name": "Redis Database Auth",
      "type": "redis",
      "host": "db-redis-auth",
      "port": 6379,
      "username": "username",
      "password": "password",
      "generated_id": "..."
    }
    ```

    ### Without Authentication [#without-authentication]

    ```json title="databases.json"
    {
      "name": "Redis Database",
      "type": "redis",
      "host": "db-redis",
      "port": 6379,
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

```yaml title="docker-compose.yml"
services:

    db-redis:
        image: redis:latest
        container_name: db-redis
        ports:
          - "6379:6379"
        volumes:
          - redis-data:/data
        command: [ "redis-server", "--appendonly", "yes" ]
        networks:
          - portabase

    db-redis-auth:
        image: redis:latest
        container_name: db-redis-auth
        ports:
          - "6380:6379"
        volumes:
          - redis-data-auth:/data
        environment:
          - REDIS_PASSWORD=<your-password>
        command: [ "redis-server", "--requirepass", "<your-password>", "--appendonly", "yes" ]
        networks:
          - portabase

    agent:
        image: portabase/agent:latest
        # ... agent configuration ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  redis-data-auth:
  redis-data:
```

## Important: Localhost and Docker [#important-localhost-and-docker]

<Callout type="warn">
  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.

  Try this: `"host": "host.docker.internal"` (replace host in config.json, toml) or `"host": "db-redis"` (if using Docker Compose).
</Callout>


# SQLite 



## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `sqlite` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ```json title="databases.json"
    {
      "name": "SQLite - 1",
      "type": "sqlite",
      "host": "db-sqlite",
      "path": "/sqlite-data/workspace/data/app.db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

Example with a SQLite image.

```yaml title="docker-compose.yml"
services:

    sqlite:
      container_name: db-sqlite
      image: keinos/sqlite3
      volumes:
        - sqlite-data:/workspace/data
      working_dir: /workspace
      command: tail -f /dev/null
      stdin_open: true
      tty: true

    agent:
        image: portabase/agent:latest
        volumes:
          - ./databases.json:/config/config.json
        # Map data sqlite folder in order to access it then in agent container
          - sqlite-data:/sqlite-data/workspace/data
        # ... agent configuration ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  sqlite-data:

```

<Callout type="warn">
  If you use a local SQLite database, you only have to map it in agent volumes `/var/lib/myapp:/sqlite-data/workspace/data`
</Callout>


# Valkey 



The agent will use `valkey-cli` to perform backups.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    When running `portabase db add`, select `valkey` as the database type.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    In your `databases.json` (or `.toml`) file, configure the following block.

    ### With Authentication [#with-authentication]

    ```json title="databases.json"
    {
      "name": "Valkey Database Auth",
      "type": "valkey",
      "host": "db-valkey-auth",
      "port": 6379,
      "username": "username",
      "password": "password",
      "generated_id": "..."
    }
    ```

    ### Without Authentication [#without-authentication]

    ```json title="databases.json"
    {
      "name": "Valkey Database",
      "type": "valkey",
      "host": "db-valkey",
      "port": 6379,
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose Example [#docker-compose-example]

```yaml title="docker-compose.yml"
services:

    db-valkey:
        image: valkey/valkey
        container_name: db-valkey
        environment:
          - ALLOW_EMPTY_PASSWORD=yes
        ports:
          - '6381:6379'
        volumes:
          - valkey-data:/data
        networks:
          - portabase

    db-valkey-auth:
        image: valkey/valkey
        container_name: db-valkey-auth
        command: >
          --requirepass "supersecurepassword"
        ports:
          - '6382:6379'
        volumes:
          - valkey-data-auth:/data
        networks:
          - portabase

    agent:
        image: portabase/agent:latest
        # ... agent configuration ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  valkey-data-auth:
  valkey-data:
```

## Important: Localhost and Docker [#important-localhost-and-docker]

<Callout type="warn">
  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.

  Try this: `"host": "host.docker.internal"` (replace host in config.json, toml) or `"host": "db-valkey"` (if using Docker Compose).
</Callout>


# API Introduction 



The Portabase dashboard exposes a REST API for programmatic management of databases and agents. Swagger UI and the OpenAPI specification are also available.

## Enable the API [#enable-the-api]

Set the following environment variables in your dashboard configuration:

```bash
API_ENABLED=true
OPENAPI_ENABLED=true
```

* `API_ENABLED=true` : enables all API routes under `/api/v1`.
* `OPENAPI_ENABLED=true` : enables the OpenAPI specification and Swagger UI. The API must also be enabled for this to work.

## API Documentation [#api-documentation]

Once enabled:

| Resource              | URL               |
| --------------------- | ----------------- |
| Swagger UI            | `/api/v1/docs`    |
| OpenAPI specification | `/api/v1/openapi` |

## Authentication [#authentication]

To create an API token:

1. Go to your **Profile** in the dashboard.
2. Open the **Account** tab.
3. In the **API Token** section, generate a new token.

Tokens are user-level, all API actions inherit the permissions of the associated user.

Use the `x-api-key` header to authenticate your requests:

```http
GET /api/v1/databases
x-api-key: <your-token>
```

<Callout type="info">
  API coverage is being extended. Check the [roadmap](https://github.com/orgs/Portabase/projects/1) for upcoming endpoints.
</Callout>


# Environment Variables 



Portabase provides flexibility through environment variables. These let you customize application behavior, database connection, authentication and storage.

<Callout type="info">
  If you use Docker Compose, set these variables in your `.env` file at the root of the project.
</Callout>

***

## Project [#project]

General instance configuration.

| Variable                       | Type      | Optional | Default                 | Description                                                                                                                                                                                                                                     |
| :----------------------------- | :-------- | :------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROJECT_URL`                  | `string`  | No       | `http://localhost:8887` | Public URL of your dashboard (e.g. `https://backups.my-domain.com`). Important for generated links.                                                                                                                                             |
| `PROJECT_SECRET`               | `string`  | No       | `None`                  | **Critical.** Secret used to encrypt sensitive data. Generate with `openssl rand -hex 32`.                                                                                                                                                      |
| `PROJECT_NAME`                 | `string`  | Yes      | `Portabase`             | Display name in the UI (site title).                                                                                                                                                                                                            |
| `RETENTION_CRON`               | `string`  | Yes      | `0 7 * * *`             | Schedule for automatic deletion of backups according to the retention policies.                                                                                                                                                                 |
| `STALE_BACKUP_THRESHOLD_HOURS` | `number`  | Yes      | `6`                     | Threshold, in hours, after which a backup without a recent successful run is flagged as stale.                                                                                                                                                  |
| `BACKUP_FOLDER_NAME`           | `string`  | Yes      | `backups`               | Folder name for storing backup files in storage channels.                                                                                                                                                                                       |
| `LOG_LEVEL`                    | `string`  | Yes      | `info`                  | Controls minimum log level. Options: `debug`, `info`, `warn`, `error`                                                                                                                                                                           |
| `SKIP_ONBOARDING`              | `boolean` | Yes      | `false`                 | Skips the initial onboarding flow on first launch. Set to `true` when the instance is provisioned automatically.                                                                                                                                |
| `AUTH_DEFAULT_USER_NAME`       | `string`  | Yes      | `None`                  | The default user name                                                                                                                                                                                                                           |
| `AUTH_DEFAULT_USER`            | `string`  | Yes      | `None`                  | The default user email                                                                                                                                                                                                                          |
| `AUTH_DEFAULT_PASSWORD`        | `string`  | Yes      | `None`                  | Password must contain at least 8 characters, 1 number, 1 lowercase letter, 1 uppercase letter and 1 special character                                                                                                                           |
| `TELEMETRY`                    | `boolean` | Yes      | `True`                  | Enables anonymous usage metrics collection.                                                                                                                                                                                                     |
| `TUSD_BEHIND_PROXY`            | `boolean` | Yes      | `false`                 | Not always required. Set to `true` when the dashboard runs behind a reverse proxy, so the tusd upload server trusts `X-Forwarded-*` headers and generates correct upload URLs. May resolve upload issues depending on your proxy configuration. |

<Callout type="warning">
  In case you want to seed the default user using .env variables, use AUTH\_DEFAULT\_USER\_NAME, AUTH\_DEFAULT\_USER, and AUTH\_DEFAULT\_PASSWORD. These 3 variables must be filled.
</Callout>

***

## API & MCP [#api--mcp]

Controls programmatic access to your dashboard.

| Variable          | Type      | Optional | Default | Description                                                                                                            |
| :---------------- | :-------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------------- |
| `API_ENABLED`     | `boolean` | Yes      | `false` | Enables all REST API routes under `/api/v1`. Required for both OpenAPI and MCP.                                        |
| `OPENAPI_ENABLED` | `boolean` | Yes      | `false` | Enables the OpenAPI specification and Swagger UI at `/api/v1/openapi` and `/api/v1/docs`. Requires `API_ENABLED=true`. |
| `MCP_ENABLED`     | `boolean` | Yes      | `false` | Enables the MCP server at `/api/v1/mcp` for AI assistant integrations. Requires `API_ENABLED=true`.                    |

***

## Database [#database]

Configuration for the internal Portabase PostgreSQL connection.

| Variable       | Type     | Optional | Default | Description                                                                                                                                                                                     |
| :------------- | :------- | :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | `string` | Yes      | `None`  | Database URL (e.g., `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public`). If not specified, the internal database will be used. |

***

## Email (SMTP) [#email-smtp]

Configuration for transactional email delivery (alerts, invitations).

<Callout type="warning">
  If no configuration is provided, email-related features will be limited (no password reset, no email verification).
</Callout>

| 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` |                                                       |


# Reverse Proxy 



By default, the Portabase Dashboard listens on `http://localhost:8887`. To make it accessible from the outside (e.g. `portabase.example.com`) and secure it with HTTPS, use a **Reverse Proxy**.

***

<Tabs items="[&#x22;Traefik V3&#x22;, &#x22;Nginx&#x22;, &#x22;GoDoxy&#x22;]">
  <Tab value="Traefik V3">
    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
        environment:
            - TZ=Europe/Paris
        expose:
          - 80
        volumes:
          - portabase-data:/data
        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-data:

    networks:
      traefik_network:
      external: true
    ```

    <Callout type="warn" title="Name conflicts">
      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...`
    </Callout>
  </Tab>

  <Tab value="Nginx">
    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. WebSocket variable [#2-websocket-variable]

    The dashboard uses WebSockets. Nginx has no built-in variable to forward the `Connection` header only when
    needed, so declare one in the `http` block (for example in `/etc/nginx/conf.d/upgrade.conf`):

    ```nginx title="/etc/nginx/conf.d/upgrade.conf"
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    ```

    <Callout type="warn" title="Do not hardcode Connection &#x22;upgrade&#x22;">
      Setting `proxy_set_header Connection "upgrade"` on every request breaks keepalive to the upstream. The
      `map` above sends `upgrade` for WebSocket requests and `close` for the rest.
    </Callout>

    ### 3. Nginx server blocks [#3-nginx-server-blocks]

    A complete setup with an HTTP → HTTPS redirect, HTTP/2 and WebSocket support.

    ```nginx title="/etc/nginx/sites-available/portabase"
    server {
        listen 80;
        http2 on;

        server_name portabase.example.com;

        return 301 https://portabase.example.com$request_uri;
    }

    server {
        listen 443 ssl;
        http2 on;
        server_name portabase.example.com;

        include /etc/nginx/snippets/ssl.conf;

        location / {
            proxy_pass http://127.0.0.1:8887;

            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_set_header        X-Scheme $scheme;
            proxy_set_header        Upgrade $http_upgrade;
            proxy_set_header        Connection $connection_upgrade;

            proxy_read_timeout 120s;
            proxy_send_timeout 60s;
            proxy_connect_timeout 10s;
        }
    }
    ```

    <Callout title="Adapt to your setup">
      * `proxy_pass http://127.0.0.1:8887` matches step 1. If Nginx itself runs in Docker on the same network as
        the dashboard, use the container name instead: `proxy_pass http://portabase-app:80`.
      * `/etc/nginx/snippets/ssl.conf` holds your certificate and TLS settings (`ssl_certificate`,
        `ssl_certificate_key`, …). Certbot generates the equivalent lines directly in the server block.
    </Callout>

    ### 4. Enable the site [#4-enable-the-site]

    ```bash
    ln -s /etc/nginx/sites-available/portabase /etc/nginx/sites-enabled/
    nginx -t && systemctl reload nginx
    ```
  </Tab>

  <Tab value="GoDoxy">
    🚧 Work in progress 🚧
  </Tab>
</Tabs>

***

## `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:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# User Guide 

































***

## Understanding the Architecture [#understanding-the-architecture]

Portabase runs as two separately deployed components.

**The Dashboard** centralizes configuration: agents, databases, backup schedules, retention, alerts and storage channels.

**The Agent** is a Rust binary installed on the same network as your databases. It is responsible for:

* detecting and reporting your databases automatically
* executing backups according to the defined schedule
* sending backup files to your storage destinations
* reporting logs and status back to the dashboard

<Callout type="info">
  The dashboard never connects directly to your databases. Everything goes
  through the agent. This architecture lets you protect databases on a private
  network or behind a firewall without exposing your servers.
</Callout>

<img alt="Dashboard → Agent → Databases architecture" src="__img0" />

The agent regularly sends a **ping** to the dashboard. This ping transmits the list of available databases, agent status and operation results. In return, the dashboard sends instructions (schedules, restore orders, etc.).

### Entity Hierarchy [#entity-hierarchy]

```
Organisation
├── Agents
│   └── Databases (discovered automatically)
│       ├── Project assignment (optional)
│       ├── Backup policy (cron)
│       ├── Retention policy
│       ├── Alert policies  ──→  Notification channels
│       └── Storage policies ──→ Storage channels
├── Projects (logical grouping)
├── Notification channels
└── Storage channels
```

***

## Managing Agents [#managing-agents]

An agent represents one instance of the Portabase Agent program deployed on a server. A single agent can manage multiple databases on the same server. If you have databases on multiple servers, create one agent per server.

### Creating an Agent [#creating-an-agent]

<Callout type="warn">
  Prerequisite: you must be `owner` or `admin` of the organisation.
</Callout>

<img alt="Agents list page" src="__img1" />

<Steps>
  <Step>
    Go to **Organisation > Settings > Agents** and click **Add agent**.
  </Step>

  <Step>
    Fill in the fields:

    * **Name** - human-readable identifier (e.g. `Production Server EU`, `Dev Machine`)
    * **Description** - free notes about this agent's role

        <img alt="Create agent dialog" src="__img2" />

    Confirm. The agent is created and an **Edge Key** is generated automatically.
  </Step>

  <Step>
    Copy the **Edge Key** from the agent detail page (button **Show Key**), then paste it into the Portabase Agent Rust configuration on your server.

        <img alt="Registration & Setup panel with Edge Key" src="__img3" />
  </Step>
</Steps>

### Verifying the Connection [#verifying-the-connection]

On next startup, the agent pings the dashboard. You'll know it's connected when:

* the **Last Contact** column shows a recent timestamp
* the status turns green in the interface

From the first ping, the agent transmits the list of all databases it can see. &#x2A;*These databases appear automatically in the dashboard - you don't need to create them manually.**

### Monitoring Agent Health [#monitoring-agent-health]

From the agent detail page, the **Health** tab shows a 12-hour ping history as a grid. Each cell represents one ping: green if received, red if missed.

<img alt="Agent health grid - 12h ping history" src="__img4" />

***

## Organising Databases with Projects [#organising-databases-with-projects]

A project is a **logical folder** for grouping databases. It has no effect on backup execution - it is purely an organisational tool.

Typical uses: group all databases for an application, separate production from staging, organise by team or client.

### Creating a Project [#creating-a-project]

<Callout type="warn">
  Prerequisite: you must be `owner` or `admin` of the organisation.
</Callout>

1. Go to **Organisation > Projects**
2. Click **New project**
3. Give the project a name, choose databases and confirm

<img alt="Create project dialog" src="__img5" />

***

## Configuring a Database [#configuring-a-database]

### How Databases Appear [#how-databases-appear]

Databases are not created manually. They appear automatically as soon as the connected agent detects them via its ping.

If a database doesn't appear, check that:

* the agent is connected (green status, recent **Last Contact**)
* the database is accessible from the agent's server

### Configuration Tabs [#configuration-tabs]

From the database detail page (&#x2A;*Projects > \[project] > \[database]**):

| Tab          | Content                           |
| :----------- | :-------------------------------- |
| **Overview** | KPIs, status, general information |
| **Backups**  | Backup list, manual actions       |
| **Restore**  | Available restore operations      |
| **Schedule** | Cron schedule + retention         |
| **Alerts**   | Alert policies                    |
| **Storage**  | Storage policies                  |
| **Logs**     | Detailed operation logs           |

<img alt="Database header with navigation tabs" src="__img6" />

### Triggering a Manual Backup [#triggering-a-manual-backup]

From the **Backups** tab, click **Backup now**. The backup moves to `waiting` status, then `ongoing` as soon as the agent picks it up at the next ping.

<img alt="Backup now button" src="__img7" />

| Status    | Meaning                                     |
| :-------- | :------------------------------------------ |
| `waiting` | Waiting to be picked up by the agent        |
| `ongoing` | Currently running                           |
| `success` | Completed successfully                      |
| `failed`  | Failed - check the **Logs** tab for details |

### Importing an External Backup [#importing-an-external-backup]

1. From the **Backups** tab, click **Import**
2. Drag and drop your file or browse your filesystem

<img alt="Import backup dialog" src="__img8" />

### Restoring a Database [#restoring-a-database]

<Callout type="warn">
  Restoration overwrites the current data in the target database. Make sure you
  have a recent backup before restoring. Restore is not available for Redis and
  Valkey.
</Callout>

From the **Restore** tab, two options:

* **From an existing backup** - choose a backup from the list and click **Restore**
* **From external storage** - select a file available in one of your storage channels

***

## Configuring Channels [#configuring-channels]

Channels are connectors to external services, used in two contexts: **notifications** and **storage**. They are configured at the organisation level and can be reused across multiple databases.

<Tabs items="[&#x22;Notification channels&#x22;, &#x22;Storage channels&#x22;]">
  <Tab value="Notification channels">
    **Creating a channel:**

    1. **Organisation > Notifications > Channels > Add channel**
    2. Choose the provider

        <img alt="Choose notification provider" src="__img9" />

    3. Fill in the connection details
    4. Give the channel a recognisable name (e.g. `Slack #ops-alerts`)
    5. Test with the **Test** button
    6. Enable the channel

    <Callout type="info">
      A disabled channel receives no notifications even if alert policies point to
      it. Use this flag to temporarily silence a channel without losing its
      configuration.
    </Callout>
  </Tab>

  <Tab value="Storage channels">
    **Creating a channel:**

    1. **Organisation > Storages > Channels > Add channel**
    2. Choose the provider

        <img alt="Choose storage provider" src="__img10" />

    3. Fill in the connection parameters
    4. Give the channel a name (e.g. `S3 Backup Bucket EU`)
    5. Enable the channel

    <Callout type="warn">
      The **Local** provider stores files on the agent's server, not the dashboard
      server. If the agent moves to another server or the disk changes, locally
      stored backups will no longer be accessible.
    </Callout>
  </Tab>
</Tabs>

***

## Setting Up Policies [#setting-up-policies]

Policies are configured at the database level. A database can have multiple policies of different types.

### Backup Schedule (cron) [#backup-schedule-cron]

**Where to configure:** database detail page > **Schedule** tab

The schedule is a cron expression that defines when automatic backups run.

```
┌──────── minute (0–59)
│  ┌───── hour (0–23)
│  │  ┌── day of month (1–31)
│  │  │  ┌─ month (1–12)
│  │  │  │  ┌ day of week (0–7, 0 and 7 = Sunday)
│  │  │  │  │
*  *  *  *  *
```

| Expression    | Result                     |
| :------------ | :------------------------- |
| `0 2 * * *`   | Every day at 2 AM          |
| `0 */6 * * *` | Every 6 hours              |
| `0 2 * * 1`   | Every Monday at 2 AM       |
| `0 2 1 * *`   | 1st of every month at 2 AM |

Need help building an expression? Use [crontab.guru](https://crontab.guru/?utm_source=portabase.io).

<img alt="Backup schedule configuration" src="__img11" />

To disable automatic backups, switch to **Manual** mode. You can still trigger backups manually from the **Backup now** button.

<Callout type="warn">
  Deleting the schedule also deletes the associated retention policy. If you
  add a schedule later, you will need to reconfigure retention.
</Callout>

### Retention Policy [#retention-policy]

**Where to configure:** database detail page > **Schedule** tab > **Retention** section

**Prerequisite:** an active cron schedule must exist on the database.

<Tabs items="[&#x22;count&#x22;, &#x22;days&#x22;, &#x22;gfs&#x22;]">
  <Tab value="count">
    Keeps only the N most recent backups. Older backups are deleted as new ones are created.

    | Parameter         | Min | Max | Default |
    | :---------------- | :-: | :-: | :-----: |
    | Number of backups |  1  | 100 |    7    |

    Ideal for development databases or when disk space is limited.
  </Tab>

  <Tab value="days">
    Keeps all backups from the past N days.

    | Parameter      | Min |  Max  | Default |
    | :------------- | :-: | :---: | :-----: |
    | Number of days |  1  | 3,650 |    30   |

    Ideal for databases with legal retention requirements over a specific period.
  </Tab>

  <Tab value="gfs">
    The **Grandfather-Father-Son** strategy keeps the best representative of each time period to maximise historical coverage.

    | Level       | What is kept                     | Default | Max |
    | :---------- | :------------------------------- | :-----: | :-: |
    | **Daily**   | The last N days                  |    7    |  31 |
    | **Weekly**  | Last backup of the last N weeks  |    4    |  52 |
    | **Monthly** | Last backup of the last N months |    12   | 120 |
    | **Yearly**  | Last backup of the last N years  |    3    |  50 |

    With default values: maximum 26 backups covering 3 years of history.

    Ideal for production databases with compliance or long-term audit requirements.
  </Tab>
</Tabs>

<Callout type="info">
  There can only be one retention policy per database. Creating a new one
  automatically replaces the existing one.
</Callout>

<img alt="Backup retention policy configuration" src="__img12" />

### Alert Policies [#alert-policies]

**Where to configure:** database detail page > **Alerts** tab

**Prerequisite:** at least one notification channel must be configured and enabled.

| Event                   | When is it triggered?                                  |
| :---------------------- | :----------------------------------------------------- |
| `error_backup`          | A backup fails                                         |
| `success_backup`        | A backup completes successfully                        |
| `error_restore`         | A restore fails                                        |
| `success_restore`       | A restore completes successfully                       |
| `error_health_database` | The agent reports the database is no longer accessible |

<Callout type="warn">
  The `weekly_report` event is not yet implemented. Want to help? See the
  [Contributing](/docs/contributing) guide.
</Callout>

**Creating a policy:**

1. **Alerts** tab > **Add policy**
2. Select the target notification channel
3. Check the events to monitor
4. Enable and save

<img alt="Notification policies panel" src="__img13" />

<Callout type="info">
  You can create multiple policies on the same database, for example, Slack for
  errors and SMTP for successes. Each policy can be individually disabled
  without deleting it.
</Callout>

### Storage Policies [#storage-policies]

**Where to configure:** database detail page > **Storage** tab

**Prerequisite:** at least one storage channel must be configured and enabled.

**Creating a policy:**

1. **Storage** tab > **Add policy**
2. Select the target storage channel
3. Enable and save

<img alt="Storage policies panel" src="__img14" />

You can create multiple storage policies on the same database. The backup file will be sent **simultaneously** to all active destinations.

From the **Backups** tab, each backup shows the send status per channel:

| Status    | Meaning                                 |
| :-------- | :-------------------------------------- |
| `pending` | Waiting to be sent                      |
| `success` | Sent (path, size and checksum verified) |
| `failed`  | Send failed for this channel            |

***

## Quick Reference [#quick-reference]

| What you're looking for    | Path                                                           |
| :------------------------- | :------------------------------------------------------------- |
| Create an agent            | **Settings > Agents > Add agent**                              |
| View an agent's key        | **Settings > Agents > \[agent] > Show Key**                    |
| Create a project           | **Projects > New project**                                     |
| View an agent's databases  | **Settings > Agents > \[agent] > Databases**                   |
| Configure backup schedule  | **Projects > \[project] > \[database] > Schedule**             |
| Configure retention        | **Projects > \[project] > \[database] > Schedule > Retention** |
| Configure alerts           | **Projects > \[project] > \[database] > Alerts**               |
| Configure backup storage   | **Projects > \[project] > \[database] > Storage**              |
| Add a notification channel | **Organisation > Notifications > Channels > Add channel**      |
| Add a storage channel      | **Organisation > Storages > Channels > Add channel**           |
| Notification logs          | **Organisation > Notifications > Logs**                        |
| Agent health               | **Settings > Agents > \[agent] > Health**                      |

***

<Cards>
  <Card href="/docs/dashboard/usage/storage/local" title="Configure Storage" icon="<DatabaseIcon />" description="Local storage, S3, Google Drive, Azure Blob Storage." />

  <Card href="/docs/dashboard/usage/notifications/slack" title="Configure Notifications" icon="<BellIcon />" description="Slack, Discord, Telegram, Email and many more channels." />
</Cards>


# MCP Server 



The Portabase MCP server exposes your dashboard over the [Model Context Protocol](https://modelcontextprotocol.io/), allowing AI assistants (Claude, Cursor, Windsurf, etc.) to manage databases, agents, and backups through natural language.

## Prerequisites [#prerequisites]

* Portabase dashboard running with both `API_ENABLED=true` and `MCP_ENABLED=true`
* An API token (see [API Introduction](/docs/dashboard/api/introduction))
* Node.js 18+ on the machine running your AI assistant

## Enable MCP [#enable-mcp]

Set both environment variables before starting your dashboard:

```bash
API_ENABLED=true
MCP_ENABLED=true
```

* `API_ENABLED=true`: enables all API routes under `/api/v1`
* `MCP_ENABLED=true`: enables the MCP server at `/api/v1/mcp`

## Connection [#connection]

Add the following to your AI assistant's MCP configuration, replacing the URL and API key with your own:

<Tabs items="[&#x22;Claude Desktop&#x22;, &#x22;Cursor / Windsurf&#x22;, &#x22;Other&#x22;]">
  <Tab value="Claude Desktop">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json
    {
      "mcpServers": {
        "portabase": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://your-dashboard.example.com/api/v1/mcp",
            "--header",
            "x-api-key: YOUR_API_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Cursor / Windsurf">
    Open **Settings → MCP Servers** and add:

    ```json
    {
      "portabase": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://your-dashboard.example.com/api/v1/mcp",
          "--header",
          "x-api-key: YOUR_API_TOKEN"
        ]
      }
    }
    ```
  </Tab>

  <Tab value="Other">
    Any MCP-compatible client that accepts a JSON config:

    ```json
    {
      "mcpServers": {
        "portabase": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://your-dashboard.example.com/api/v1/mcp",
            "--header",
            "x-api-key: YOUR_API_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  Never commit your API token to version control. Use your environment's secret management to inject it where possible.
</Callout>

## Verify the connection [#verify-the-connection]

Restart your AI assistant. Ask it:

> "List my Portabase databases"

A successful response confirms the MCP server is connected.

## Available Tools [#available-tools]

See the [Tools reference](/docs/dashboard/mcp/tools) for the full list of operations.


# MCP Tools Reference 



The Portabase MCP server exposes 12 tools grouped into three categories: **Agents**, **Databases**, and **Backups**.

***

## Agents [#agents]

### `list_agents` [#list_agents]

List all agents accessible to the authenticated user.

**Parameters:** none

**Returns:** Array of agent objects.

***

### `get_agent` [#get_agent]

Get details for a specific agent, including its associated databases.

| Parameter | Type   | Required | Description |
| :-------- | :----- | :------: | :---------- |
| `id`      | string |    Yes   | Agent ID    |

**Returns:** Agent object with associated databases.

***

### `create_agent` [#create_agent]

Create a new agent, optionally scoped to an organization.

| Parameter        | Type          | Required | Description                           |
| :--------------- | :------------ | :------: | :------------------------------------ |
| `name`           | string        |    Yes   | Agent name (min 1 character)          |
| `organizationId` | string (UUID) |    No    | Organization ID to scope the agent to |

**Returns:** Created agent object.

***

### `delete_agent` [#delete_agent]

Delete an agent by ID.

| Parameter | Type   | Required | Description |
| :-------- | :----- | :------: | :---------- |
| `id`      | string |    Yes   | Agent ID    |

**Returns:** Confirmation message.

***

### `get_agent_key` [#get_agent_key]

Get the edge key for an agent. This key is used by the agent binary to authenticate with Portabase.

| Parameter | Type   | Required | Description |
| :-------- | :----- | :------: | :---------- |
| `id`      | string |    Yes   | Agent ID    |

**Returns:** Object containing the edge key.

<Callout type="warn">
  The edge key grants the agent access to your Portabase instance. Treat it like a password and never expose it in logs or version control.
</Callout>

***

## Databases [#databases]

### `list_databases` [#list_databases]

List all databases accessible to the authenticated user.

**Parameters:** none

**Returns:** Array of database objects.

***

### `get_database` [#get_database]

Get details for a specific database.

| Parameter | Type   | Required | Description |
| :-------- | :----- | :------: | :---------- |
| `id`      | string |    Yes   | Database ID |

**Returns:** Database object.

***

### `get_database_status` [#get_database_status]

Get the current status of a database, including the latest backup and restoration state.

| Parameter | Type   | Required | Description |
| :-------- | :----- | :------: | :---------- |
| `id`      | string |    Yes   | Database ID |

**Returns:** Status object with backup and restore state.

***

## Backups [#backups]

### `list_backups` [#list_backups]

List all backups for a specific database, ordered by most recent first.

| Parameter    | Type   | Required | Description |
| :----------- | :----- | :------: | :---------- |
| `databaseId` | string |    Yes   | Database ID |

**Returns:** Array of backup objects.

***

### `get_backup` [#get_backup]

Get details for a specific backup, including its storage locations.

| Parameter    | Type   | Required | Description |
| :----------- | :----- | :------: | :---------- |
| `databaseId` | string |    Yes   | Database ID |
| `backupId`   | string |    Yes   | Backup ID   |

**Returns:** Backup object with `storages` array. Use the `id` values from `storages` as `backupStorageId` in `trigger_restore`.

***

### `trigger_backup` [#trigger_backup]

Trigger an immediate backup for a database.

| Parameter    | Type   | Required | Description |
| :----------- | :----- | :------: | :---------- |
| `databaseId` | string |    Yes   | Database ID |

**Returns:** Backup job object.

<Callout type="info">
  Returns `409 Conflict` if a backup is already running for this database.
</Callout>

***

### `trigger_restore` [#trigger_restore]

Trigger a database restore from a specific backup storage. Use `get_backup` to find available `backupStorageId` values.

| Parameter         | Type          | Required | Description                                         |
| :---------------- | :------------ | :------: | :-------------------------------------------------- |
| `databaseId`      | string        |    Yes   | Database ID                                         |
| `backupId`        | string (UUID) |    Yes   | Backup ID                                           |
| `backupStorageId` | string (UUID) |    Yes   | Backup storage ID (from `get_backup` storages list) |

**Returns:** Restore job object.

<Callout type="info">
  Returns `409 Conflict` if a restore is already running for this database.
</Callout>


# Global Configuration 



These variables control the general authentication behavior and account security on your Portabase instance.

## General Settings [#general-settings]

<TypeTable
  type="{
  AUTH_EMAIL_PASSWORD_ENABLED: {
    description: &#x22;Completely disables traditional email and password login.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_SIGNUP_ENABLED: {
    description: &#x22;Allows or disallows the creation of new accounts by visitors.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_PASSKEY_ENABLED: {
    description: &#x22;Enables support for Passkeys (WebAuthn) for passwordless login.&#x22;,
    type: 'boolean',
    default: 'false',
  },
  AUTH_SYNC_OIDC_ROLES_ON_LOGIN: {
    description: &#x22;Updates user roles at each OIDC login based on remote groups.&#x22;,
    type: 'boolean',
    default: 'true',
  },
    TRUSTED_DOMAINS: {
        description: &#x22;Specify trusted origins, separate with commas&#x22;,
        type: 'string',
        default: null,
    },
}"
/>

<Callout type="warn">
  If you disable `AUTH_EMAIL_PASSWORD_ENABLED`, make sure you have configured at least one functional OAuth2 or OIDC provider, otherwise you might lose access to your instance.
</Callout>

## Account Linking [#account-linking]

These variables control how a Portabase account is associated with an OAuth2 or OIDC provider. They apply to every configured provider.

<TypeTable
  type="{
  AUTH_ALLOW_LINKING: {
    description: &#x22;Allows associating an OAuth2 or OIDC provider with an existing account. When disabled, a provider can only be used to sign in to an account it is already linked to.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_ALLOW_UNLINKING: {
    description: &#x22;Allows a user to remove a linked provider from their own account, from the dashboard, once the link is set.&#x22;,
    type: 'boolean',
    default: 'true',
  },
}"
/>

<Callout type="warn">
  Keep `AUTH_ALLOW_UNLINKING` at `false` when the provider is the only way into an account: with `AUTH_EMAIL_PASSWORD_ENABLED` disabled and no passkey registered, a user who unlinks their last provider locks themselves out.
</Callout>

## Security Recommendations [#security-recommendations]

* **Passkeys**: We recommend enabling `AUTH_PASSKEY_ENABLED` to provide a more secure and smooth login experience.
* **Registration**: For a private instance, set `AUTH_SIGNUP_ENABLED` to `false` after creating your administrator accounts.
* **Account linking**: On a shared instance, set `AUTH_ALLOW_LINKING` to `false` unless your provider verifies email addresses. A provider that returns an unverified address could otherwise be used to take over an existing account with the same email.


# Apprise 



[Apprise](https://github.com/caronc/apprise) is a notification gateway that relays a single message to 100+ services (Discord, Telegram, Slack, email, ntfy, Gotify, and many more). Portabase talks to a self-hosted [Apprise API](https://github.com/caronc/apprise-api) server using a **persistent configuration**.

## Configuration on your Apprise API server [#configuration-on-your-apprise-api-server]

<Steps>
  <Step>
    Run an Apprise API instance (for example the `caronc/apprise` Docker image) and note its base URL (e.g., `http://localhost:8000`).
  </Step>

  <Step>
    Register a **persistent configuration** under a key of your choice. Portabase sends to `POST /notify/{key}`, so this key must exist on the server. Add the target service URLs (Discord, Telegram, etc.) to that configuration.
  </Step>

  <Step>
    Copy the **config key** you chose (e.g., `my-alerts`).
  </Step>
</Steps>

<Callout type="info">
  Portabase does not store the destination service URLs. They live in the persistent configuration on your Apprise
  server; Portabase only references it by its config key.
</Callout>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Apprise**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the following information:

    * **Channel Name**: A label for this channel in Portabase.
    * **Apprise Server URL**: The base URL of your Apprise API server (e.g., `http://localhost:8000`).
    * **Config Key**: The persistent config key registered on your server (e.g., `my-alerts`).
    * **Custom Headers** (Optional): Add headers if your server sits behind a reverse proxy or basic auth (e.g., `Authorization`).

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/apprise/configuration.png" alt="Apprise channel configuration" width="493" height="654" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. The message should be relayed to every service in your Apprise configuration.
  </Step>
</Steps>


# Discord 



Discord notifications use the platform's native Webhook system to post messages to a specific channel.

## Discord server configuration [#discord-server-configuration]

<Steps>
  <Step>
    In Discord, go to **Server Settings > Integrations > Webhooks**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/fr/1.png" alt="Discord configuration" width="1151" height="1079" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Create a new Webhook and copy its **URL**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/fr/2.png" alt="Discord configuration" width="1166" height="1079" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Discord**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the Discord webhook URL obtained earlier (e.g., `https://discord.com/api/webhooks/...`) and click **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/configuration.png" alt="Discord channel configuration" width="504" height="426" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Email (SMTP) 



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]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Email**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    * **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`).

    <Callout type="info">
      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.
    </Callout>

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/smtp/configuration.png" alt="SMTP channel configuration" width="504" height="789" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Gotify 



[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]

<Steps>
  <Step>
    1. Log in to your Gotify instance.
  </Step>

  <Step>
    2. Create a new **Application** (e.g., "Portabase").
  </Step>

  <Step>
    3. Copy the **Token** generated for this application.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Gotify**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

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

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/gotify/configuration.png" alt="Gotify channel configuration" width="504" height="492" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Healthchecks.io 



[Healthchecks.io](https://healthchecks.io) watches for pings that are supposed to arrive on a schedule. If a ping does not arrive in time, it alerts you.

This flips the usual notification model. Slack or Discord tell you when a backup *fails*; Healthchecks tells you when a backup **stops happening at all** — a crashed agent, a paused schedule, a container that never restarted. Those silent failures are the ones you notice too late.

<Callout type="info">
  Healthchecks.io is open source. These steps apply to the hosted service and to a self-hosted instance alike — only
  the ping server URL differs.
</Callout>

## Choosing between a check UUID and a project ping key [#choosing-between-a-check-uuid-and-a-project-ping-key]

Portabase can address your checks in two ways. Pick one before configuring the channel.

|                  | Check UUID          | Project ping key             |
| ---------------- | ------------------- | ---------------------------- |
| Pings            | one single check    | any check, addressed by slug |
| Channels needed  | one per check       | one for every database       |
| Where to find it | on the check's page | in your project settings     |

## Configuration on Healthchecks [#configuration-on-healthchecks]

<Steps>
  <Step>
    Create a check and give it a name, for example `portabase-production`.
  </Step>

  <Step>
    Set the **Period** to the interval between two backups, and the **Grace Time** to how long a backup may be late before you want to be alerted. A daily backup that takes about twenty minutes fits a period of 1 day and a grace time of 1 hour.
  </Step>

  <Step>
    Copy the check's **UUID**, or, if you plan to cover several databases from one channel, copy the **ping key** from your project settings instead.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Healthchecks.io**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the following information:

    * **Channel Name**: A label for this channel in Portabase.
    * **Ping Server URL**: Leave `https://hc-ping.com` as is for the hosted service, or point it at your self-hosted instance.
    * **Check UUID or Ping Key**: The check UUID, or the project ping key when you want to address checks by slug.
    * **Use database name as slug** (Optional): One channel for every database — the slug is derived from the database name of each event. Requires a project ping key, not a check UUID.
    * **Slug** (Optional): The slug to ping. Leave it empty when the field above holds a check UUID.
    * **Create missing checks** (Optional): Adds `?create=1` so a slug with no matching check is created on its first ping. Ignored when pinging a check UUID.

    Then click **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/healthchecks/configuration.png" alt="Healthchecks.io channel configuration" width="448" height="746" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. The check should turn green in Healthchecks within a few seconds.
  </Step>
</Steps>

<Callout type="warn">
  Treat the check UUID and the project ping key like passwords. Anyone who has them can mark your checks as up and
  hide a real outage.
</Callout>


# Microsoft Teams 



Microsoft Teams notifications use an **Incoming Webhook** connector to post messages to a specific channel.

## Microsoft Teams configuration [#microsoft-teams-configuration]

<Steps>
  <Step>
    In Teams, go to the channel you want to notify, then **Channel options > Connectors** (or **Workflows** depending on your tenant).
  </Step>

  <Step>
    Add an **Incoming Webhook** connector, give it a name (e.g., "Portabase"), and copy the generated **Webhook URL**.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Microsoft Teams**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the following information:

    * **Channel Name**: A label for this channel in Portabase.
    * **Teams Webhook URL**: The webhook URL obtained earlier.

    Then click **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/ms-teams/configuration.png" alt="Microsoft Teams channel configuration" width="495" height="412" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. Verify that a test message appears in the selected Teams channel.
  </Step>
</Steps>


# Ntfy 



[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]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **ntfy.sh**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

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

    <Callout type="warn">
      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.
    </Callout>

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/ntfy/configuration.png" alt="Ntfy channel configuration" width="504" height="790" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Pushover 



[Pushover](https://pushover.net) is a service for sending real-time push notifications to your phone, tablet, or desktop.

## Creation of an application on Pushover [#creation-of-an-application-on-pushover]

<Steps>
  <Step>
    Log in to your [Pushover](https://pushover.net) account.
  </Step>

  <Step>
    Go to **Create an Application/API Token** and register a new application (e.g., "Portabase").
  </Step>

  <Step>
    Copy the generated **API Token/Key**.
  </Step>

  <Step>
    On your Pushover dashboard, copy your **User Key** (top right of the page).
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Pushover**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the following information:

    * **Channel Name**: A label for this channel in Portabase.
    * **User Key**: Your personal User Key, or your **Group Key** to notify a team.
    * **App API Token**: The application token created above.
    * **Message Priority** (Optional): Emergency priority repeats every 60 seconds until acknowledged, for at most one hour.
    * **Device Name** (Optional): Target one registered device. Leave it empty to send to all of them.

    Then click **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/pushover/configuration.png" alt="Pushover channel configuration" width="501" height="778" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. The message should appear instantly on your device(s).
  </Step>
</Steps>


# Slack 



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]

<Steps>
  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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**.
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

[//]: # "### 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."

[//]: # "</Step>"

[//]: # "</Steps>"

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Slack**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the Slack webhook URL obtained earlier `https://hooks.slack.com/services/...` and click **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/slack/configuration.png" alt="Slack channel configuration" width="504" height="421" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Telegram 



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]

<Steps>
  <Step>
    Contact [@BotFather](https://t.me/botfather) on Telegram to create a new bot and get your **Token** (e.g.,
    `123456:ABC-DEF1234...`).
  </Step>

  <Step>
    Start a conversation with your bot (click "Start").
  </Step>

  <Step>
    Retrieve your **Chat ID** (you can use a bot like `@userinfobot` to find it).
  </Step>
</Steps>

<Callout type="warn" title="Warning">
  You need to grant the bot the proper permissions (administrator or at least the right to manage topics).
  Otherwise, an error will occur.
</Callout>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Telegram**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the following information:

    * **Bot Token**: The token provided by BotFather.
    * **Chat ID**: The numeric identifier of the conversation or group.
    * **Topic ID** : The numeric identifier of the topic you want to monitor (optional, to filter notifications).

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/telegram/configuration.png" alt="Telegram channel configuration" width="499" height="664" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. Your bot should send you
    a test message immediately.
  </Step>
</Steps>


# Webhook 



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]

<Steps>
  <Step>
    Go to **Notifications > Channels*&#x2A;, click on **+ Add Notification Channel**, and choose **Webhook**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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`.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/webhook/configuration.png" alt="Webhook channel configuration" width="504" height="553" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    To test the configuration, click the channel's edit icon, then click **Test Channel**. Verify that your endpoint responds correctly.
  </Step>
</Steps>


# Azure Blob Storage 



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.

***

## Creation of a Storage Account and Container [#creation-of-a-storage-account-and-container]

<Steps>
  <Step>
    Navigate to the [Azure Portal](https://portal.azure.com) and create a **Storage Account** (or use an existing one).
  </Step>

  <Step>
    Inside the Storage Account, go to **Containers** and create a new container for your backups.
  </Step>

  <Step>
    Go to **Access keys** and note the **Storage account name** and **Key**.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    In **Storage > Channels*&#x2A;, click on **+ Add Storage Channel** and choose **Azure Blob Storage**.
  </Step>

  <Step>
    Enter the storage account name, key, and container name previously noted.
  </Step>

  <Step>
    Click **Add Channel** to finalize the configuration.
  </Step>
</Steps>

***

## Verification [#verification]

1. Restart the dashboard:

```bash
portabase restart .
```

2. Log into the web UI.
3. Trigger a manual backup on an agent.
4. Check your container in the Azure Portal to confirm the backup file exists.


# Google Cloud Storage 



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.

***

## Creation of a Service Account and Bucket [#creation-of-a-service-account-and-bucket]

<Steps>
  <Step>
    Navigate to the [Google Cloud Console](https://console.cloud.google.com) and select your project (or create a new one).
  </Step>

  <Step>
    Go to **Cloud Storage > Buckets** and create a new bucket for your backups. Note the **bucket name**.
  </Step>

  <Step>
    Go to **IAM & Admin > Service Accounts** and create a new service account.
  </Step>

  <Step>
    Assign the **Storage Object Admin** role (`roles/storage.objectAdmin`) to the service account on the bucket.
  </Step>

  <Step>
    In the service account details, go to **Keys > Add Key > Create new key** and select **JSON**. Download the generated key file.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    In **Storage > Channels*&#x2A;, click on **+ Add Storage Channel** and choose **Google Cloud Storage**.
  </Step>

  <Step>
    Enter the bucket name and paste the content of the service account JSON key file.
  </Step>

  <Step>
    Click **Add Channel** to finalize the configuration.
  </Step>
</Steps>

***

## Verification [#verification]

1. Restart the dashboard:

```bash
portabase restart .
```

2. Log into the web UI.
3. Trigger a manual backup on an agent.
4. Check your bucket in the Google Cloud Console to confirm the backup file exists.


# Google Drive 



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]

<Steps>
  <Step>
    Navigate to [Google Cloud Console](https://console.cloud.google.com).
  </Step>

  <Step>
    2. Open the sidebar menu and go to **API & Services > Credentials**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-identifiant.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Click **Create Credentials > OAuth Client ID**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-identifiant-2.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Select **Web Application** as the application type and configure the **Authorized JavaScript origins** and **Authorized redirect URIs** according to your domain.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-oauth-2.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Click **Create**, then note the generated **Client ID** and **Client Secret**.
  </Step>
</Steps>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    In **Storage > Channels*&#x2A;, click on **+ Add Storage Channel** and choose **Google Drive**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/choose-provider.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the credentials previously generated in the Google Cloud Console.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/configuration.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Click **Connect Google Drive** to initiate the OAuth 2.0 authentication flow.
  </Step>

  <Step>
    Click **Add Channel** to finalize the configuration.
  </Step>
</Steps>


# Local Storage 

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 `data` folder:

```yaml title="docker-compose.yml"
services:
  portabase:
    # ...
    volumes:
      - portabase-data:/data
```

Backups are stored inside `/data/private/backups`.


# Object Storage (S3) 



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]

<Tabs items="[&#x22;MinIO&#x22;, &#x22;RustFS&#x22;]">
  <Tab value="MinIO">
    This adds a **MinIO** service to your Docker Compose stack, typically behind Traefik.

    ### Docker Compose changes [#docker-compose-changes]

    <Callout type="info">
      MinIO exposes two ports:

      * **9000**: S3 API (used by Portabase).
      * **9001**: Web Console (admin UI).
    </Callout>

    ```yaml title="docker-compose.yml"
    name: portabase-stack

    services:
      portabase:
        image: portabase/portabase:latest
        container_name: portabase-app
        env_file: .env
        volumes:
          - portabase-data:/data
        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-data:
      postgres-data:
      minio-data:

    networks:
      traefik_network:
        external: true
    ```
  </Tab>

  <Tab value="RustFS">
    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
    ```
  </Tab>
</Tabs>

## Configuration on the dashboard [#configuration-on-the-dashboard]

<Steps>
  <Step>
    In **Storage > Channels*&#x2A;, click on **+ Add Storage Channel** choose **S3**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/choose-provider.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Enter the credentials.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/s3/configuration.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Click **Add Channel** to finalize the configuration.
  </Step>
</Steps>

***

## Verification [#verification]

1. Restart the dashboard:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>

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.


# OAuth2 Configuration 



Portabase supports dynamic addition of OAuth2 providers through a series of `AUTH_SOCIAL_*` variables. This page explains the general operation, available variables, and role management.

## Quick Setup [#quick-setup]

<Steps>
  <Step>
    ### Enable a provider [#enable-a-provider]

    Define a Client ID and Client Secret pair for the provider of your choice (e.g., Google, GitHub).
  </Step>

  <Step>
    ### Deploy [#deploy]

    Apply these environment variables to your Portabase instance.
  </Step>

  <Step>
    ### Configure Callback [#configure-callback]

    Add the redirect URL in the provider's console:
    `https://<your-domain>/api/auth/callback/<providerId>`
  </Step>

  <Step>
    ### Verify [#verify]

    Test the connection from your dashboard login page.
  </Step>
</Steps>

## Configuration Variables [#configuration-variables]

You can configure a "default" provider via `AUTH_SOCIAL_*` or multiple providers via `AUTH_SOCIAL_<NAME>_*`.

<TypeTable
  type="{
  AUTH_SOCIAL_CLIENT: {
    description: &#x22;Client ID provided by the OAuth2 service.&#x22;,
    type: 'string',
  },
  AUTH_SOCIAL_SECRET: {
    description: &#x22;Client Secret provided by the OAuth2 service.&#x22;,
    type: 'string',
  },
  AUTH_SOCIAL_ICON: {
    description: &#x22;Icon to display (Lucide, Iconify identifier, or a link).&#x22;,
    type: 'string',
    default: 'lucide:building',
  },
  AUTH_ALLOW_LINKING: {
    description: &#x22;Allows associating a provider with an existing account.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_ROLE_MAP: {
    description: &#x22;Mapping of remote roles to Portabase roles.&#x22;,
    type: 'string',
  },
}"
/>

Linking a provider to an existing account is controlled by `AUTH_ALLOW_LINKING`, and a user's ability to detach it afterwards by `AUTH_ALLOW_UNLINKING`. Both are described in [Account Linking](/docs/dashboard/configuration/auth/configuration#account-linking).

### Dynamic Providers [#dynamic-providers]

To add multiple services, use the `AUTH_SOCIAL_<PROVIDER>_*` prefix. The `providerId` will be the lowercase version of the prefix.

```bash
# Example for Google
AUTH_SOCIAL_GOOGLE_CLIENT="xxx"
AUTH_SOCIAL_GOOGLE_SECRET="yyy"
AUTH_SOCIAL_GOOGLE_TITLE="Google Enterprise"
```

<Callout type="info">
  If you use standard names (`google`, `github`, `discord`, etc.), Portabase automatically applies the corresponding icon and brand color.
</Callout>

## Role Management [#role-management]

The `AUTH_ROLE_MAP` variable allows mapping your provider's groups/roles to Portabase's internal roles. It uses the format `remote_role:portabase_role`, separated by commas.

* `admin:admin`: Maps the remote "admin" role to the local "admin" role.
* `default:user`: Sets the default role if no match is found.

Full example: `admin:admin,editor:member,default:user`



## Configuration Guides [#configuration-guides]

Choose a provider to see its specific configuration steps:

<Cards>
  <Card title="Google" href="./configurations/google" icon="<Icon icon=&#x22;logos:google-icon&#x22; />" />

  <Card title="GitHub" href="./configurations/github" icon="<Icon icon=&#x22;logos:github-icon&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Discord" href="./configurations/discord" icon="<Icon icon=&#x22;logos:discord-icon&#x22; />" />

  <Card title="Apple" href="./configurations/apple" icon="<Icon icon=&#x22;logos:apple&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="LinkedIn" href="./configurations/linkedin" icon="<Icon icon=&#x22;logos:linkedin-icon&#x22; />" />

  <Card title="X (Twitter)" href="./configurations/x" icon="<Icon icon=&#x22;logos:twitter&#x22; />" />

  <Card title="Reddit" href="./configurations/reddit" icon="<Icon icon=&#x22;logos:reddit-icon&#x22; />" />
</Cards>


# OIDC Configuration 



**OpenID Connect (OIDC)** integration allows connecting Portabase to any compatible identity provider, such as Keycloak, Auth0, Authentik, or Okta.

## Implementation [#implementation]

To configure an OIDC provider, you must define a set of environment variables starting with `AUTH_OIDC_`.

<Steps>
  <Step>
    ### Create the Client [#create-the-client]

    On your identity server (e.g., Keycloak), create a new client of type "OIDC" or "OpenID Connect".
  </Step>

  <Step>
    ### Configure URLs [#configure-urls]

    Define the redirect URL (Redirect URI):
    `https://<your-domain>/api/auth/sso/callback/<providerId>`
  </Step>

  <Step>
    ### Enter Variables [#enter-variables]

    Add the credentials obtained into your Portabase configuration.
  </Step>
</Steps>

## Provider Settings [#provider-settings]

<TypeTable
  type="{
  AUTH_OIDC_ID: {
    description: &#x22;Unique internal identifier (e.g., keycloak). Required.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_TITLE: {
    description: &#x22;Text displayed on the login button.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_DESC: {
    description: &#x22;Short description displayed below the title.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_ICON: {
    description: &#x22;Icon to display (Lucide, Iconify identifier, or a link).&#x22;,
    type: 'string',
  },
  AUTH_OIDC_ISSUER_URL: {
    description: &#x22;Issuer URL for automatic discovery.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_CLIENT: {
    description: &#x22;Client identifier (Client ID). Required.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_SECRET: {
    description: &#x22;Client secret (Client Secret). Required.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_SCOPES: {
    description: &#x22;Requested permissions.&#x22;,
    type: 'string',
    default: 'openid profile email',
  },
  AUTH_OIDC_PKCE: {
    description: &#x22;Enables PKCE flow for added security.&#x22;,
    type: 'boolean',
    default: 'false',
  },
  AUTH_OIDC_HOST: {
    description: &#x22;Internal OIDC server address (for Docker-to-Docker communication).&#x22;,
    type: 'string',
  },
}"
/>

Linking a provider to an existing account is controlled by `AUTH_ALLOW_LINKING`, and a user's ability to detach it afterwards by `AUTH_ALLOW_UNLINKING`. Both are described in [Account Linking](/docs/dashboard/configuration/auth/configuration#account-linking).

## Multiple Providers [#multiple-providers]

Portabase supports configuring multiple OIDC providers simultaneously. To do this, replace the `AUTH_OIDC_` prefix with `AUTH_OIDC_<NAME>_`.

### Example with Pocket [#example-with-pocket]

```bash
AUTH_OIDC_POCKET_ID="portabase-pocketid"
AUTH_OIDC_POCKET_TITLE="Pocket ID"
AUTH_OIDC_POCKET_DESC=""
AUTH_OIDC_POCKET_ICON="https://github.com/user-attachments/assets/4ceb2708-9f29-4694-b797-be833efce17d"
AUTH_OIDC_POCKET_CLIENT="portabase"
AUTH_OIDC_POCKET_SECRET="dkNOnQwhDQVwLxoNbQOkJioMA3sQIPdk"
AUTH_OIDC_POCKET_ISSUER_URL="http://localhost:3055"
AUTH_OIDC_POCKET_HOST="localhost:8080"
```

<Callout type="info">
  Using a specific prefix allows isolating configurations if you use multiple identity servers.
</Callout>

## Configuration Examples [#configuration-examples]

Learn how to integrate specific solutions:

<Tabs items="[&#x22;Keycloak&#x22;, &#x22;PocketID&#x22;]">
  <Tab value="Keycloak">
    Learn how to configure Keycloak with Portabase for enterprise identity management.
    [View the full guide](./examples/keycloak)
  </Tab>

  <Tab value="PocketID">
    A lightweight alternative for self-hosters.
    [View the full guide](./examples/pocketid)
  </Tab>
</Tabs>

## Groups and Roles [#groups-and-roles]

You can restrict Portabase access to a specific group from your OIDC provider via the `ALLOWED_GROUP` variable. If the user does not belong to this group, login will be denied.


# Apple 



Apple integration (Sign in with Apple) allows your users to sign in via their Apple account, offering a secure and privacy-respecting experience.

<Callout type="warning">
  Sign in with Apple requires an **Apple Developer** account (paid program).
</Callout>

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Access Apple Developer Portal [#access-apple-developer-portal]

    Log in to your account on the [Apple Developer Portal](https://developer.apple.com/account/).
  </Step>

  <Step>
    ### Create an Identifier (Services ID) [#create-an-identifier-services-id]

    In **Certificates, Identifiers & Profiles** > **Identifiers**, create a new **Services ID**.

    * Select the **Services IDs** type.
    * Give a name and a unique identifier (e.g., `com.your-domain.portabase`).
  </Step>

  <Step>
    ### Configure Sign In with Apple [#configure-sign-in-with-apple]

    Enable **Sign In with Apple** for this Services ID and click **Configure**.

    * In **Primary App ID**, select your primary application or create one.
    * In **Domains and Subdomains**, add your domain (e.g., `portabase.your-domain.com`).
    * In **Return URLs**, add: `https://portabase.your-domain.com/api/auth/callback/apple`
  </Step>

  <Step>
    ### Create an Authentication Key [#create-an-authentication-key]

    In **Keys**, create a new key.

    * Check **Sign In with Apple**.
    * Associate it with the previously created Services ID.
    * Download the `.p8` file (keep it, it is only downloadable once).
  </Step>

  <Step>
    ### Get Information [#get-information]

    Note the following elements:

    * **Services ID** (your Client ID).
    * **Team ID** (visible in your Apple Developer profile).
    * **Key ID** (displayed in your key details).
  </Step>

  <Step>
    ### Generate Client Secret [#generate-client-secret]

    Apple does not use a static secret but a signed JWT token. Use a script or your pipeline to generate this secret using your `.p8` file.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Add these variables to your configuration:

```bash
AUTH_SOCIAL_APPLE_CLIENT="your-apple-services-id"
AUTH_SOCIAL_APPLE_SECRET="your-apple-signed-jwt"
AUTH_SOCIAL_APPLE_APP_BUNDLE_IDENTIFIER="com.your-domain.portabase"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Discord 



Discord integration is ideal for communities and teams already using Discord for their communication.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create an Application [#create-an-application]

    Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/discord/en/create-new-app.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configure OAuth2 [#configure-oauth2]

    Go to the **OAuth2** > tab:

    * Add the redirect URL: `https://portabase.your-domain.com/api/auth/callback/discord`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/discord/en/oauth2-configuration.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Select Permissions [#select-permissions]

    In **OAuth2** > **URL Generator**, select the `identify` and `email` scopes. These permissions are necessary to create the user account.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/discord/en/oauth2-url-generator.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    Copy the **Client ID**. Click **Reset Secret** to get your **Client Secret**.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Add these lines to your configuration:

```bash
AUTH_SOCIAL_DISCORD_CLIENT="your-discord-client-id"
AUTH_SOCIAL_DISCORD_SECRET="your-discord-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# GitHub 



GitHub integration allows developers and organization members to sign in easily.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Access Developer Settings [#access-developer-settings]

    Log in to GitHub and go to [Developer Settings](https://github.com/settings/developers).

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/github/en/developer-settings.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Register an Application [#register-an-application]

    Click **New OAuth App**:

    * **Application name**: Portabase.
    * **Homepage URL**: Your domain (e.g., `https://portabase.your-domain.com`).
    * **Authorization callback URL**: `https://portabase.your-domain.com/api/auth/callback/github`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/github/en/register-oauth-app.png" alt="GitHub OAuth app creation" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Generate Keys [#generate-keys]

    Click **Register application**. Copy the **Client ID**, then generate a **Client Secret** and store it securely.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Use the `GITHUB` prefix for your variables:

```bash
AUTH_SOCIAL_GITHUB_CLIENT="your-github-client-id"
AUTH_SOCIAL_GITHUB_SECRET="your-github-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Google 



Google integration allows your users to sign-in via their Google or Google Workspace account.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Project Creation [#project-creation]

    Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project or select an existing one.
  </Step>

  <Step>
    ### Consent Screen [#consent-screen]

    Go to **APIs & Services** > **OAuth consent screen**:

    * Choose the user type: **External** (any Google account) or **Internal** (restricted to your Workspace organization).
    * Complete the mandatory information (App name, email).
  </Step>

  <Step>
    ### Credentials Creation [#credentials-creation]

    Open **APIs & Services** > **Credentials**.
    Click **Create Credentials** > **OAuth client ID**.
    Select **Web application**.
  </Step>

  <Step>
    ### Redirect URLs [#redirect-urls]

    In **Authorized redirect URIs**, add the following URL:
    `https://portabase.your-domain.com/api/auth/callback/google`
  </Step>

  <Step>
    ### Get the Keys [#get-the-keys]

    Validate to get your **client ID** and **client secret**.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Add the following variables to your `.env` file or Docker configuration:

```bash
AUTH_SOCIAL_GOOGLE_CLIENT="your-google-client-id"
AUTH_SOCIAL_GOOGLE_SECRET="your-google-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# LinkedIn 



LinkedIn integration allows your users to sign in via their professional LinkedIn profile.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create a LinkedIn Application [#create-a-linkedin-application]

    Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps) and click **Create app**.

    * Fill in the name, organization (or personal profile), and your website URL.
    * Accept the terms of use.

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/linkedin/en/create-an-app.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Enable Sign In with LinkedIn Product [#enable-sign-in-with-linkedin-product]

    In the **Products** tab, find **Sign In with LinkedIn** and click **Request access**. This is necessary to enable authentication.
  </Step>

  <Step>
    ### Configure OAuth 2.0 [#configure-oauth-20]

    Go to the **Auth** tab:

    * In **Authorized redirect URLs for your app**, add: `https://portabase.your-domain.com/api/auth/callback/linkedin`
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    Still in the **Auth** tab, you will find your **Client ID** and **Client Secret**.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Use these variables to configure LinkedIn authentication:

```bash
AUTH_SOCIAL_LINKEDIN_CLIENT="your-linkedin-client-id"
AUTH_SOCIAL_LINKEDIN_SECRET="your-linkedin-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Reddit 



Reddit integration allows your users to sign in via their Reddit account, ideal for community platforms.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Access Reddit Apps [#access-reddit-apps]

    Log in to your account on [Reddit](https://www.reddit.com/) and go to [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps).

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/reddit/en/authorized-applications.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Create an Application [#create-an-application]

    At the bottom of the page, click &#x2A;*Create another app...**:

    * **Name**: Portabase.
    * Select **Web app**.
    * **Description**: Data management platform.
    * **Redirect URI**: `https://portabase.your-domain.com/api/auth/callback/reddit`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/reddit/en/create-application.png" alt="Reddit - Create application" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    After clicking **Create app**, you will see:

    * The **Client ID** (indicated just below the application name).
    * The **Client Secret** (indicated next to the secret field).
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Use these variables to configure Reddit authentication:

```bash
AUTH_SOCIAL_REDDIT_CLIENT="your-reddit-client-id"
AUTH_SOCIAL_REDDIT_SECRET="your-reddit-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# X (Twitter) 



Integration with X (Twitter) allows users to sign in via their social account.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create an Application [#create-an-application]

    Log in to the [Twitter Console](https://console.x.com/) and create a **Project** and an **App**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/twitter/en/developer-enrolment.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### OAuth 2.0 Settings [#oauth-20-settings]

    In **User authentication settings**, enable **OAuth 2.0** and choose the type **Web App, Automated App or Bot**.
  </Step>

  <Step>
    ### URLs and Scopes [#urls-and-scopes]

    * **Callback URL**: `https://portabase.your-domain.com/api/auth/callback/x`
    * **Scopes**: Select at least `users.read` and `tweet.read`.
  </Step>

  <Step>
    ### Credentials [#credentials]

    Save to get your **Client ID** and **Client Secret**.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

You can use the `X` or `TWITTER` prefix depending on your preference (ensure the callback URL matches the lowercase version of the prefix).

```bash
AUTH_SOCIAL_X_CLIENT="your-x-client-id"
AUTH_SOCIAL_X_SECRET="your-x-client-secret"
```

## Restart the Dashboard [#restart-the-dashboard]

After updating your `.env` file, restart the instance:

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Authentik 



The integration of [Authentik](https://github.com/goauthentik/authentik) offers a modern authentication solution, ideal for self-hosting your Portabase instance.

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Configure the application [#configure-the-application]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/1.png" alt="Authentik - Configure the application" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Choose a provider type [#choose-a-provider-type]

    Choose **OAuth2/OpenID Provider**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/2.png" alt="Authentik - Choose a provider type" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configure OAuth2 provider [#configure-oauth2-provider]

    Set the authorized redirect URL to allow returning to Portabase after logging in:

    * **Redirect URLs/Origins**: [https://portabase.your-domain.com/api/auth/sso/callback/authentik](https://portabase.your-domain.com/api/auth/sso/callback/authentik)

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/3.png" alt="Authentik - Configure OAuth2 provider" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configure bindings [#configure-bindings]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/4.png" alt="Authentik - Configure bindings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Review the application and provider [#review-the-application-and-provider]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/5.png" alt="Authentik - Review the application and provider" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

# Environment Variables [#environment-variables]

Configure Portabase with the following values. This example uses the dynamic `AUTH_OIDC_AUTHENTIK_` prefix to isolate the configuration.

```bash
# Identifier and Title
AUTH_OIDC_AUTHENTIK_ID="authentik"
AUTH_OIDC_AUTHENTIK_TITLE="Authentik"
AUTH_OIDC_AUTHENTIK_DESC="Login via my Authentik instance"

# OIDC Credentials
AUTH_OIDC_AUTHENTIK_CLIENT="portabase"
AUTH_OIDC_AUTHENTIK_SECRET="your-authentik-secret"
AUTH_OIDC_AUTHENTIK_ISSUER_URL="https://authentik.your-domain.com/application/o/<authentik-slug>/"
AUTH_OIDC_AUTHENTIK_HOST="authentik:3000" # If in the same Docker network or authentik.your-domain.com

# Advanced Settings
AUTH_OIDC_AUTHENTIK_SCOPES="openid profile email groups"
AUTH_OIDC_AUTHENTIK_PKCE=true

# Role Mapping
AUTH_OIDC_AUTHENTIK_ROLE_MAP="admin:admin,default:user"

AUTH_OIDC_AUTHENTIK_ALLOW_UNLINKING=false

TRUSTED_DOMAINS="https://{Authentik URL}, https://{Portabase URL}"

```

## Specific Endpoints (Optional) [#specific-endpoints-optional]

If automatic discovery doesn't work, you can manually specify the endpoints:

```bash
AUTH_OIDC_AUTHENTIK_DISCOVERY_ENDPOINT="https://authentik.your-domain.com//application/o/<authentik-slug>/.well-known/openid-configuration"
AUTH_OIDC_AUTHENTIK_JWKS_ENDPOINT="https://authentik.your-domain.com//application/o/<authentik-slug>/.well-known/jwks.json"
```


# Keycloak 



[Keycloak](https://www.keycloak.org/) integration offers robust identity management and SSO capabilities for your Portabase instance.

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create a Client [#create-a-client]

    Log in to the Keycloak admin console, choose your Realm, and create a new client:

    * **Client type**: `OpenID Connect`.
    * **Client ID**: `portabase`.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/1.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Authentication and Flow [#authentication-and-flow]

    In **Capability config**, enable **Client authentication** (Confidential Client) and ensure **Standard flow** is selected.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/2.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Login Settings [#login-settings]

    Define the allowed URLs:

    * **Valid redirect URIs**: `https://portabase.your-domain.com/api/auth/sso/callback/your-provider-id`

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/3.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Get the Secret [#get-the-secret]

    Save, then go to the **Credentials** tab to copy your **Client Secret**.
  </Step>

  <div className=" align-middle justify-items-center">
    <Image src="/static/auth/keycloak/4.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
  </div>
</Steps>

## Environment Variables [#environment-variables]

Configure Portabase with the following values:

```bash
# Identifier and Title
AUTH_OIDC_ID="your-provider-id"
AUTH_OIDC_TITLE="Keycloak"
AUTH_OIDC_DESC=""
AUTH_OIDC_ICON=""

# OIDC Credentials
AUTH_OIDC_CLIENT="portabase"
AUTH_OIDC_SECRET="your-keycloak-secret"
AUTH_OIDC_ISSUER_URL="https://keycloak.your-domain.com/realms/your-realm"
AUTH_OIDC_HOST="keycloak.your-domain.com"

# Advanced Settings
AUTH_OIDC_SCOPES="openid profile email"
AUTH_OIDC_PKCE=true

# Role Mapping
AUTH_OIDC_ROLE_MAP="admin:admin,default:pending"

TRUSTED_DOMAINS="https://{Keycloak URL}, https://{Portabase URL}"

```

<Callout type="info">
  If you changed `AUTH_OIDC_ID`, don't forget to adjust the redirect URL in Keycloak accordingly.
</Callout>

## Advanced Configuration [#advanced-configuration]

If automatic discovery doesn't work, you can manually specify the endpoints:

```bash
AUTH_OIDC_POCKET_DISCOVERY_ENDPOINT="https://keycloak.your-domain.com/realms/your-realm/.well-known/openid-configuration"
AUTH_OIDC_POCKET_JWKS_ENDPOINT="https://keycloak.your-domain.com/realms/your-realm/protocol/openid-connect/certs"
```


# PocketID 



The integration of [PocketID](https://github.com/pocket-id/pocket-id) offers a lightweight authentication solution, ideal for self-hosting your Portabase instance.

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create an Application [#create-an-application]

    Log in to the PocketID administration interface and create a new application:

    * **Application name**: `portabase` (or the name of your choice).

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/pocketid/1.png" alt="PocketID application configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Redirect Settings [#redirect-settings]

    Set the authorized redirect URL to allow returning to Portabase after logging in:

    * **Callback URL / Redirect URI**: `https://portabase.your-domain.com/api/auth/sso/callback/pocketid`
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    Save the configuration. You can then copy the **Client ID** and generate your **Client Secret** to add them to your environment variables.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/pocketid/3.png" alt="PocketID getting credentials" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Configure Portabase with the following values. This example uses the dynamic `AUTH_OIDC_POCKET_` prefix to isolate the configuration.

```bash
# Identifier and Title
AUTH_OIDC_POCKET_ID="pocketid"
AUTH_OIDC_POCKET_TITLE="PocketID"
AUTH_OIDC_POCKET_DESC="Login via my PocketID instance"
AUTH_OIDC_POCKET_ICON="https://github.com/user-attachments/assets/4ceb2708-9f29-4694-b797-be833efce17d"

# OIDC Credentials
AUTH_OIDC_POCKET_CLIENT="portabase"
AUTH_OIDC_POCKET_SECRET="your-pocketid-secret"
AUTH_OIDC_POCKET_ISSUER_URL="https://pocketid.your-domain.com"
AUTH_OIDC_POCKET_HOST="pocketid:3000" # If in the same Docker network or pocketid.your-domain.com

# Advanced Settings
AUTH_OIDC_POCKET_SCOPES="openid profile email groups"
AUTH_OIDC_POCKET_PKCE=true

# Role Mapping
AUTH_OIDC_POCKET_ROLE_MAP="admin:admin,default:user"

AUTH_OIDC_POCKET_ALLOW_UNLINKING=false

TRUSTED_DOMAINS="https://{Pocket ID URL},https://{Portabase URL}"


```

<Callout type="info">
  PocketID allows passing user groups. Use `AUTH_OIDC_POCKET_ROLE_MAP` to automatically grant the administrator role to members of your `admin` group.
</Callout>

## Specific Endpoints (Optional) [#specific-endpoints-optional]

If automatic discovery doesn't work, you can manually specify the endpoints:

```bash
AUTH_OIDC_POCKET_DISCOVERY_ENDPOINT="https://pocketid.your-domain.com/.well-known/openid-configuration"
AUTH_OIDC_POCKET_JWKS_ENDPOINT="https://pocketid.your-domain.com/.well-known/jwks.json"
```


# Référence CLI 



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 :

<Steps>
  <Step>
    ### Cloner le dépôt [#cloner-le-dépôt]

    ```bash
    git clone https://github.com/Portabase/cli.git
    cd cli
    ```
  </Step>

  <Step>
    ### Installer les dépendances [#installer-les-dépendances]

    ```bash
    uv sync
    ```
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

<Callout type="tip">
  Vous pouvez également lancer les commandes directement sans installer le paquet en utilisant :

  ```bash
  uv run main.py [COMMAND]
  ```
</Callout>

## 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                                                                             | Défaut       |
| :------------------ | :---: | :-------------------------------------------------------------------------------------- | :----------- |
| `--key <str>`       |  `-k` | La **Edge Key** fournie par le Dashboard. Si omise, elle sera demandée interactivement. | `None`       |
| `--tz <str>`        |       | Fuseau horaire de l'agent.                                                              | `UTC`        |
| `--polling <int>`   |       | Fréquence de scrutation (polling) en secondes.                                          | `5`          |
| `--env <str>`       |       | Environnement de l'application (ex: `production`, `development`).                       | `production` |
| `--data-path <str>` |       | Chemin de données interne au conteneur.                                                 | `/data`      |
| `--start`           |  `-s` | Démarrer l'agent immédiatement après la création.                                       | `False`      |

<Callout type="info" title="Assistant Interactif">
  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 automatiquement.
</Callout>

### `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 <int>` |       | 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.

<Callout type="warn">
  Ces commandes modifient la configuration. Pour qu'elles soient prises en compte, vous devez redémarrer l'agent (`portabase restart <CHEMIN_AGENT>`).
</Callout>

### `db list` [#db-list]

Affiche un tableau récapitulatif des bases de données configurées pour un agent donné.

```bash
portabase db list <CHEMIN_AGENT>
```

### `db add` [#db-add]

Lance un assistant interactif pour ajouter une nouvelle connexion à la configuration.

```bash
portabase db add <CHEMIN_AGENT>
```

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 <CHEMIN_AGENT>
```

***

## 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).

<Callout type="tip" title="Astuce de productivité">
  Si vous êtes déjà dans le dossier du composant, vous pouvez utiliser `.` comme chemin. Exemple : `portabase logs .`
</Callout>

### `start` [#start]

Démarre les conteneurs en mode détaché (arrière-plan). Équivalent à `docker compose up -d`.

```bash
portabase start <CHEMIN>
```

### `stop` [#stop]

Arrête les conteneurs proprement.

```bash
portabase stop <CHEMIN>
```

### `restart` [#restart]

Redémarre l'ensemble des services. Utile après une modification de configuration (`db add` ou changement dans `.env`).

```bash
portabase restart <CHEMIN>
```

### `logs` [#logs]

Affiche les logs des conteneurs.

```bash
portabase logs [OPTIONS] <CHEMIN>
```

**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] <CHEMIN>
```

**Options**

| Option    | Alias | Description                                        |
| :-------- | :---: | :------------------------------------------------- |
| `--force` |  `-f` | Ne demande pas de confirmation avant de supprimer. |

<Callout type="danger">
  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.
</Callout>

***

## Déchiffrement des Sauvegardes (`decrypt`) [#déchiffrement-des-sauvegardes-decrypt]

Déchiffre les fichiers de sauvegarde Portabase `.enc` (AES-256-GCM) et restaure l'archive d'origine. Fonctionne sur un seul fichier ou sur un dossier entier de fichiers `.enc`.

```bash
portabase decrypt [OPTIONS] INPUT_PATH [OUTPUT_PATH]
```

**Arguments**

| Argument      | Requis | Description                                                                                        |
| :------------ | :----: | :------------------------------------------------------------------------------------------------- |
| `INPUT_PATH`  |   Oui  | Un fichier `.enc`, ou un dossier contenant des fichiers `.enc` (premier niveau ; tous déchiffrés). |
| `OUTPUT_PATH` |   Non  | Fichier ou dossier de sortie, du même type que l'entrée. Par défaut, le dossier de l'entrée.       |

**Options**

| Option           | Alias | Description                                                                         | Défaut             |
| :--------------- | :---: | :---------------------------------------------------------------------------------- | :----------------- |
| `--key <chemin>` |  `-k` | Chemin vers le fichier de clé maître (clé AES-256 brute de 32 octets ou en Base64). | `./master_key.bin` |

Déchiffrer un seul fichier :

```bash
portabase decrypt backup.tar.gz.enc backup.tar.gz --key master_key.bin
```

Déchiffrer tous les `.enc` d'un dossier vers un autre dossier :

```bash
portabase decrypt ./backups ./restored --key master_key.bin
```

Omettez la sortie pour écrire à côté de l'entrée, et omettez `--key` pour utiliser `master_key.bin` du dossier courant :

```bash
portabase decrypt backup.tar.gz.enc
```

<Callout type="info" title="Clé maître">
  La clé maître est la même clé AES-256 de 32 octets que celle utilisée pour le chiffrement. Téléchargez-la depuis le dashboard, dans **Paramètres → Stockage**. Si `--key` n'est pas fourni, le CLI cherche `master_key.bin` dans le dossier courant.
</Callout>

<Callout type="tip" title="Le mode dossier est résilient">
  Lors du déchiffrement d'un dossier, chaque fichier est traité indépendamment : un fichier corrompu ou avec une mauvaise clé n'interrompt pas le lot. Un récapitulatif liste les fichiers réussis et ceux en échec (avec la raison), et la commande se termine avec un code non nul si au moins un fichier a échoué.
</Callout>

<Callout type="info" title="Sauvegardes volumineuses">
  Le déchiffrement fonctionne entièrement en flux (streaming) : les fichiers sont traités par blocs, la mémoire reste donc bornée (quelques dizaines de Mo) même pour des sauvegardes de plusieurs gigaoctets (>2 Go). La sortie est écrite de manière atomique, donc un échec ne laisse jamais de fichier partiel.
</Callout>

## Maintenance et Dépannage [#maintenance-et-dépannage]

Gérez le comportement global et les paramètres du Portabase CLI.

### `config channel` [#config-channel]

Change le canal de mise à jour pour basculer entre les versions stables et bêta.

```bash
portabase config channel <stable|beta>
```

### `config show` [#config-show]

Affiche la configuration actuelle du CLI, y compris le canal de mise à jour actif.

```bash
portabase config show
```

### `update` [#update]

Met à jour le CLI vers la dernière version disponible. Cette commande vérifie les mises à jour sur le dépôt officiel et applique les correctifs de sécurité ou les nouvelles fonctionnalités.

```bash
portabase update
```

***

## Résolution de problèmes fréquents [#résolution-de-problèmes-fréquents]

<Accordions>
  <Accordion title="portabase : commande introuvable (command not found)">
    Le CLI est installé dans `/usr/local/bin`, mais certains shells (notamment les shells `root` sur les distributions minimales, ou les shells non-login) n'incluent pas ce dossier dans leur `PATH`.

    Vérifiez d'abord que le binaire est bien présent :

    ```bash
    ls -l /usr/local/bin/portabase
    ```

    Si le fichier existe, ajoutez le dossier à votre `PATH` puis rechargez la configuration de votre shell :

    ```bash
    echo 'export PATH="/usr/local/sbin:/usr/local/bin:$PATH"' >> /root/.bashrc
    source /root/.bashrc
    ```

    <Callout type="info" title="Adaptez à votre utilisateur et à votre shell">
      Remplacez `/root/.bashrc` par le fichier de profil de l'utilisateur qui lance réellement la commande :

      * **bash (utilisateur non-root)** : `~/.bashrc`
      * **zsh** : `~/.zshrc`
      * **fish** : `fish_add_path /usr/local/bin`

      Rechargez-le ensuite avec `source <fichier>` (ou ouvrez un nouveau terminal).
    </Callout>

    Vérifiez que tout fonctionne :

    ```bash
    which portabase
    portabase --version
    ```

    Si le binaire est absent de `/usr/local/bin`, l'installation ne s'est pas terminée : relancez le script d'installation et lisez sa sortie.
  </Accordion>

  <Accordion title="Docker Daemon not running">
    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`).
  </Accordion>

  <Accordion title="Permission Denied">
    Sur Linux, si vous n'avez pas ajouté votre utilisateur au groupe `docker`, vous devrez peut-être lancer les commandes avec `sudo`. &#x2A;Recommandé : Ajoutez
    votre utilisateur au groupe docker pour éviter d'utiliser sudo.*
  </Accordion>

  <Accordion title="Ping server failed (Logs Agent)">
    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.
  </Accordion>
</Accordions>


# Contribuer 



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.

<Cards>
  <Card href="#développement-du-dashboard" title="Développement Dashboard" icon="<DatabaseIcon />" description="Contribuez à l'interface web en Next.js. Apprenez à la lancer localement et à gérer la base de données." />

  <Card href="#développement-de-lagent" title="Développement Agent" icon="<WaypointsIcon />" description="Améliorez l'agent en Rust qui gère les sauvegardes et la communication avec le dashboard." />

  <Card href="/docs/cli#développement" title="Développement CLI" icon="<TerminalIcon />" description="Aidez à améliorer l'outil en ligne de commande en Python qui orchestre tout l'écosystème." />

  <Card href="https://github.com/Portabase/e2e-tests" title="Tests E2E" icon="<FlaskConicalIcon />" description="Maintenez la suite de tests end-to-end partagée, réutilisée pour valider à la fois le Dashboard et l'Agent." />
</Cards>

***

### Développement du Dashboard [#développement-du-dashboard]

Pour exécuter le Dashboard depuis les sources :

<Steps>
  <Step>
    #### Cloner le dépôt [#cloner-le-dépôt]

    ```bash
    git clone https://github.com/Portabase/portabase.git
    cd portabase
    ```
  </Step>

  <Step>
    #### Installer les dépendances [#installer-les-dépendances]

    ```bash
    pnpm install
    ```
  </Step>

  <Step>
    #### 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
    ```
  </Step>

  <Step>
    #### Démarrer en mode développement [#démarrer-en-mode-développement]

    ```bash
    make up
    ```
  </Step>
</Steps>

### Développement de l'Agent [#développement-de-lagent]

Pour mettre en place l'agent dans un environnement de développement :

<Steps>
  <Step>
    #### Cloner le dépôt [#cloner-le-dépôt-1]

    ```bash
    git clone https://github.com/Portabase/agent.git
    cd agent
    ```
  </Step>

  <Step>
    #### Compiler l'agent [#compiler-lagent]

    ```bash
    cargo build
    ```
  </Step>

  <Step>
    #### Démarrer en mode développement [#démarrer-en-mode-développement-1]

    ```bash
    docker compose up
    ```
  </Step>
</Steps>

Consultez les [prérequis de développement](/docs/requirements#4-prérequis-pour-le-développement-optionnel) pour les versions des outils.

***

### 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. **Lancez les tests** et assurez-vous qu'ils passent, y compris les [tests end-to-end](https://github.com/Portabase/e2e-tests) le cas échéant (voir [Tests](#tests) ci-dessous).
6. **Poussez** sur votre fork et **ouvrez une Pull Request**.

Merci de nous aider à rendre Portabase meilleur !

***

### Tests [#tests]

Portabase dispose d'un pipeline de tests automatisé qui s'exécute à chaque pull request.

Les &#x2A;*tests end-to-end (E2E)** sont maintenus dans un dépôt dédié, [`Portabase/e2e-tests`](https://github.com/Portabase/e2e-tests), plutôt que dans les dépôts du projet principal. Les garder séparés facilite leur maintenance et permet de réutiliser la même suite pour les tests côté agent.

<Cards>
  <Card href="https://github.com/Portabase/e2e-tests" title="Dashboard" icon="<DatabaseIcon />" description="S'appuie actuellement exclusivement sur les tests end-to-end. Les tests unitaires ne sont pas encore inclus." />

  <Card href="https://github.com/Portabase/e2e-tests" title="Agent" icon="<WaypointsIcon />" description="Inclut des tests unitaires exécutés à chaque pull request avec un rapport de couverture de code, en plus des tests end-to-end." />
</Cards>

### Commandes de développement utiles [#commandes-de-développement-utiles]

Pour faciliter la gestion de l'environnement de développement, des commandes `make` sont disponibles pour gérer les données des fournisseurs d'authentification.

<Cards>
  <Card title="Importer les données de test pour l'authentification">
    <p>
      Cette commande charge les données de test pour Keycloak et Pocket ID. Elle est un alias pour 

      `make seed-keycloak`

       et 

      `make seed-pocket`

      .
    </p>

    ```bash
    make seed-auth
    ```
  </Card>

  <Card title="Importer les données de test pour Keycloak">
    <p>
      Réinitialise et charge les données de test pour Keycloak depuis 

      `seeds/keycloak/*.json`

      .
    </p>

    ```bash
    make seed-keycloak
    ```
  </Card>

  <Card title="Importer les données de test pour Pocket ID">
    <p>
      Réinitialise et charge les données de test pour Pocket ID depuis 

      `seeds/pocket-id/portabase.zip`

      .
    </p>

    ```bash
    make seed-pocket
    ```
  </Card>

  <Card title="Exporter les données de Keycloak">
    <p>
      Exporte la configuration de Keycloak et les utilisateurs vers 

      `seeds/keycloak/`

      .
    </p>

    ```bash
    make export-keycloak
    ```
  </Card>

  <Card title="Exporter les données de Pocket ID">
    <p>
      Exporte les données de Pocket ID vers 

      `seeds/pocket-id/portabase.zip`

      .
    </p>

    ```bash
    make export-pocket
    ```
  </Card>

  <Card title="Générer un token d'accès pour Pocket ID">
    <p>
      Génère un token d'accès unique pour l'administrateur de Pocket ID.
    </p>

    ```bash
    make pocket-token
    ```
  </Card>
</Cards>


# FAQ 



<Accordions type="single">
  {docsFaqEntries.fr.map((item) => (
          <Accordion key={item.question} title={item.question}>
              {item.answer}
          </Accordion>
      ))}
</Accordions>


# Introduction 



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

<Callout type="info" title="Simplicité avant tout">
  Plus besoin d'écrire de scripts complexes. Portabase connecte vos serveurs à un tableau de bord unique pour une
  gestion sereine de vos données.
</Callout>

<div className="mt-8 flex justify-center">
  <div className="w-full max-w-2xl aspect-video">
    <VideoDialog animationStyle="top-in-bottom-out" videoSrc="https://www.youtube.com/embed/nSTzT27GgAg" thumbnailSrc="/static/img/thumbnail-portabase-video.png" thumbnailAlt="Portabase Video - Youtube" />
  </div>
</div>

***

## Architecture [#architecture]

Le serveur central fournit l’interface graphique et joue le rôle de control-plane : il permet de déclarer les agents, configurer les sauvegardes, lancer des restaurations et connecter des systèmes tiers (stockages, notifications).

L’agent est déployé au plus près des bases de données : il exécute les tâches de sauvegarde et de restauration.

Le choix architectural est important : le serveur cental ne contacte jamais directement les agents. Il n’est donc pas nécessaire d’ouvrir des ports entrants vers les environnements où résident les bases de données. Ce sont les agents qui contactent périodiquement le serveur central.

Cette approche réduit la surface d’exposition réseau et limite les conséquences d’une compromission du serveur central.

<div className="align-middle justify-items-center bg-white pl-4 pr-8 py-1 rounded-2xl">
  <Image src="/static/architecture.png" alt="Google Drive configuration" width="1280" height="1080" className="w-256" />
</div>

## Fonctionnalités [#fonctionnalités]

### Bases de données supportées [#bases-de-données-supportées]

| Base de données   | Support  | Versions testées             | Restauration |
| :---------------- | :------- | :--------------------------- | :----------- |
| **PostgreSQL**    | ✅ Stable | 12, 13, 14, 15, 16, 17 et 18 | Oui          |
| **MySQL**         | ✅ Stable | 5.7, 8 et 9                  | Oui          |
| **MariaDB**       | ✅ Stable | 10 et 11                     | Oui          |
| **MongoDB**       | ✅ Stable | 4, 5, 6, 7 et 8              | Oui          |
| **SQLite**        | ✅ Stable | 3.x                          | Oui          |
| **Redis**         | ✅ Stable | 2.8+                         | Non          |
| **Valkey**        | ✅ Stable | 7.2+                         | No           |
| **Firebird**      | ✅ Stable | 3.0, 4.0, 5.0                | Oui          |
| **MSSQL Server**  | ✅ Stable | -                            | Yes          |
| **Volume Docker** | ✅ Stable | Docker Engine 20.10+         | Oui          |

### 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.
* ✅ **Google Drive**
* ✅ **Azure Blob Storage**
* ✅ **Google Cloud Storage**

<Callout type="info" title="Note importantet">
  Portabase permet d’envoyer un même backup vers **plusieurs destinations simultanément**. Vous pouvez ainsi combiner
  stockage local, cloud privé et services S3, garantissant une redondance maximale et une sécurité accrue en cas de
  défaillance d’un point de stockage.
</Callout>

### 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.
* **Chiffrement avancé** : Sauvegardes protégées par AES GCM pour garantir la confidentialité et l’intégrité des données.

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

***

## Comment ça marche ? [#comment-ça-marche-]

L'écosystème repose sur trois éléments simples :

<Cards>
  <Card href="/docs/installation" title="Le Tableau de Bord" icon="<DatabaseIcon/>" description="L'interface web pour piloter vos sauvegardes, consulter l'historique et restaurer vos données si besoin." />

  <Card href="/docs/installation#couverture-de-lagent" title="L'Agent" icon="<WaypointsIcon/>" description="Le connecteur qui s'installe sur vos serveurs. Il travaille en arrière-plan pour gérer vos bases de données." />

  <Card href="/docs/cli" title="L'Assistant (CLI)" icon="<TerminalIcon/>" description="Un outil simple à lancer sur votre ordinateur pour installer et configurer vos agents en quelques secondes." />
</Cards>


# Prérequis 



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.

<Tabs items="[&#x22;Linux&#x22;, &#x22;macOS&#x22;]">
  <Tab value="Linux">
    ### 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.*
  </Tab>

  <Tab value="macOS">
    ### 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.
  </Tab>
</Tabs>

***

## 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).

<Callout type="info">
  Vous pouvez vérifier si Docker est correctement installé en tapant `docker compose version` dans votre terminal.
</Callout>

***

## 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+.


# Fichier de Configuration 



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.

<Tabs items="[&#x22;JSON (Défaut)&#x22;, &#x22;TOML&#x22;]">
  <Tab value="JSON (Défaut)">
    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"
            }
        ]
    }
    ```
  </Tab>

  <Tab value="TOML">
    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"
    ```
  </Tab>
</Tabs>

***

## 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 d'affichage de votre base de données                                                                                                        |
| `database`     | Dépend du fournisseur | 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`, `sqlite`, `mysql`, `mariadb` (utilisez `mysql` pour le driver MariaDB).    |
| `host`         | Dépend du fournisseur | 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`         | Dépend du fournisseur | Le port d'écoute (Défaut : `5432` pour Postgres, `3306` pour MySQL).                                                                               |
| `username`     | Dépend du fournisseur | L'utilisateur qui a les droits de lecture (dump) sur la base.                                                                                      |
| `password`     | Dépend du fournisseur | 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.

<Callout type="warn" title="Attention">
  Si vous créez ce fichier manuellement, vous **devez** générer vous-même un UUID valide. N'inventez pas une chaîne aléatoire simple.
</Callout>

<UUIDGenerator />

***

## 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

```

<Callout type="info">
  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`
</Callout>


# Variables d'environnement 



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.

<Callout type="info">
  Si vous utilisez Docker Compose, ces variables doivent être définies dans votre fichier `.env` à la racine du
  projet.
</Callout>

***

| Variable           | Type     | Optionnel | Défaut  | Description                                                                                                                                                                                                                                                                                                      |
| :----------------- | :------- | :-------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EDGE_KEY`         | `string` | Non       | `None`  | Clé unique de votre agent, disponible dans le dashboard.                                                                                                                                                                                                                                                         |
| `TZ`               | `string` | Oui       | `UTC`   | Fuseau horaire de l'agent (ex : `UTC`, `Europe/Paris`).                                                                                                                                                                                                                                                          |
| `POLLING`          | `number` | Oui       | `5`     | Fréquence (en secondes) de vérification des nouvelles tâches.                                                                                                                                                                                                                                                    |
| `DATA_PATH`        | `string` | Oui       | `/data` | Chemin interne où l'agent stocke ses données.                                                                                                                                                                                                                                                                    |
| `TMPDIR`           | `string` | Oui       | `/tmp`  | Répertoire où l'agent construit l'archive temporaire de sauvegarde/restauration. Pointez-le vers un disque disposant d'assez d'espace libre pour votre plus gros volume (voir [Volume Docker](/docs/agent/db/docker-volume#stockage-temporaire-et-espace-disque)).                                               |
| `RETRY_ATTEMPTS`   | `number` | Oui       | `3`     | Nombre total de tentatives — et non le nombre de nouvelles tentatives après la première — pour un dump de base de données, chaque upload vers le stockage et le téléchargement lors d’une restauration. `3` signifie une tentative initiale suivie de deux nouvelles tentatives. Doit être compris entre 3 et 5. |
| `RETRY_BACKOFF_MS` | `number` | Oui       | `1000`  | Délai de base entre les nouvelles tentatives. Il double à chaque tentative, avec un jitter uniforme et un plafond de 30 s par attente. Avec la valeur par défaut, le temps d’attente cumulé est d’environ 3 s maximum par étape. Doit être compris entre 100 et 30000.                                           |
| `SSL_CERT_FILE`    | `string` | Oui       | `None`  | Chemin d'un bundle de CA utilisé pour les connexions TLS sortantes de l'agent. Nécessaire lorsque l'agent doit faire confiance à une autorité de certification interne (voir ci-dessous).                                                                                                                        |

***

<Callout type="warn" title="Autorité de certification interne : update-ca-certificates n'a aucun effet">
  L'agent est écrit en Rust et utilise `rustls`, qui ne lit **pas** le répertoire de CA du système. Placer votre
  certificat dans `/usr/local/share/ca-certificates/` puis exécuter `update-ca-certificates` satisfait des outils
  comme `curl`, mais l'agent continue d'échouer avec `InvalidCertificate(UnknownIssuer)`.

  Montez plutôt un bundle de CA et faites-le pointer par `SSL_CERT_FILE` :

  ```yaml title="docker-compose.yml"
  volumes:
    - ./ca-bundle.crt:/etc/ssl/certs/portabase-ca-bundle.crt:ro
  environment:
    - SSL_CERT_FILE=/etc/ssl/certs/portabase-ca-bundle.crt
  ```

  `SSL_CERT_FILE` **remplace** le magasin de certificats racine par défaut, il ne s'y ajoute pas. Le bundle doit donc
  contenir les certificats racine standard de Mozilla concaténés à votre CA interne — sinon l'agent perd la confiance
  envers les hôtes publics, comme votre stockage S3.
</Callout>


# Vue d'ensemble 

Les outils de sauvegarde de bases de données varient considérablement en termes d'architecture et de portée opérationnelle. Certaines solutions sont spécialisées pour un moteur de base de données unique et s'appuient principalement sur des commandes en ligne de commande, tandis que d'autres offrent des fonctionnalités plus larges comme des interfaces web, la prise en charge de plusieurs bases et des outils de gestion pour les équipes.

## Vue d'ensemble des solutions existantes [#vue-densemble-des-solutions-existantes]

Les outils traditionnels tels que [Barman](https://pgbarman.org/), [pgBackRest](https://pgbackrest.org/) et [WAL-G](https://wal-g.readthedocs.io/) offrent des mécanismes robustes de sauvegarde et de restauration, mais s'adressent principalement aux spécialistes de l'infrastructure, nécessitant une configuration via des fichiers et la ligne de commande.

Les plateformes plus récentes comme [Databasus](https://databasus.com/) et [Databasement](https://david-crty.github.io/databasement/) simplifient la gestion des sauvegardes grâce à des interfaces graphiques et des configurations guidées, les rendant plus accessibles aux équipes de développement.

Les solutions d'entreprise comme [Veeam](https://www.veeam.com/) fournissent des capacités de sauvegarde étendues sur plusieurs systèmes, mais sont propriétaires et principalement destinées aux grandes organisations.

Portabase adopte une approche différente : une plateforme open-source légère avec une architecture basée sur des agents, une interface web et la prise en charge de plusieurs bases de données. Elle est entièrement auto-hébergée et conçue pour simplifier la gestion des sauvegardes pour les équipes manipulant plusieurs bases de données.

## Comparaison des fonctionnalités [#comparaison-des-fonctionnalités]

| Fonctionnalité                | Portabase | Barman | pgBackRest | WAL-G | Databasus | Databasement | Veeam |
| ----------------------------- | :-------: | :----: | :--------: | :---: | :-------: | :----------: | :---: |
| Support multi-DBMS            |     ✅     |    ❌   |      ❌     |   ✅   |     ✅     |       ✅      |   ✅   |
| Interface Web                 |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ✅      |   ✅   |
| Architecture basée sur agents |     ✅     |    ❌   |      ❌     |   ❌   |     ❌     |       ❌      |   ✅   |
| Équipes/organisations         |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ❌      |   ✅   |
| Notifications intégrées       |     ✅     |    ❌   |      ❌     |   ❌   |     ✅     |       ✅      |   ✅   |
| Intégration OIDC/OAuth2       |     ✅     |    ❌   |      ❌     |   ❌   |     ❌     |       ❌      |   ✅   |
| Installation Docker           |     ✅     |    ❌   |      ❌     |   ✅   |     ✅     |       ✅      |   ❌   |
| Support auto-hébergé          |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ❌   |
| Chiffrement                   |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ✅   |
| Politiques de rétention       |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ✅   |
| Open-Source                   |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ❌   |


# Bien démarrer 



Portabase est composé de trois parties principales. Pour commencer, nous vous recommandons d'installer le **Tableau de Bord** en premier, puis votre premier **Agent**.

<div className="mt-8 flex justify-center">
  <div className="w-full max-w-2xl aspect-video">
    <VideoDialog animationStyle="top-in-bottom-out" videoSrc="https://www.youtube.com/embed/42NCH5JHjdE" thumbnailSrc="/static/img/thumbnail-portabase-onboarding.png" thumbnailAlt="Portabase Onboarding - Youtube" />
  </div>
</div>

<Cards>
  <Card href="/docs/installation" title="Installer le Tableau de Bord" icon="<DatabaseIcon />" description="Configurez l'interface centrale pour gérer toutes vos sauvegardes et vos agents." />

  <Card href="/docs/installation#couverture-de-lagent" title="Installer un Agent" icon="<WaypointsIcon />" description="Déployez un agent léger sur vos serveurs de base de données pour gérer les tâches de sauvegarde." />

  <Card href="/docs/cli" title="Référence CLI" icon="<TerminalIcon />" description="Apprenez à utiliser la CLI Portabase pour automatiser l'installation et la gestion." />
</Cards>

***

### 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
```


# CLI 



Le CLI est la méthode d'installation recommandée. Il télécharge les templates, génère le secret de chiffrement (`PROJECT_SECRET`) et lance les conteneurs à votre place.

<Callout type="warn">
  Installez le CLI en premier. Si ce n'est pas encore fait, suivez les instructions [ici](/docs/cli#installation).
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Créer le Dashboard [#créer-le-dashboard]

        Lancez la commande suivante. Cela créera un dossier contenant la configuration.

        ```bash
        # Syntaxe : portabase dashboard <nom-du-dossier>
        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
        ```
      </Step>

      <Step>
        ### 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
        ```
      </Step>

      <Step>
        ### Accéder à l'interface [#accéder-à-linterface]

        Ouvrez votre navigateur : &#x2A;*[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    Le CLI vous guide pas à pas : il configure l'agent et vous propose d'ajouter immédiatement des bases de données.

    <Steps>
      <Step>
        ### 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**.
      </Step>

      <Step>
        ### 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.
      </Step>

      <Step>
        ### 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 ajoute 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 une instance distante RDS/managée). Vous devrez fournir l'hôte, le port et les identifiants.
      </Step>

      <Step>
        ### Démarrer [#démarrer]

        Si vous n'avez pas démarré l'agent à la fin de l'installation :

        ```bash
        portabase start my-agent
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Gestion quotidienne [#gestion-quotidienne]

Le CLI offre des raccourcis pratiques pour gérer le cycle de vie d'un dashboard ou d'un agent sans taper de commandes Docker complexes. `<path>` correspond au dossier créé à l'installation.

| Action           | Commande                     | Description                                                                                                                                 |
| :--------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **Démarrer**     | `portabase start <path>`     | Lance les conteneurs en arrière-plan (`up -d`).                                                                                             |
| **Arrêter**      | `portabase stop <path>`      | Arrête les conteneurs proprement.                                                                                                           |
| **Redémarrer**   | `portabase restart <path>`   | Redémarre la stack complète.                                                                                                                |
| **Logs**         | `portabase logs <path>`      | Affiche les logs en direct (option `-f` activée par défaut). Pour un agent, permet de vérifier la connexion au dashboard (« Ping server »). |
| **Désinstaller** | `portabase uninstall <path>` | ⚠️ Supprime les conteneurs **et** les volumes de données.                                                                                   |

***

## Étapes suivantes [#étapes-suivantes]

* [Variables d'environnement](/docs/dashboard/configuration/environment) pour le Dashboard, ou [environnement de l'Agent](/docs/agent/environment).
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) pour exposer le Dashboard derrière un domaine.
* [Mise en route](/docs/dashboard/getting-started) pour créer votre première sauvegarde.


# Coolify 



[Coolify](https://coolify.io) est un PaaS open-source et auto-hébergé - une alternative à Heroku, Netlify ou Vercel que vous exécutez sur vos propres serveurs. Portabase est publié dans son **catalogue de services** : le Dashboard et sa base PostgreSQL se déploient ensemble en quelques clics, sans écrire de `docker-compose.yml`.

Liens utiles : [site de Coolify](https://coolify.io) · [documentation Coolify](https://coolify.io/docs) · [Coolify sur GitHub](https://github.com/coollabsio/coolify)

<Callout type="warn">
  Vous avez besoin d'une instance Coolify fonctionnelle avec au moins un serveur connecté, et d'un
  domaine pointant dessus pour le HTTPS. Voir les [prérequis](/docs/requirements) pour le reste.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Créer la ressource [#créer-la-ressource]

        Dans votre interface Coolify, ouvrez le projet et l'environnement cibles,
        puis cliquez sur **+ New** et choisissez l'onglet **Service**.
      </Step>

      <Step>
        ### Choisir Portabase dans le catalogue [#choisir-portabase-dans-le-catalogue]

        Recherchez **Portabase** dans la liste des services en un clic et sélectionnez-le.

        Coolify crée le conteneur Portabase avec sa base PostgreSQL, et pré-remplit les
        valeurs générées (identifiants de la base, `PROJECT_SECRET`).
      </Step>

      <Step>
        ### Définir le domaine [#définir-le-domaine]

        Ouvrez les paramètres du service et renseignez le **Domain** (FQDN) du conteneur
        Portabase, par exemple `https://portabase.example.com`. Coolify se charge du reverse
        proxy et du certificat TLS : notre [guide reverse proxy](/docs/dashboard/configuration/reverse-proxy)
        n'est donc pas nécessaire ici.

        Vérifiez que la variable d'environnement `PROJECT_URL` correspond exactement à cette
        URL publique, schéma compris : les agents s'en servent pour joindre le Dashboard.
      </Step>

      <Step>
        ### Vérifier le secret [#vérifier-le-secret]

        <Callout type="warn">
          `PROJECT_SECRET` chiffre tout ce que les agents échangent avec le Dashboard, ainsi
          que les identifiants qui y sont stockés. Sauvegardez-le, et **ne le changez jamais
          une fois des agents connectés** : les données déjà chiffrées deviendraient illisibles.
        </Callout>

        S'il n'a pas été généré automatiquement, définissez une valeur aléatoire forte :

        ```bash
        openssl rand -hex 32
        ```

        La liste complète des réglages disponibles se trouve sur la page
        [variables d'environnement](/docs/dashboard/configuration/environment).
      </Step>

      <Step>
        ### Déployer [#déployer]

        Cliquez sur **Deploy**, attendez que le conteneur passe en healthy, puis ouvrez votre
        domaine et suivez la [mise en route](/docs/dashboard/getting-started).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      L'Agent ne se déploie pas via Coolify. Il doit tourner au plus près de vos bases de
      données, sur l'hôte lui-même, pour les joindre via le réseau local - y compris les bases
      que Coolify ne gère pas.
    </Callout>

    Installez-le directement sur le serveur de base de données avec le [CLI](/docs/installation/cli)
    ou [Docker Compose](/docs/installation/docker), puis lisez
    [sauvegarder les bases gérées par Coolify](#sauvegarder-les-bases-gérées-par-coolify) ci-dessous.
  </Tab>
</Tabs>

***

## Sauvegarder les bases gérées par Coolify [#sauvegarder-les-bases-gérées-par-coolify]

Coolify exécute chaque base de données dans un conteneur Docker, sur son propre réseau Docker. Pour
que l'Agent Portabase puisse les joindre, connectez le conteneur de l'agent à ce réseau :

```bash
# Lister les réseaux créés par Coolify, puis attacher l'agent au bon
docker network ls
docker network connect <reseau-coolify> portabase-agent
```

Déclarez ensuite la base dans le Dashboard en utilisant le **nom du conteneur** comme hôte, et son
port habituel. Les bases qui tournent directement sur l'hôte, et non dans un conteneur, restent
joignables grâce au mapping `extra_hosts` déjà présent dans le
[fichier compose de l'agent](/docs/installation/docker).

Les réglages propres à chaque moteur - droits requis, options de dump, comportement de restauration -
sont documentés dans la [section bases de données](/docs/agent/db).

***

## Dépannage [#dépannage]

* **L'agent apparaît hors ligne.** Vérifiez que `PROJECT_URL` est bien l'URL HTTPS publique du Dashboard, et non un nom de conteneur interne, puis vérifiez la [configuration de l'agent](/docs/agent/configuration).
* **L'agent ne joint pas une base.** C'est presque toujours un problème de réseau Docker - voir la section ci-dessus.
* **Vous avez changé `PROJECT_SECRET`.** Les données déjà chiffrées sont irrécupérables. Rétablissez la valeur précédente.

D'autres réponses dans la [FAQ](/docs/faq).

***

## Pages liées [#pages-liées]

<Cards>
  <Card href="/docs/installation/dokploy" title="Dokploy" icon="<DatabaseIcon />" description="Le même déploiement en un clic, sur le PaaS Dokploy." />

  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Installer l'Agent au plus près de vos bases avec Docker Compose." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentification" icon="<ShieldCheckIcon />" description="Ajouter des fournisseurs OAuth2 ou OIDC devant votre Dashboard." />

  <Card href="/docs/agent/db" title="Bases de données" icon="<WaypointsIcon />" description="Configuration détaillée pour chaque moteur supporté par Portabase." />
</Cards>


# Docker 



Déployez Portabase vous-même, sans le CLI. Utilisez **Docker Run** pour un test rapide et **Docker Compose** pour tout ce que vous comptez conserver.

<Callout type="warn">
  Assurez-vous que le moteur Docker est déjà installé sur l'hôte.
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    ## Docker Run [#docker-run]

    Recommandé uniquement pour les tests, pas pour la production : cette méthode utilise la base de données interne embarquée.

    <Steps>
      <Step>
        ### Variables d'environnement [#variables-denvironnement]

        Créez le fichier `.env`. **Attention**, vous devez générer vous-même les secrets.

        ```bash title=".env"
        # --- Configuration de l'app ---
        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=generated_secure_hex_token
        ```
      </Step>

      <Step>
        ### Démarrer le Dashboard [#démarrer-le-dashboard]

        ```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
        ```
      </Step>

      <Step>
        ### Accéder à l'interface [#accéder-à-linterface]

        Ouvrez votre navigateur : &#x2A;*[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
      </Step>
    </Steps>

    ## Docker Compose [#docker-compose]

    Recommandé pour la production et les workflows GitOps : le Dashboard tourne aux côtés d'un conteneur PostgreSQL dédié.

    <Steps>
      <Step>
        ### 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
        ```
      </Step>

      <Step>
        ### Configuration Docker [#configuration-docker]

        ```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:
                    - "8887:80"
                volumes:
                    - portabase-data:/data
                depends_on:
                    db:
                        condition: service_healthy
                healthcheck:
                    test: ["CMD-SHELL", "curl -f http://localhost/api/health"]
                    interval: 30s
                    timeout: 5s
                    retries: 3
                    start_period: 60s

            db:
                container_name: portabase-pg
                image: postgres:17-alpine
                restart: 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:
        ```
      </Step>

      <Step>
        ### Variables d'environnement [#variables-denvironnement-1]

        Créez le fichier `.env`. **Attention**, vous devez générer vous-même les secrets.

        ```bash title=".env"
        # --- Configuration de l'app ---
        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=generated_secure_hex_token

        # --- URL de la base de données ---
        POSTGRES_USER=portabase
        POSTGRES_PASSWORD=change_me_secure_db_password
        POSTGRES_HOST=db
        POSTGRES_PORT=5432
        POSTGRES_DB=portabase

        DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public
        ```
      </Step>

      <Step>
        ### Démarrage [#démarrage]

        ```bash
        docker compose up -d
        ```
      </Step>

      <Step>
        ### Accéder à l'interface [#accéder-à-linterface-1]

        Ouvrez votre navigateur : &#x2A;*[http://localhost:8887](http://localhost:8887)** (ou le port choisi).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    Pour une installation manuelle, créez la structure de fichiers et configurez le réseau pour que l'agent puisse voir vos bases de données locales.

    <Steps>
      <Step>
        ### Structure des fichiers [#structure-des-fichiers-1]

        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
        ```

        <Callout type="warn">
          Le fichier `databases.json` doit exister, même vide, avant de lancer le conteneur, sinon l'agent ne pourra pas démarrer correctement.
        </Callout>

        Initialisez le fichier JSON avec un objet vide :

        ```bash
        echo '{"databases": []}' > databases.json
        ```
      </Step>

      <Step>
        ### Configuration Docker [#configuration-docker-1]

        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
                    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`.*
      </Step>

      <Step>
        ### Variables d'environnement [#variables-denvironnement-2]

        Récupérez l'**Edge Key** de l'agent créé dans le Dashboard, puis ajoutez-la au fichier `.env` :

        ```bash title=".env"
        EDGE_KEY=coller_votre_clé_ici
        ```

        Pour la liste complète des variables d'environnement disponibles, consultez la page [Environnement](/docs/agent/environment).
      </Step>

      <Step>
        ### Démarrage [#démarrage-1]

        ```bash
        docker compose up -d
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Étapes suivantes [#étapes-suivantes]

* [Variables d'environnement](/docs/dashboard/configuration/environment) pour le Dashboard, ou [environnement de l'Agent](/docs/agent/environment).
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) pour exposer le Dashboard derrière un domaine.
* [Mise en route](/docs/dashboard/getting-started) pour créer votre première sauvegarde.


# Dokploy 



[Dokploy](https://dokploy.com) est un PaaS open-source et auto-hébergé bâti sur Docker et Traefik - une alternative à Vercel, Netlify ou Heroku pour vos propres serveurs. Portabase est publié dans son **catalogue de templates** : le Dashboard et sa base PostgreSQL se déploient ensemble en quelques clics, sans écrire de `docker-compose.yml`.

Liens utiles : [site de Dokploy](https://dokploy.com) · [documentation Dokploy](https://docs.dokploy.com) · [Dokploy sur GitHub](https://github.com/Dokploy/dokploy)

<Callout type="warn">
  Vous avez besoin d'une instance Dokploy fonctionnelle, et d'un domaine pointant dessus pour le
  HTTPS. Voir les [prérequis](/docs/requirements) pour le reste.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Créer le service [#créer-le-service]

        Ouvrez le projet cible, cliquez sur **Create Service** et choisissez **Template**.
      </Step>

      <Step>
        ### Choisir Portabase dans le catalogue [#choisir-portabase-dans-le-catalogue]

        Recherchez **Portabase** dans la liste des templates et créez-le.

        Dokploy provisionne le conteneur Portabase avec sa base PostgreSQL, et pré-remplit les
        valeurs générées (identifiants de la base, `PROJECT_SECRET`).
      </Step>

      <Step>
        ### Définir le domaine [#définir-le-domaine]

        Dans l'onglet **Domains** du service, ajoutez l'hôte public du conteneur Portabase,
        par exemple `portabase.example.com`, sur le port **80**. Activez le HTTPS pour que
        Dokploy émette le certificat via Traefik : notre
        [guide reverse proxy](/docs/dashboard/configuration/reverse-proxy) n'est donc pas
        nécessaire ici.

        Vérifiez que la variable d'environnement `PROJECT_URL` correspond exactement à cette
        URL publique, schéma compris : les agents s'en servent pour joindre le Dashboard.
      </Step>

      <Step>
        ### Vérifier le secret [#vérifier-le-secret]

        <Callout type="warn">
          `PROJECT_SECRET` chiffre tout ce que les agents échangent avec le Dashboard, ainsi
          que les identifiants qui y sont stockés. Sauvegardez-le, et **ne le changez jamais
          une fois des agents connectés** : les données déjà chiffrées deviendraient illisibles.
        </Callout>

        S'il n'a pas été généré automatiquement, définissez une valeur aléatoire forte :

        ```bash
        openssl rand -hex 32
        ```

        La liste complète des réglages disponibles se trouve sur la page
        [variables d'environnement](/docs/dashboard/configuration/environment).
      </Step>

      <Step>
        ### Déployer [#déployer]

        Cliquez sur **Deploy**, attendez que le conteneur passe en healthy, puis ouvrez votre
        domaine et suivez la [mise en route](/docs/dashboard/getting-started).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      L'Agent ne se déploie pas via Dokploy. Il doit tourner au plus près de vos bases de
      données, sur l'hôte lui-même, pour les joindre via le réseau local - y compris les bases
      que Dokploy ne gère pas.
    </Callout>

    Installez-le directement sur le serveur de base de données avec le [CLI](/docs/installation/cli)
    ou [Docker Compose](/docs/installation/docker), puis lisez
    [sauvegarder les bases gérées par Dokploy](#sauvegarder-les-bases-gérées-par-dokploy) ci-dessous.
  </Tab>
</Tabs>

***

## Sauvegarder les bases gérées par Dokploy [#sauvegarder-les-bases-gérées-par-dokploy]

Dokploy exécute chaque base de données dans un conteneur Docker, sur son propre réseau Docker. Pour
que l'Agent Portabase puisse les joindre, connectez le conteneur de l'agent à ce réseau :

```bash
# Lister les réseaux créés par Dokploy, puis attacher l'agent au bon
docker network ls
docker network connect <reseau-dokploy> portabase-agent
```

Déclarez ensuite la base dans le Dashboard en utilisant le **nom du conteneur** comme hôte, et son
port habituel. Les bases qui tournent directement sur l'hôte, et non dans un conteneur, restent
joignables grâce au mapping `extra_hosts` déjà présent dans le
[fichier compose de l'agent](/docs/installation/docker).

Les réglages propres à chaque moteur - droits requis, options de dump, comportement de restauration -
sont documentés dans la [section bases de données](/docs/agent/db).

***

## Dépannage [#dépannage]

* **L'agent apparaît hors ligne.** Vérifiez que `PROJECT_URL` est bien l'URL HTTPS publique du Dashboard, et non un nom de conteneur interne, puis vérifiez la [configuration de l'agent](/docs/agent/configuration).
* **L'agent ne joint pas une base.** C'est presque toujours un problème de réseau Docker - voir la section ci-dessus.
* **Vous avez changé `PROJECT_SECRET`.** Les données déjà chiffrées sont irrécupérables. Rétablissez la valeur précédente.

D'autres réponses dans la [FAQ](/docs/faq).

***

## Pages liées [#pages-liées]

<Cards>
  <Card href="/docs/installation/coolify" title="Coolify" icon="<DatabaseIcon />" description="Le même déploiement en un clic, sur le PaaS Coolify." />

  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Installer l'Agent au plus près de vos bases avec Docker Compose." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentification" icon="<ShieldCheckIcon />" description="Ajouter des fournisseurs OAuth2 ou OIDC devant votre Dashboard." />

  <Card href="/docs/agent/db" title="Bases de données" icon="<WaypointsIcon />" description="Configuration détaillée pour chaque moteur supporté par Portabase." />
</Cards>


# Vue d'ensemble 



Portabase se compose de deux éléments, tous deux installés depuis cette section :

* Le **Dashboard** - le plan de contrôle. Installez-le une seule fois, là où vous souhaitez piloter vos sauvegardes.
* L'**Agent** - le connecteur. Installez-en un sur chaque serveur hébergeant des bases de données à sauvegarder.

Commencez par le Dashboard, puis installez votre premier Agent. Chaque page ci-dessous traite les deux, dans un onglet **Dashboard** et un onglet **Agent**.

<Callout type="warn">
  Vérifiez les [prérequis](/docs/requirements) avant de commencer.
</Callout>

***

## Choisir une méthode [#choisir-une-méthode]

| Méthode                                         | Idéal pour                                                          | Base de données interne | Support         | Statut      |
| :---------------------------------------------- | :------------------------------------------------------------------ | :---------------------- | :-------------- | :---------- |
| [**CLI**](/docs/installation/cli)               | Démarrer vite, la voie la plus directe sur un serveur classique     | -                       | Officiel        | ✅ Testé     |
| [**Docker**](/docs/installation/docker)         | Contrôle manuel, GitOps, hôtes Docker existants                     | Embarquée ou externe    | Officiel        | ✅ Testé     |
| [**Kubernetes**](/docs/installation/kubernetes) | Clusters existants, workflows Helm                                  | Embarquée ou externe    | Officiel        | ✅ Testé     |
| [**Coolify**](/docs/installation/coolify)       | Utilisateurs de PaaS auto-hébergé voulant un déploiement en un clic | Gérée par Coolify       | Officiel        | ✅ Testé     |
| [**Dokploy**](/docs/installation/dokploy)       | Utilisateurs de PaaS auto-hébergé voulant un déploiement en un clic | Gérée par Dokploy       | Officiel        | ✅ Testé     |
| [**Unraid**](/docs/installation/unraid)         | Serveurs Unraid, installation depuis Community Applications         | Externe (PostgreSQL 17) | Officiel        | ✅ Testé     |
| [**Proxmox VE**](/docs/installation/proxmox)    | Hôtes Proxmox, LXC via le script communautaire                      | Installée dans le LXC   | ⚠️ Non officiel | ❌ Non testé |

**Support** - les méthodes *officielles* sont publiées et maintenues par l'équipe Portabase. Les méthodes *non officielles* sont maintenues par un tiers : nous ne maîtrisons ni ce qu'elles installent, ni le moment où elles changent.

**Statut** - *Testé* signifie que nous exécutons nous-mêmes la méthode avant chaque version. *Non testé* signifie que nous ne l'avons pas vérifiée.

Sans préférence particulière, utilisez le **CLI**. Il génère le secret de chiffrement et lance les conteneurs à votre place.

<Cards>
  <Card href="/docs/installation/cli" title="CLI" icon="<TerminalIcon />" description="Une commande pour créer et démarrer le Dashboard ou un Agent. Recommandé." />

  <Card href="/docs/installation/docker" title="Docker" icon="<ContainerIcon />" description="Docker Run pour un test rapide, Docker Compose pour la production." />

  <Card href="/docs/installation/kubernetes" title="Kubernetes" icon="<ShipIcon />" description="Installez le chart Helm depuis le registre OCI." />

  <Card href="/docs/installation/coolify" title="Coolify" icon="<CloudIcon />" description="Déployez le Dashboard depuis le catalogue de services Coolify." />

  <Card href="/docs/installation/dokploy" title="Dokploy" icon="<LayersIcon />" description="Déployez le Dashboard depuis le catalogue de templates Dokploy." />

  <Card href="/docs/installation/unraid" title="Unraid" icon="<HardDriveIcon />" description="Installez le Dashboard depuis le catalogue Community Applications." />

  <Card href="/docs/installation/proxmox" title="Proxmox VE" icon="<ServerIcon />" description="Script communautaire créant un LXC Debian. Non officiel, non testé." />
</Cards>

***

## Couverture de l'Agent [#couverture-de-lagent]

L'Agent s'exécute au plus près de vos bases de données : il s'installe donc directement sur l'hôte, plutôt que via un PaaS ou un cluster.

| Méthode    | Dashboard | Agent                                                                                |
| :--------- | :-------- | :----------------------------------------------------------------------------------- |
| CLI        | ✅         | ✅                                                                                    |
| Docker     | ✅         | ✅                                                                                    |
| Kubernetes | ✅         | ❌ - utilisez [Docker](/docs/installation/docker)                                     |
| Coolify    | ✅         | ❌ - utilisez le [CLI](/docs/installation/cli) ou [Docker](/docs/installation/docker) |
| Dokploy    | ✅         | ❌ - utilisez le [CLI](/docs/installation/cli) ou [Docker](/docs/installation/docker) |
| Unraid     | ✅         | ❌ - utilisez [Docker](/docs/installation/docker)                                     |
| Proxmox VE | ✅         | ❌ - utilisez le [CLI](/docs/installation/cli) ou [Docker](/docs/installation/docker) |

***

## Après l'installation [#après-linstallation]

Une fois le Dashboard en ligne, poursuivez avec :

* [Variables d'environnement](/docs/dashboard/configuration/environment) - base de données externe, e-mail, limites de stockage.
* [Reverse proxy](/docs/dashboard/configuration/reverse-proxy) - exposer le service derrière un domaine en HTTPS.
* [Authentification](/docs/dashboard/configuration/auth/configuration) - fournisseurs OAuth2 et OIDC.
* [Mise en route](/docs/dashboard/getting-started) - créer votre premier agent et votre première sauvegarde.


# Kubernetes 



Pour les déploiements Kubernetes, installez le Dashboard directement depuis le registre OCI avec Helm.

<Callout type="warn">
  Nécessite un cluster fonctionnel, `kubectl` configuré dessus, et Helm 3.8+ (support OCI).
</Callout>

***

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    ## Avec ClusterIP + port-forward (développement/test) [#avec-clusterip--port-forward-développementtest]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set project.secret=$(openssl rand -hex 32)
    ```

    ```bash
    kubectl port-forward svc/portabase 8887:80 -n portabase
    # Accès à http://localhost:8887
    ```

    ## Avec LoadBalancer (environnements cloud) [#avec-loadbalancer-environnements-cloud]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set service.type=LoadBalancer \
    --set project.secret=$(openssl rand -hex 32)
    ```

    ```bash
    kubectl get svc portabase -n portabase
    # Accès à http://<EXTERNAL-IP>:8887
    ```

    ## Avec Ingress (accès par domaine) [#avec-ingress-accès-par-domaine]

    ```bash
    helm install portabase oci://ghcr.io/portabase/charts/portabase \
    -n portabase --create-namespace \
    --set ingress.enabled=true \
    --set ingress.hosts[0].host=portabase.example.com \
    --set project.secret=$(openssl rand -hex 32)
    ```
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      Il n'existe pas de chart Helm pour l'Agent. L'Agent est conçu pour tourner au plus près
      de vos bases de données, sur l'hôte lui-même, afin de les joindre via le réseau local.
    </Callout>

    Installez-le sur le serveur de base de données avec le [CLI](/docs/installation/cli) ou
    [Docker Compose](/docs/installation/docker).
  </Tab>
</Tabs>

***

## Étapes suivantes [#étapes-suivantes]

* [Variables d'environnement](/docs/dashboard/configuration/environment) - pointer le Dashboard vers un PostgreSQL externe.
* [Authentification](/docs/dashboard/configuration/auth/configuration) - fournisseurs OAuth2 et OIDC.
* [Mise en route](/docs/dashboard/getting-started) - créer votre première sauvegarde.


# Proxmox VE 



[Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment) est une plateforme de virtualisation open source. Le projet [community-scripts](https://community-scripts.org) maintient un script qui crée un conteneur LXC Debian 13 et y installe le Dashboard Portabase - PostgreSQL, tusd, nginx et les services systemd compris.

Liens utiles : [Script Portabase](https://community-scripts.org/scripts/portabase) · [Site community-scripts](https://community-scripts.org) · [Documentation Proxmox VE](https://pve.proxmox.com/pve-docs/)

<Callout type="error">
  **Non officiel et non testé.** Ce script est maintenu par le projet community-scripts, pas par
  l'équipe Portabase, et il se trouve actuellement dans leur dépôt de **développement** - signalé
  comme *en développement actif*, *possiblement instable, incomplet ou sujet à des changements
  cassants*, et **déconseillé en production**. C'est aussi la seule méthode d'installation que nous
  n'avons pas testée nous-mêmes. Pour un déploiement supporté, utilisez plutôt le
  [CLI](/docs/installation/cli) ou [Docker](/docs/installation/docker).
</Callout>

***

## Ce que le script installe [#ce-que-le-script-installe]

| Élément                  | Valeur                                                   |
| :----------------------- | :------------------------------------------------------- |
| Type de conteneur        | LXC non privilégié                                       |
| OS                       | Debian 13                                                |
| Ressources par défaut    | 4 vCPU · 8192 Mo de RAM · 15 Go de disque                |
| Port                     | `3000` (nginx devant l'application sur `127.0.0.1:8887`) |
| Base de données          | PostgreSQL 17, installé dans le conteneur                |
| Téléversements           | tusd, via le service `portabase-tusd`                    |
| Fichier de configuration | `/opt/portabase/.env`                                    |
| Services                 | `portabase`, `portabase-tusd`                            |

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Lancer le script depuis le shell Proxmox VE [#lancer-le-script-depuis-le-shell-proxmox-ve]

        Ouvrez le **Shell** de votre nœud Proxmox VE et exécutez :

        ```bash
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/portabase.sh)"
        ```

        <Callout type="info">
          Lisez toujours le script avant de l'exécuter. La commande à jour et faisant foi
          est affichée sur la [page du script](https://community-scripts.org/scripts/portabase) -
          vérifiez-la là-bas si l'URL ci-dessus a changé.
        </Callout>

        Acceptez les valeurs par défaut, ou choisissez **Advanced** pour ajuster le CPU, la
        RAM, le disque et les paramètres réseau.
      </Step>

      <Step>
        ### Ouvrir le Dashboard [#ouvrir-le-dashboard]

        À la fin, le script affiche l'URL : `http://<ip-du-conteneur>:3000`.

        Connectez-vous avec le compte par défaut qu'il a créé :

        | Utilisateur         | Mot de passe    |
        | :------------------ | :-------------- |
        | `admin@example.com` | `Portabase123!` |

        <Callout type="warn">
          Changez ce mot de passe dès la première connexion, et passez
          `AUTH_SIGNUP_ENABLED=false` dans `/opt/portabase/.env` une fois votre compte créé.
        </Callout>
      </Step>

      <Step>
        ### Vérifier la configuration [#vérifier-la-configuration]

        Le script génère `PROJECT_SECRET` à votre place et l'écrit dans `/opt/portabase/.env`,
        aux côtés de `DATABASE_URL`, `PROJECT_URL` et `TRUSTED_DOMAINS` - ces deux dernières
        pointant sur `http://<ip-du-conteneur>:3000`.

        <Callout type="warn">
          `PROJECT_SECRET` chiffre tout ce que les agents échangent avec le Dashboard, ainsi
          que les identifiants qui y sont stockés. Sauvegardez `/opt/portabase/.env`, et **ne
          changez jamais ce secret une fois des agents connectés** : les données déjà
          chiffrées deviendraient illisibles.
        </Callout>

        SMTP, backends de stockage et fournisseurs d'authentification se configurent dans ce
        même fichier - voir
        [variables d'environnement](/docs/dashboard/configuration/environment). Appliquez les
        changements avec :

        ```bash
        systemctl restart portabase
        ```

        Si vous placez le Dashboard derrière un domaine en HTTPS - voir le
        [guide reverse proxy](/docs/dashboard/configuration/reverse-proxy) - mettez à jour
        `PROJECT_URL` et `TRUSTED_DOMAINS` avec cette URL publique.
      </Step>

      <Step>
        ### Mise à jour [#mise-à-jour]

        Relancez la même commande et choisissez **Update**. Le script arrête les services,
        sauvegarde `/opt/portabase/.env`, déploie la nouvelle version, reconstruit
        l'application et restaure votre configuration.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      Le script n'installe que le Dashboard. L'Agent doit s'exécuter au plus près de vos bases
      de données : il s'installe donc directement sur l'hôte qui les héberge.
    </Callout>

    Installez-le avec le [CLI](/docs/installation/cli) ou
    [Docker Compose](/docs/installation/docker) - dans le conteneur LXC ou la VM qui exécute la
    base, ou sur l'hôte Proxmox lui-même si les bases y résident.
  </Tab>
</Tabs>

***

## Sauvegarder des bases hébergées sur Proxmox VE [#sauvegarder-des-bases-hébergées-sur-proxmox-ve]

Les bases tournent en général dans d'autres conteneurs LXC ou VM du même nœud. Installez un Agent par
conteneur ou VM, puis déclarez chaque base dans le Dashboard avec l'IP du conteneur ou de la VM et le
port de la base. Vérifiez que le pare-feu Proxmox autorise l'Agent à la joindre.

Les réglages propres à chaque moteur - droits requis, options de dump, comportement à la restauration

* sont documentés dans la [section bases de données](/docs/agent/db).

***

## Dépannage [#dépannage]

* **Le Dashboard ne répond pas sur le port 3000.** Vérifiez les deux services : `systemctl status portabase portabase-tusd`, et les logs avec `journalctl -u portabase -f`.
* **L'agent apparaît hors ligne.** `PROJECT_URL` doit être l'URL que l'agent peut réellement joindre. Mettez-la à jour dans `/opt/portabase/.env` puis redémarrez. Voir la [configuration de l'agent](/docs/agent/configuration).
* **Les téléversements ou restaurations échouent.** Le service `portabase-tusd` est arrêté, ou `TUSD_BEHIND_PROXY` a été modifié. Redémarrez-le avec `systemctl restart portabase-tusd`.
* **Le script lui-même échoue.** C'est un problème community-scripts, pas Portabase - signalez-le sur [leur GitHub](https://github.com/community-scripts/ProxmoxVED/issues) avec les logs en mode verbeux avancé.

Plus de réponses dans la [FAQ](/docs/faq).

***

## Pages liées [#pages-liées]

<Cards>
  <Card href="/docs/installation/cli" title="CLI" icon="<TerminalIcon />" description="L'installation supportée en une commande, sur n'importe quel hôte Linux." />

  <Card href="/docs/installation/unraid" title="Unraid" icon="<DatabaseIcon />" description="Installez le Dashboard depuis le catalogue Community Applications." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentification" icon="<ShieldCheckIcon />" description="Ajoutez des fournisseurs OAuth2 ou OIDC devant votre Dashboard." />

  <Card href="/docs/agent/db" title="Bases de données" icon="<WaypointsIcon />" description="Configuration par moteur pour chaque base supportée par Portabase." />
</Cards>


# Unraid 



[Unraid](https://unraid.net) est un système d'exploitation NAS doté d'une boutique d'applications basée sur Docker. Portabase y est publié comme **template officiel** dans [Community Applications](https://ca.unraid.net/apps/portabase-dashboard-1sdc97m05ufd7q) : le Dashboard s'installe depuis l'onglet Apps, sans aucun `docker-compose.yml` à écrire.

Liens utiles : [Portabase sur Community Applications](https://ca.unraid.net/apps/portabase-dashboard-1sdc97m05ufd7q) · [Site d'Unraid](https://unraid.net) · [Documentation Unraid](https://docs.unraid.net)

<Callout type="warn">
  Le template ne fournit **pas** de base de données. Il vous faut une instance **PostgreSQL 17**
  accessible avant l'installation - soit le conteneur PostgreSQL de Community Applications, soit un
  serveur externe. Consultez les [prérequis](/docs/requirements) pour le reste.
</Callout>

***

## Installation [#installation]

<Tabs items="[&#x22;Dashboard&#x22;, &#x22;Agent&#x22;]">
  <Tab value="Dashboard" id="dashboard">
    <Steps>
      <Step>
        ### Installer PostgreSQL 17 [#installer-postgresql-17]

        Depuis l'onglet **Apps**, installez un conteneur PostgreSQL 17 puis créez une base et
        un utilisateur pour Portabase. Notez l'hôte, le port, le nom de la base, l'utilisateur
        et le mot de passe : ils servent à l'étape suivante.
      </Step>

      <Step>
        ### Ajouter le template Portabase [#ajouter-le-template-portabase]

        Toujours dans l'onglet **Apps**, recherchez **Portabase**, sélectionnez
        **Portabase-Dashboard** puis cliquez sur **Install**.

        Le template utilise l'image officielle `portabase/portabase:latest`, en mode réseau
        **bridge**.
      </Step>

      <Step>
        ### Renseigner les variables obligatoires [#renseigner-les-variables-obligatoires]

        | Champ                  | Valeur par défaut                       | Remarques                                                                               |
        | :--------------------- | :-------------------------------------- | :-------------------------------------------------------------------------------------- |
        | Port WebUI             | `8887` → `80` dans le conteneur         | Changez le port hôte si `8887` est déjà pris                                            |
        | `/data`                | `/mnt/user/appdata/portabase/dashboard` | Données persistantes, à conserver sur l'array                                           |
        | `DATABASE_URL`         | -                                       | `postgresql://user:password@host:5432/portabase`                                        |
        | `PROJECT_SECRET`       | -                                       | Valeur hexadécimale aléatoire forte, voir plus bas                                      |
        | `PROJECT_URL`          | -                                       | L'URL du Dashboard **telle que les agents la joignent**, ex. `http://192.168.1.10:8887` |
        | `AUTH_SIGNUP_ENABLED`  | -                                       | À désactiver une fois votre compte créé                                                 |
        | `AUTH_PASSKEY_ENABLED` | `true`                                  | Authentification par passkey                                                            |

        Les variables optionnelles - `PROJECT_NAME`, `AUTH_DEFAULT_USER_NAME`,
        `AUTH_DEFAULT_USER`, `AUTH_DEFAULT_PASSWORD`, les paramètres SMTP et
        `RETENTION_CRON` - sont décrites sur la page
        [variables d'environnement](/docs/dashboard/configuration/environment).
      </Step>

      <Step>
        ### Générer le secret [#générer-le-secret]

        <Callout type="warn">
          `PROJECT_SECRET` chiffre tout ce que les agents échangent avec le Dashboard, ainsi
          que les identifiants qui y sont stockés. Sauvegardez-le, et **ne le changez jamais
          une fois des agents connectés** : les données déjà chiffrées deviendraient
          illisibles.
        </Callout>

        Depuis le terminal Unraid :

        ```bash
        openssl rand -hex 32
        ```
      </Step>

      <Step>
        ### Appliquer et ouvrir la WebUI [#appliquer-et-ouvrir-la-webui]

        Cliquez sur **Apply**, attendez le démarrage du conteneur, puis ouvrez
        `http://<ip-unraid>:8887` et suivez la
        [mise en route](/docs/dashboard/getting-started).

        Pour l'exposer sur un domaine en HTTPS, placez-le derrière un reverse proxy - voir le
        [guide reverse proxy](/docs/dashboard/configuration/reverse-proxy) - et renseignez
        `PROJECT_URL` avec cette URL publique.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Agent" id="agent">
    <Callout type="info">
      Il n'existe pas encore de template Community Applications pour l'Agent. Celui-ci doit
      s'exécuter au plus près de vos bases de données, sur l'hôte lui-même, afin de les joindre
      sur le réseau local.
    </Callout>

    Pour sauvegarder des bases hébergées **sur le serveur Unraid**, installez-y l'Agent avec
    [Docker Compose](/docs/installation/docker) depuis le terminal Unraid. Pour des bases situées
    sur d'autres machines, installez un Agent par machine avec le [CLI](/docs/installation/cli)
    ou [Docker](/docs/installation/docker).
  </Tab>
</Tabs>

***

## Sauvegarder des bases hébergées sur Unraid [#sauvegarder-des-bases-hébergées-sur-unraid]

Unraid exécute chaque base de données dans un conteneur Docker. Pour que l'Agent puisse la joindre,
les deux conteneurs doivent partager un réseau :

```bash
# Lister les réseaux Docker, puis rattacher l'agent au bon
docker network ls
docker network connect <network> portabase-agent
```

Déclarez ensuite la base dans le Dashboard en utilisant le **nom du conteneur** comme hôte, et son
port habituel. Les conteneurs du réseau `bridge` par défaut sont aussi joignables sur l'IP de
l'Unraid, au port publié.

Les réglages propres à chaque moteur - droits requis, options de dump, comportement à la restauration

* sont documentés dans la [section bases de données](/docs/agent/db).

***

## Dépannage [#dépannage]

* **Le conteneur redémarre en boucle.** `DATABASE_URL` est incorrecte ou PostgreSQL est injoignable. Consultez le log du conteneur depuis l'interface Unraid.
* **L'agent apparaît hors ligne.** `PROJECT_URL` doit être l'URL que l'agent peut réellement joindre : l'IP LAN de l'Unraid, ou l'URL publique HTTPS si vous utilisez un reverse proxy. Voir la [configuration de l'agent](/docs/agent/configuration).
* **L'agent ne joint pas une base.** Presque toujours un problème de réseau Docker - voir la section ci-dessus.
* **Vous avez changé `PROJECT_SECRET`.** Les données chiffrées existantes sont irrécupérables. Restaurez la valeur précédente.

Plus de réponses dans la [FAQ](/docs/faq).

***

## Pages liées [#pages-liées]

<Cards>
  <Card href="/docs/installation/docker" title="Docker" icon="<TerminalIcon />" description="Installez l'Agent au plus près de vos bases avec Docker Compose." />

  <Card href="/docs/installation/proxmox" title="Proxmox VE" icon="<DatabaseIcon />" description="Déployez le Dashboard dans un conteneur LXC via le script communautaire." />

  <Card href="/docs/dashboard/configuration/auth/configuration" title="Authentification" icon="<ShieldCheckIcon />" description="Ajoutez des fournisseurs OAuth2 ou OIDC devant votre Dashboard." />

  <Card href="/docs/agent/db" title="Bases de données" icon="<WaypointsIcon />" description="Configuration par moteur pour chaque base supportée par Portabase." />
</Cards>


# Volume Docker 



Le type `docker-volume` permet à l'agent de sauvegarder directement un volume Docker nommé, sans passer par un driver de base de données. Utile pour les moteurs sans outil de dump dédié, ou pour protéger le volume de données d'un conteneur tel quel.

La sauvegarde et la restauration s'effectuent **à la volée, à chaud**, sans arrêter le conteneur cible.

<Callout type="warn">
  Ce provider nécessite que l'agent ait accès au socket Docker. Vous devez monter `/var/run/docker.sock:/var/run/docker.sock` sur le conteneur de l'agent, sinon il ne peut pas inspecter ni archiver le volume.
</Callout>

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `docker-volume` comme type de base de données.

    **Paramètres spécifiques demandés :**

    * **Volume Name** : Le nom exact du volume Docker à sauvegarder (ex : `databases_sqlite-data`).
    * **Container Name** : (Optionnel, mais recommandé) Le nom du conteneur utilisant actuellement le volume. Renseignez-le pour permettre à l'agent de redémarrer automatiquement ce conteneur après une restauration.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Test database 14 - Docker Volume",
      "type": "docker-volume",
      "volume_name": "<volume_name>",
      "generated_id": "...",
      "container_name": "<container_name>",
    }
    ```

    <UUIDGenerator />

    **Paramètres spécifiques :**

    * **volume\_name** : (Requis) Le nom du volume Docker à sauvegarder.
    * **container\_name** : (Optionnel, mais recommandé) Le nom du conteneur auquel le volume est attaché. Sans lui la sauvegarde/restauration fonctionne quand même, mais l'agent ne peut pas redémarrer automatiquement le conteneur après une restauration.
  </Tab>
</Tabs>

## Exemple Docker Compose [#exemple-docker-compose]

L'agent a besoin d'accéder au socket Docker pour inspecter et archiver les volumes. Montez-le en plus de votre configuration d'agent habituelle.

```yaml title="docker-compose.yml"
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      # Requis : donne à l'agent l'accès au démon Docker
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
    networks:
      - portabase

networks:
  portabase:
    name: portabase_network
    external: true
```

<Callout type="info">
  Sans le socket Docker monté, l'agent ne peut pas résoudre ni archiver le volume et le job de sauvegarde échouera.
</Callout>

## Stockage temporaire et espace disque [#stockage-temporaire-et-espace-disque]

Pendant une sauvegarde `docker-volume`, l'agent construit l'archive de sauvegarde dans un **répertoire temporaire** à l'intérieur du conteneur de l'agent, en utilisant l'emplacement temporaire du système, `/tmp` par défaut.

Si `/tmp` se trouve sur un système de fichiers racine à l'étroit, la sauvegarde d'un gros volume échoue avec :

```
No space left on device
```

<Callout type="warn">
  L'archive temporaire occupe environ la taille du volume sauvegardé. Un volume de 20 Go nécessite environ 20 Go libres à l'emplacement temporaire, et pas seulement à la destination.
</Callout>

### Rediriger le répertoire temporaire [#rediriger-le-répertoire-temporaire]

L'agent respecte la variable d'environnement standard `TMPDIR`. Pointez-la vers un répertoire adossé à un disque plus grand, et montez-y un stockage hôte :

```yaml title="docker-compose.yml"
services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      - /var/run/docker.sock:/var/run/docker.sock
      # Répertoire hôte avec assez d'espace libre
      - /mnt/bigdisk:/scratch
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."
      # Indique à l'agent de construire les archives temporaires ici au lieu de /tmp
      TMPDIR: /scratch
```

Utilisez un chemin hôte (`/mnt/bigdisk`) disposant de plus d'espace libre que la taille de la sauvegarde. L'archive temporaire est construite là plutôt que sur le système de fichiers racine à l'étroit.

<Callout type="info">
  L'archive temporaire est supprimée automatiquement une fois la sauvegarde terminée. Il en va de même pour les **restaurations** : elles décompressent dans le même emplacement temporaire, donc `TMPDIR` doit pointer vers un disque assez grand pour elles aussi.
</Callout>


# Firebird 



L'agent utilisera `gbak` et `isql` pour réaliser les sauvegardes/restaurations.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `firebird` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Database - Firebird",
      "database": "/var/lib/firebird/data/mirror.fdb",
      "type": "firebird",
      "username": "alice",
      "password": "fake_password",
      "port": 3050,
      "host": "db-firebird",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose [#docker-compose]

Voici comment configurer un service Firebird en parallèle de l’agent.

```yaml title="docker-compose.yml"
services:
  db-firebird:
    image: firebirdsql/firebird
    container_name: db-firebird
    restart: always
    environment:
      - FIREBIRD_ROOT_PASSWORD=fake_root_password
      - FIREBIRD_USER=alice
      - FIREBIRD_PASSWORD=fake_password
      - FIREBIRD_DATABASE=mirror.fdb
      - FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8
    volumes:
      - firebird-data:/var/lib/firebird/data
    ports:
      - "3060:3050"
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... Configuration de l'agent ...
    depends_on:
      - db-firebird
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  firebird-data:
```

<Callout type="warn">
  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.
</Callout>


# Bases de Données Supportées 



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              | Restauration |
| :---------------- | :-------------- | :------- | :---------------------------- | :----------- |
| **PostgreSQL**    | `postgresql`    | ✅ Stable | 12, 13, 14, 15, 16, 17 and 18 | Oui          |
| **MySQL**         | `mysql`         | ✅ Stable | 5.7, 8 and 9                  | Oui          |
| **MariaDB**       | `mysql`         | ✅ Stable | 10 and 11                     | Oui          |
| **MongoDB**       | `mongodb`       | ✅ Stable | 4, 5, 6, 7 and 8              | Oui          |
| **SQLite**        | `sqlite`        | ✅ Stable | 3.x                           | Oui          |
| **Redis**         | `redis`         | ✅ Stable | 2.8+                          | Non          |
| **Valkey**        | `valkey`        | ✅ Stable | 7.2+                          | Non          |
| **Firebird**      | `firebird`      | ✅ Stable | 3.0, 4.0, 5.0                 | Oui          |
| **MSSQL Server**  | `mssql`         | ✅ Stable | -                             | Oui          |
| **Volume Docker** | `docker-volume` | ✅ Stable | Docker Engine 20.10+          | Oui          |

## 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).

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;À la main&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    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**.
  </Tab>

  <Tab value="À la main" id="docker">
    Vous pouvez aussi éditer le fichier `databases.json` (ou `.toml`) monté dans le conteneur.

    ```json title="databases.json"
    {
      "databases": [
        {
          "name": "Database 1 - PostgreSQL",
          "database": "my-db",
          "type": "postgresql",
          "host": "db-prod",
          "port": 5432,
          "username": "admin",
          "password": "secret_password",
          "generated_id": "uuid-v4-unique"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<UUIDGenerator />

<Callout type="info">
  Pour plus de détails sur chaque moteur, consultez les pages dédiées dans cette section.
</Callout>


# MariaDB 



L'agent utilisera `mariadb-dump` pour réaliser les sauvegardes et les restaurations.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `mariadb` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Database - MariaDB",
      "database": "mariadb",
      "type": "mariadb",
      "username": "mariadb",
      "password": "changeme",
      "port": 3306,
      "host": "db-mariadb",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose [#docker-compose]

```yaml title="docker-compose.yml"
services:
  db-mariadb:
    container_name: db-mariadb
    image: mariadb:latest
    ports:
      - "3311:3306"
    environment:
      - MYSQL_DATABASE=mariadb
      - MYSQL_USER=mariadb
      - MYSQL_PASSWORD=changeme
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... Configuration de l'agent ...
    depends_on:
      - db-mariadb
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mariadb-data:
```

<Callout type="warn">
  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.
</Callout>


# MongoDB 



L'agent utilisera `mongodump` pour réaliser les sauvegardes et `mongorestore` pour les restaurations.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `mongodb` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ### Avec Authentification [#avec-authentification]

    ```json title="databases.json"
    {
      "name": "my-mongo-auth",
      "database": "testdbauth",
      "type": "mongodb",
      "host": "db-mongodb-auth",
      "port": 27017,
      "username": "username",
      "password": "password",
      "generated_id": "..."
    }
    ```

    ### Sans Authentification [#sans-authentification]

    ```json title="databases.json"
    {
      "name": "my-mongo",
      "type": "mongodb",
      "host": "db-mongodb",
      "port": 27017,
      "database": "testdb",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## MongoDB Atlas / Cloud (SRV) [#mongodb-atlas--cloud-srv]

Les clusters MongoDB managés (MongoDB Atlas et équivalents) sont joignables via un enregistrement DNS `SRV` plutôt que par un hôte et un port fixes. La chaîne de connexion utilise le schéma `mongodb+srv://`.

Pour une connexion SRV, &#x2A;*n'indiquez pas le champ `port`** (ou mettez-le à `0`). L'agent le détecte et bascule automatiquement sur `mongodb+srv://`. Utilisez le nom d'hôte du cluster (se terminant par `.mongodb.net`) comme `host`.

Via CLI : lancez `portabase db add`, choisissez `mongodb`, puis laissez le port vide pour activer la connexion SRV.

```json title="databases.json"
{
  "name": "MongoDB Cluster Cloud",
  "database": "mydb",
  "type": "mongodb",
  "username": "username",
  "password": "password",
  "host": "cluster0.abcde.mongodb.net",
  "generated_id": "..."
}
```

<UUIDGenerator />

<Callout type="info">
  Aucun `port` n'est renseigné pour les connexions SRV. Lorsque `port` est absent (ou `0`), l'agent construit une URI `mongodb+srv://user:password@host/database?authSource=admin`. Avec authentification, les identifiants sont encodés (URL-encoding) automatiquement et `authSource=admin` est ajouté. Sans nom d'utilisateur ni mot de passe, l'URI est construite sans identifiants ni chaîne de requête.
</Callout>

## 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:
```

<Callout type="warn">
  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.
</Callout>


# MsSQL 



L'agent utilisera `sqlpackage` pour réaliser les sauvegardes/restaurations.

<Callout type="warn">
  MsSQL impose des règles de complexité strictes pour les mots de passe. Votre mot de passe doit comporter au moins 8 caractères et contenir des caractères issus de trois des quatre catégories suivantes : majuscules, minuscules, chiffres (0 à 9) et caractères non alphanumériques (ex: !, $, #, %). Le non-respect de ces exigences entraînera le crash du conteneur.
</Callout>

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `mssql` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Database - MsSQL",
      "database": "myappdb",
      "type": "mssql",
      "username": "sa",
      "password": "Password!Strong1",
      "port": 1433,
      "host": "db-mssql",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose [#docker-compose]

Voici comment configurer un service MsSQL en parallèle de l’agent.

```yaml title="docker-compose.yml"
services:
  db-mssql:
    container_name: db-mssql
    image: mcr.microsoft.com/azure-sql-edge:latest
    ports:
      - "1433:1433"
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "Password!Strong1"
    volumes:
      - mssql-data:/var/opt/mssql
    networks:
      - portabase
    healthcheck:
      test: ["CMD-SHELL", "cat /proc/net/tcp6 | grep -q '059901' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 20

  agent:
    image: portabase/agent:latest
    # ... agent configuration ...
    depends_on:
      - db-mssql
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mssql-data:
```

<Callout type="warn">
  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.
</Callout>


# MySQL 



L'agent utilisera `mysqldump` pour réaliser les sauvegardes et les restaurations.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `mysql`.

    **Paramètres spécifiques demandés :**

    * **Database Name** : Le nom de la base de données à sauvegarder.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json`, utilisez le type `mysql`.

    ```json title="databases.json"
    {
        "name": "Test database 11 - Mysql",
        "database": "mysqldb",
        "type": "mysql",
        "username": "mysqldb",
        "password": "changeme",
        "port": 3306,
        "host": "db-mysql",
        "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Paramètres spécifiques :**

    * **database** : (Requis) Le nom de la base de données.
  </Tab>
</Tabs>

## Exemple Docker Compose [#exemple-docker-compose]

Exemple avec une image MySQL.

```yaml title="docker-compose.yml"
services:
  db-mysql:
    container_name: db-mysql
    image: mysql:9.5
    ports:
      - "3312:3306"
    environment:
      - MYSQL_DATABASE=mysqldb
      - MYSQL_USER=mysqldb
      - MYSQL_PASSWORD=changeme
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - portabase

  agent:
    image: portabase/agent:latest
    # ... Configuration de l'agent ...
    depends_on:
      - db-mysql
    networks:
      - portabase

networks:
  portabase:
    external: true

volumes:
  mysql-data:
```

<Callout type="warn">
  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.
</Callout>


# PostgreSQL 



PostgreSQL est entièrement supporté par l'agent Portabase. Nous utilisons les outils natifs `pg_dump` pour garantir des sauvegardes cohérentes et fiables.

Deux modes sont disponibles :

* **`postgresql`** : Sauvegarde d'une base unique via `pg_dump`. Cible une base de données précise.
* **`postgresql-cluster`** : Sauvegarde complète du cluster via `pg_dumpall`. Dumpe toutes les bases de l'instance **ainsi que les objets globaux** (rôles, propriété, droits, tablespaces). Utile lorsque des rôles et une propriété avancés sont configurés au niveau du cluster.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    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.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Database - PostgreSQL",
      "type": "postgresql",
      "host": "postgres",
      "port": 5432,
      "username": "postgres",
      "password": "mysecretpassword",
      "database": "app_db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Paramètres spécifiques :**

    * **database** : (Requis) Le nom exact de la base de données à dumper.
  </Tab>
</Tabs>

## Options [#options]

Les champs suivants peuvent être définis sous une clé `options` dans la configuration de la base de données.

| Option           | Type      | Défaut    | Description                                                                                                                                                                                                                                                                                                                            |
| ---------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep_ownership` | `boolean` | `false`   | Lorsque `true`, les flags `--no-owner` et `--no-privileges` sont omis du dump. La propriété et les droits sont préservés dans la sortie. Par défaut, ces flags sont appliqués afin de rendre les restaurations portables entre différents utilisateurs et environnements, par exemple lors d'une migration d'une instance à une autre. |
| `clean_mode`     | `string`  | `"clean"` | Contrôle la façon dont la base cible est nettoyée **avant une restauration**. Une valeur parmi `none`, `clean`, `drop_schemas`, `drop_database`. Voir [Mode de nettoyage](#mode-de-nettoyage) ci-dessous.                                                                                                                              |

```json title="databases.json (avec options)"
{
  "name": "Database - PostgreSQL",
  "type": "postgresql",
  "host": "postgres",
  "port": 5432,
  "username": "postgres",
  "password": "mysecretpassword",
  "database": "app_db",
  "generated_id": "...",
  "options": {
    "keep_ownership": true,
    "clean_mode": "drop_schemas"
  }
}
```

### Mode de nettoyage [#mode-de-nettoyage]

`pg_restore --clean` ne supprime que les objets présents dans la table des matières de la sauvegarde. Tout ce qui existe déjà dans la cible et que le dump ne connaît pas subsiste et peut entrer en conflit avec la restauration : restaurer dans une base **déjà peuplée** peut donc échouer partiellement (`already exists`, erreurs de contrainte ou de clé). `clean_mode` permet de garantir une cible propre avant la restauration.

| Valeur          | Comportement                                                                                                  | Cas d'usage                                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`          | Aucun pré-nettoyage et pas de `--clean`.                                                                      | Restauration dans une base connue comme vide. Le plus rapide, le moins destructif.                                                                          |
| `clean`         | Comportement actuel : `pg_restore --clean --if-exists`. &#x2A;*Par défaut.**                                  | Configurations existantes. N'est pas une réinitialisation complète (voir ci-dessus).                                                                        |
| `drop_schemas`  | Supprime chaque schéma non système en `CASCADE`, puis restaure.                                               | **Recommandé pour les nouvelles configurations.** Fonctionne sur Postgres managé (RDS, Cloud SQL, Neon, Supabase) où le rôle ne peut pas supprimer la base. |
| `drop_database` | `DROP DATABASE` + `CREATE DATABASE` en préservant l'encodage, la collation et le propriétaire, puis restaure. | Réinitialisation complète sur Postgres auto-hébergé où le rôle possède `CREATEDB` + la propriété, ou est superutilisateur.                                  |

Si la valeur est absente ou non reconnue, l'agent retombe sur `clean`. `drop_database` n'est jamais appliqué par défaut.

<Callout type="warning">
  `drop_schemas` et `drop_database` sont **destructifs et sans retour arrière**. Si l'agent s'arrête entre la suppression et la restauration, la cible reste vide ou supprimée. `drop_database` exige en plus que le rôle de connexion soit propriétaire de la base **et** dispose de `CREATEDB`, ou soit superutilisateur - sinon la restauration échoue à une vérification préalable avant toute suppression. Préférez `drop_schemas` sur les fournisseurs managés où vous ne pouvez pas supprimer la base.
</Callout>

<Callout type="info">
  `drop_schemas` est limité aux schémas : il ne supprime pas les objets au niveau de la base ou du cluster (event triggers, publications/souscriptions, paramètres au niveau de la base, rôles, tablespaces). Les extensions installées dans un schéma supprimé ne sont recréées à la restauration que si le rôle en a la permission (les extensions réservées au superutilisateur comme `pg_stat_statements` ne le sont pas). Pour une cible entièrement vierge incluant les objets globaux, utilisez `drop_database`.
</Callout>

```json title="databases.json (supprimer et recréer avant la restauration)"
{
  "name": "Database - PostgreSQL",
  "type": "postgresql",
  "host": "postgres",
  "port": 5432,
  "username": "postgres",
  "password": "mysecretpassword",
  "database": "app_db",
  "generated_id": "...",
  "options": {
    "clean_mode": "drop_database"
  }
}
```

## Sauvegarde du cluster (`pg_dumpall`) [#sauvegarde-du-cluster-pg_dumpall]

Utilisez le mode cluster lorsque vous devez sauvegarder **l'instance entière** : toutes les bases de données ainsi que les objets globaux tels que les rôles, la propriété et les droits. C'est le choix recommandé lorsque des rôles et une propriété avancés sont configurés au niveau du cluster de bases de données, car un simple `pg_dump` ne capture pas les objets globaux du cluster.

<Callout type="info">
  L'utilisateur spécifié dans la configuration doit être un superadmin pour que `pg_dumpall` puisse dumper toutes les bases et les objets globaux.
</Callout>

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `postgresql-cluster` 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.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "Database - PostgreSQL Cluster",
      "type": "postgresql-cluster",
      "host": "postgres",
      "port": 5432,
      "username": "postgres",
      "password": "mysecretpassword",
      "database": "app_db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />

    **Paramètres spécifiques :**

    * **username** : (Requis) Doit être un superutilisateur pour dumper toutes les bases et les objets globaux.
    * **database** : (Optionnel) Base de connexion utilisée pour exécuter `pg_dumpall`. Vaut `"postgres"` par défaut si omis. Cette valeur **ne limite pas** le périmètre du dump - `pg_dumpall` inclut toujours toutes les bases de l'instance, quelle que soit cette valeur.
  </Tab>
</Tabs>

<UUIDGenerator />

<Callout type="warning">
  Les sauvegardes de cluster peuvent être nettement plus volumineuses et plus lentes que les sauvegardes d'une base unique, car toutes les bases de l'instance sont incluses. La restauration d'une sortie `pg_dumpall` recrée les rôles et la propriété de manière globale.
</Callout>

## 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:
```

<Callout type="info">
  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`.
</Callout>


# Redis 



L'agent utilisera `redis-cli` pour réaliser les sauvegardes.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `redis` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ### Avec Authentification [#avec-authentification]

    ```json title="databases.json"
    {
      "name": "Redis Database Auth",
      "type": "redis",
      "host": "db-redis-auth",
      "port": 6379,
      "username": "username",
      "password": "password",
      "generated_id": "..."
    }
    ```

    ### Sans Authentification [#sans-authentification]

    ```json title="databases.json"
    {
      "name": "Redis Database",
      "type": "redis",
      "host": "db-redis",
      "port": 6379,
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose [#docker-compose]

```yaml title="docker-compose.yml"
services:

    db-redis:
        image: redis:latest
        container_name: db-redis
        ports:
          - "6379:6379"
        volumes:
          - redis-data:/data
        command: [ "redis-server", "--appendonly", "yes" ]
        networks:
          - portabase

    db-redis-auth:
        image: redis:latest
        container_name: db-redis-auth
        ports:
          - "6380:6379"
        volumes:
          - redis-data-auth:/data
        environment:
          - REDIS_PASSWORD=<mot-de-passe>
        command: [ "redis-server", "--requirepass", "<mot-de-passe>", "--appendonly", "yes" ]
        networks:
          - portabase

    agent:
        image: portabase/agent:latest
        # ... agent configuration ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  redis-data-auth:
  redis-data:
```

## Important : Localhost et Docker [#important--localhost-et-docker]

<Callout type="warn">
  Si vous utilisez localhost comme hôte (car 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 sur toutes les interfaces (0.0.0.0) ou qu'elle est accessible depuis l'agent.

  Essayez ceci : `"host": "host.docker.internal"` (remplacez host dans config.json, toml) ou `"host": "db-redis"` (si vous utilisez Docker Compose).
</Callout>


# SQLite 



## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `sqlite` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ```json title="databases.json"
    {
      "name": "SQLite - 1",
      "type": "sqlite",
      "host": "db-sqlite",
      "path": "/sqlite-data/workspace/data/app.db",
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Exemple Docker Compose [#exemple-docker-compose]

Exemple avec une image SQLite.

```yaml title="docker-compose.yml"
services:

    sqlite:
      container_name: db-sqlite
      image: keinos/sqlite3
      volumes:
        - sqlite-data:/workspace/data
      working_dir: /workspace
      command: tail -f /dev/null
      stdin_open: true
      tty: true

    agent:
        image: portabase/agent:latest
        volumes:
          - ./databases.json:/config/config.json
        # Mapper le dossier de données SQLite pour y accéder ensuite dans le container agent
          - sqlite-data:/sqlite-data/workspace/data
        # ... configuration de l'agent ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  sqlite-data:

```

<Callout type="warn">
  Si vous utilisez une base de données SQLite locale, il suffit de la mapper dans les volumes de l’agent : `/var/lib/myapp:/sqlite-data/workspace/data`
</Callout>


# Valkey 



L'agent utilisera `valkey-cli` pour réaliser les sauvegardes.

## Configuration [#configuration]

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Lorsque vous exécutez `portabase db add`, sélectionnez `valkey` comme type de base de données.
  </Tab>

  <Tab value="Via Docker Compose" id="docker">
    Dans votre fichier `databases.json` (ou `.toml`), configurez le bloc suivant.

    ### Avec Authentification [#avec-authentification]

    ```json title="databases.json"
    {
      "name": "Valkey Database Auth",
      "type": "valkey",
      "host": "db-valkey-auth",
      "port": 6379,
      "username": "username",
      "password": "password",
      "generated_id": "..."
    }
    ```

    ### Sans Authentification [#sans-authentification]

    ```json title="databases.json"
    {
      "name": "Valkey Database",
      "type": "valkey",
      "host": "db-valkey",
      "port": 6379,
      "generated_id": "..."
    }
    ```

    <UUIDGenerator />
  </Tab>
</Tabs>

## Docker Compose [#docker-compose]

```yaml title="docker-compose.yml"
services:

    db-valkey:
        image: valkey/valkey
        container_name: db-valkey
        environment:
          - ALLOW_EMPTY_PASSWORD=yes
        ports:
          - '6381:6379'
        volumes:
          - valkey-data:/data
        networks:
          - portabase

    db-valkey-auth:
        image: valkey/valkey
        container_name: db-valkey-auth
        command: >
          --requirepass "supersecurepassword"
        ports:
          - '6382:6379'
        volumes:
          - valkey-data-auth:/data
        networks:
          - portabase

    agent:
        image: portabase/agent:latest
        # ... agent configuration ...
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  valkey-data-auth:
  valkey-data:
```

## Important : Localhost et Docker [#important--localhost-et-docker]

<Callout type="warn">
  Si vous utilisez localhost comme hôte (car 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 sur toutes les interfaces (0.0.0.0) ou qu'elle est accessible depuis l'agent.

  Essayez ceci : `"host": "host.docker.internal"` (remplacez host dans config.json, toml) ou `"host": "db-valkey"` (si vous utilisez Docker Compose).
</Callout>


# Introduction à l'API 



Le dashboard Portabase expose une API REST pour la gestion programmatique des bases de données et des agents. L'interface Swagger UI et la spécification OpenAPI sont également disponibles.

## Activer l'API [#activer-lapi]

Définissez les variables d'environnement suivantes dans la configuration du dashboard :

```bash
API_ENABLED=true
OPENAPI_ENABLED=true
```

* `API_ENABLED=true` : active toutes les routes API sous `/api/v1`.
* `OPENAPI_ENABLED=true` : active la spécification OpenAPI et l'interface Swagger UI. L'API doit également être activée pour que cela fonctionne.

## Documentation de l'API [#documentation-de-lapi]

Une fois activée :

| Ressource             | URL               |
| --------------------- | ----------------- |
| Swagger UI            | `/api/v1/docs`    |
| Spécification OpenAPI | `/api/v1/openapi` |

## Authentification [#authentification]

Pour créer un token d'API :

1. Accédez à votre **Profil** dans le dashboard.
2. Ouvrez l'onglet **Compte**.
3. Dans la section **Token API**, générez un nouveau token.

Les tokens sont au niveau utilisateur, toutes les actions API héritent des permissions de l'utilisateur associé.

Utilisez l'en-tête `x-api-key` pour authentifier vos requêtes :

```http
GET /api/v1/databases
x-api-key: <votre-token>
```

<Callout type="info">
  La couverture de l'API est en cours d'extension. Consultez la [feuille de route](https://github.com/orgs/Portabase/projects/1) pour les prochains endpoints.
</Callout>


# Variables d'environnement 



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.

<Callout type="info">
  Si vous utilisez Docker Compose, ces variables doivent être définies dans votre fichier `.env` à la racine du
  projet.
</Callout>

***

## Projet [#projet]

Configuration générale de l'instance Portabase.

| Variable                       | Type      | Optionnel | Défaut                  | Description                                                                                                                                                                                                                                                                                       |
| :----------------------------- | :-------- | :-------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PROJECT_URL`                  | `string`  | Non       | `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`  | Non       | `None`                  | **Critique.** Clé secrète utilisée pour chiffrer les données sensibles. Générez-la avec `openssl rand -hex 32`.                                                                                                                                                                                   |
| `PROJECT_NAME`                 | `string`  | Oui       | `Portabase`             | Le nom affiché dans l'interface (titre du site).                                                                                                                                                                                                                                                  |
| `RETENTION_CRON`               | `string`  | Oui       | `0 7 * * *`             | Planification de la purge automatique des sauvegarde conformément aux politiques de rétention.                                                                                                                                                                                                    |
| `STALE_BACKUP_THRESHOLD_HOURS` | `number`  | Oui       | `6`                     | Seuil, en heures, au-delà duquel une sauvegarde sans exécution réussie récente est marquée comme obsolète.                                                                                                                                                                                        |
| `BACKUP_FOLDER_NAME`           | `string`  | Oui       | `backups`               | Nom du dossier de stockage des fichiers de sauvegarde dans les canaux de stockage.                                                                                                                                                                                                                |
| `LOG_LEVEL`                    | `string`  | Oui       | `info`                  | Contrôle le niveau minimal des logs. Options : `debug`, `info`, `warn`, `error`                                                                                                                                                                                                                   |
| `SKIP_ONBOARDING`              | `boolean` | Oui       | `false`                 | Ignore l'étape d'onboarding initiale au premier lancement. Mettez `true` lorsque l'instance est provisionnée automatiquement.                                                                                                                                                                     |
| `AUTH_DEFAULT_USER_NAME`       | `string`  | Oui       | `None`                  | Nom de l’utilisateur par défaut                                                                                                                                                                                                                                                                   |
| `AUTH_DEFAULT_USER`            | `string`  | Oui       | `None`                  | Adresse e-mail de l’utilisateur par défaut                                                                                                                                                                                                                                                        |
| `AUTH_DEFAULT_PASSWORD`        | `string`  | Oui       | `None`                  | Le mot de passe doit contenir au moins 8 caractères, 1 chiffre, 1 lettre minuscule, 1 lettre majuscule et 1 caractère spécial                                                                                                                                                                     |
| `TELEMETRY`                    | `boolean` | Oui       | `True`                  | Permet la collecte de métriques d’utilisation anonymes.                                                                                                                                                                                                                                           |
| `TUSD_BEHIND_PROXY`            | `boolean` | Oui       | `false`                 | Pas toujours nécessaire. Mettez `true` lorsque le dashboard est derrière un reverse proxy, afin que le serveur d'upload tusd fasse confiance aux en-têtes `X-Forwarded-*` et génère des URLs d'upload correctes. Peut résoudre certains problèmes d'upload selon la configuration de votre proxy. |

<Callout type="warning">
  Si vous souhaitez créer automatiquement l’utilisateur par défaut via les variables `.env`, utilisez `AUTH_DEFAULT_USER_NAME`, `AUTH_DEFAULT_USER` et `AUTH_DEFAULT_PASSWORD`. Ces 3 variables doivent obligatoirement être renseignées.
</Callout>

***

## API & MCP [#api--mcp]

Contrôle l'accès programmatique à votre dashboard.

| Variable          | Type      | Optionnel | Défaut  | Description                                                                                                          |
| :---------------- | :-------- | :-------- | :------ | :------------------------------------------------------------------------------------------------------------------- |
| `API_ENABLED`     | `boolean` | Oui       | `false` | Active toutes les routes REST API sous `/api/v1`. Requis pour OpenAPI et MCP.                                        |
| `OPENAPI_ENABLED` | `boolean` | Oui       | `false` | Active la spécification OpenAPI et Swagger UI sur `/api/v1/openapi` et `/api/v1/docs`. Nécessite `API_ENABLED=true`. |
| `MCP_ENABLED`     | `boolean` | Oui       | `false` | Active le serveur MCP sur `/api/v1/mcp` pour les intégrations avec les assistants IA. Nécessite `API_ENABLED=true`.  |

***

## Base de données [#base-de-données]

Configuration de la connexion à la base de données PostgreSQL de Portabase.

| Variable       | Type     | Optionnel | Défaut | Description                                                                                                                                                                                                          |
| :------------- | :------- | :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | `string` | Oui       | None   | URL de la base de données (exemple: `postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public`). Si non spécifié, la base de données interne sera utilisée. |

***

## Email (SMTP) [#email-smtp]

Configuration pour l'envoi d'emails transactionnels (alertes, invitations).

<Callout type="warning">
  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).
</Callout>

| 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` |                                                                |


# Reverse Proxy 



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.example.com`) et sécurisé avec HTTPS, il est recommandé d'utiliser un **Reverse Proxy**.

***

<Tabs items="[&#x22;Traefik V3&#x22;, &#x22;Nginx&#x22;, &#x22;GoDoxy&#x22;]">
  <Tab value="Traefik V3">
    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-data:/data
        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(`portabase.example.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-data:

    networks:
      # Déclaration du réseau externe
      traefik_network:
      external: true
    ```

    <Callout type="warn" title="Conflits de noms">
      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...`
    </Callout>
  </Tab>

  <Tab value="Nginx">
    Si vous utilisez un serveur web classique comme Nginx sur l'hôte :

    ### 1. Configuration Portabase [#1-configuration-portabase]

    Conservez la configuration par défaut qui expose le service uniquement sur localhost.

    ```yaml
    ports:
    - "127.0.0.1:8887:80" # Écoute uniquement sur localhost
    ```

    ### 2. Variable WebSocket [#2-variable-websocket]

    Le dashboard utilise des WebSockets. Nginx n'a pas de variable native pour ne transmettre l'en-tête
    `Connection` que lorsque c'est nécessaire : déclarez-la dans le bloc `http` (par exemple dans
    `/etc/nginx/conf.d/upgrade.conf`) :

    ```nginx title="/etc/nginx/conf.d/upgrade.conf"
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    ```

    <Callout type="warn" title="Ne codez pas Connection &#x22;upgrade&#x22; en dur">
      Mettre `proxy_set_header Connection "upgrade"` sur chaque requête casse le keepalive vers l'upstream. La
      `map` ci-dessus envoie `upgrade` pour les requêtes WebSocket et `close` pour les autres.
    </Callout>

    ### 3. Blocs serveur Nginx [#3-blocs-serveur-nginx]

    Une configuration complète avec redirection HTTP → HTTPS, HTTP/2 et support des WebSockets.

    ```nginx title="/etc/nginx/sites-available/portabase"
    server {
        listen 80;
        http2 on;

        server_name portabase.example.com;

        return 301 https://portabase.example.com$request_uri;
    }

    server {
        listen 443 ssl;
        http2 on;
        server_name portabase.example.com;

        include /etc/nginx/snippets/ssl.conf;

        location / {
            proxy_pass http://127.0.0.1:8887;

            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_set_header        X-Scheme $scheme;
            proxy_set_header        Upgrade $http_upgrade;
            proxy_set_header        Connection $connection_upgrade;

            proxy_read_timeout 120s;
            proxy_send_timeout 60s;
            proxy_connect_timeout 10s;
        }
    }
    ```

    <Callout title="À adapter à votre installation">
      * `proxy_pass http://127.0.0.1:8887` correspond à l'étape 1. Si Nginx tourne lui-même dans Docker sur le
        même réseau que le dashboard, utilisez plutôt le nom du conteneur : `proxy_pass http://portabase-app:80`.
      * `/etc/nginx/snippets/ssl.conf` contient votre certificat et vos réglages TLS (`ssl_certificate`,
        `ssl_certificate_key`, …). Certbot génère les lignes équivalentes directement dans le bloc server.
    </Callout>

    ### 4. Activer le site [#4-activer-le-site]

    ```bash
    ln -s /etc/nginx/sites-available/portabase /etc/nginx/sites-enabled/
    nginx -t && systemctl reload nginx
    ```
  </Tab>

  <Tab value="GoDoxy">
    🚧 En cours de construction 🚧
  </Tab>
</Tabs>

***

## 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://portabase.example.com
```

Une fois modifié, redémarrez le dashboard :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Guide d'utilisation 

































***

## Comprendre l'architecture [#comprendre-larchitecture]

Portabase fonctionne avec deux composants déployés séparément.

**Le Dashboard** centralise la configuration : agents, bases, plannings de sauvegarde, rétention, alertes et canaux de stockage.

**L'Agent** est un binaire Rust installé sur le même réseau que vos bases de données. Il est responsable de :

* détecter et remonter la liste de vos bases automatiquement
* exécuter les sauvegardes selon le planning défini
* envoyer les fichiers vers vos destinations de stockage
* remonter les logs et statuts au dashboard

<Callout type="info">
  Le dashboard ne se connecte jamais directement à vos bases de données. Tout
  passe par l'agent. Cette architecture vous permet de protéger des bases sur
  un réseau privé ou derrière un pare-feu, sans exposer vos serveurs.
</Callout>

<img alt="Architecture Dashboard → Agent → Bases de données" src="__img0" />

L'agent envoie régulièrement un **ping** au dashboard. Ce ping transmet la liste des bases disponibles, le statut de l'agent et les résultats des opérations. En retour, le dashboard envoie les instructions (plannings, ordres de restore, etc.).

### Hiérarchie des entités [#hiérarchie-des-entités]

```
Organisation
├── Agents
│   └── Bases de données (découvertes automatiquement)
│       ├── Assignation à un Projet (optionnelle)
│       ├── Politique de sauvegarde (cron)
│       ├── Politique de rétention
│       ├── Politiques d'alerte  ──→  Canaux de notification
│       └── Politiques de stockage ──→ Canaux de stockage
├── Projets (regroupement logique)
├── Canaux de notification
└── Canaux de stockage
```

***

## Gérer les agents [#gérer-les-agents]

Un agent représente une instance du programme Portabase Agent déployée sur un serveur. Un même agent peut gérer plusieurs bases sur le même serveur. Si vous avez des bases sur plusieurs serveurs, créez un agent par serveur.

### Créer un agent [#créer-un-agent]

<Callout type="warn">
  Prérequis : être `owner` ou `admin` de l'organisation.
</Callout>

<img alt="Liste des agents" src="__img1" />

<Steps>
  <Step>
    Rendez-vous dans **Organisation > Settings > Agents** et cliquez sur **Add agent**.
  </Step>

  <Step>
    Renseignez les champs :

    * **Nom** - identifiant lisible (ex : `Production Server EU`, `Dev Machine`)
    * **Description** - notes libres sur le rôle de cet agent

        <img alt="Formulaire de création d'agent" src="__img2" />

    Validez. L'agent est créé et une **Edge Key** est générée automatiquement.
  </Step>

  <Step>
    Copiez l'**Edge Key** depuis la page de détail de l'agent (bouton **Show Key**), puis collez-la dans la configuration de l'agent Rust sur votre serveur.

        <img alt="Panneau Registration & Setup avec l'Edge Key" src="__img3" />
  </Step>
</Steps>

### Vérifier la connexion [#vérifier-la-connexion]

Au prochain démarrage, l'agent pingue le dashboard. Vous saurez qu'il est connecté quand :

* la colonne **Last Contact** affiche une date récente
* le statut passe au vert dans l'interface

Dès le premier ping, l'agent transmet la liste de toutes les bases qu'il peut voir. &#x2A;*Ces bases apparaissent automatiquement dans le dashboard - vous n'avez rien à créer manuellement.**

### Surveiller la santé d'un agent [#surveiller-la-santé-dun-agent]

Depuis la page de détail d'un agent, l'onglet **Health** affiche l'historique des pings des dernières 12 heures sous forme de grille. Chaque case représente un ping : verte si reçu, rouge si manqué.

<img alt="Grille de santé de l'agent - historique 12h" src="__img4" />

***

## Organiser ses bases avec les projets [#organiser-ses-bases-avec-les-projets]

Un projet est un **dossier logique** pour regrouper plusieurs bases de données. Il n'influence pas l'exécution des sauvegardes - c'est uniquement un outil d'organisation.

Usages typiques : regrouper les bases d'une application, séparer production et staging, organiser par équipe ou client.

### Créer un projet [#créer-un-projet]

<Callout type="warn">
  Prérequis : être `owner` ou `admin` de l'organisation.
</Callout>

1. Rendez-vous dans **Organisation > Projects**
2. Cliquez sur **New project**
3. Donnez un nom au projet, choisissez vos bases de données et validez

<img alt="Formulaire de création de projet" src="__img5" />

***

## Configurer une base de données [#configurer-une-base-de-données]

### Comment les bases apparaissent [#comment-les-bases-apparaissent]

Les bases de données ne se créent pas manuellement. Elles apparaissent automatiquement dès que l'agent connecté les détecte via son ping.

Si une base n'apparaît pas, vérifiez que :

* l'agent est connecté (statut vert, **Last Contact** récent)
* la base est accessible depuis le serveur de l'agent

### Onglets de configuration [#onglets-de-configuration]

Depuis la fiche d'une base (&#x2A;*Projects > \[projet] > \[base]**) :

| Onglet       | Contenu                                  |
| :----------- | :--------------------------------------- |
| **Overview** | KPIs, statut, informations générales     |
| **Backups**  | Liste des sauvegardes, actions manuelles |
| **Restore**  | Restaurations disponibles                |
| **Schedule** | Planning cron + rétention                |
| **Alerts**   | Politiques d'alerte                      |
| **Storage**  | Politiques de stockage                   |
| **Logs**     | Logs détaillés des opérations            |

<img alt="En-tête de base avec les onglets de navigation" src="__img6" />

### Déclencher une sauvegarde manuelle [#déclencher-une-sauvegarde-manuelle]

Depuis l'onglet **Backups**, cliquez sur **Backup now**. La sauvegarde passe en statut `waiting` puis `ongoing` dès que l'agent la prend en charge au prochain ping.

<img alt="Bouton Backup now" src="__img7" />

| Statut    | Signification                                      |
| :-------- | :------------------------------------------------- |
| `waiting` | En attente d'être prise en charge par l'agent      |
| `ongoing` | En cours d'exécution                               |
| `success` | Terminée avec succès                               |
| `failed`  | Échec - consultez l'onglet **Logs** pour le détail |

### Importer une sauvegarde externe [#importer-une-sauvegarde-externe]

1. Depuis l'onglet **Backups**, cliquez sur **Import**
2. Glissez-déposez votre fichier ou parcourez votre système

<img alt="Fenêtre d'import de sauvegarde" src="__img8" />

### Restaurer une base [#restaurer-une-base]

<Callout type="warn">
  La restauration écrase les données actuelles de la base. Assurez-vous d'avoir
  effectué une sauvegarde récente avant toute restauration. La restauration
  n'est pas disponible pour Redis et Valkey.
</Callout>

Depuis l'onglet **Restore**, deux options :

* **Depuis un backup existant** - choisissez un backup dans la liste et cliquez sur **Restore**
* **Depuis un stockage externe** - sélectionnez un fichier disponible dans l'un de vos canaux de stockage

***

## Configurer les canaux [#configurer-les-canaux]

Les canaux sont des connecteurs vers des services externes, utilisables dans deux contextes : **notifications** et **stockage**. Ils se configurent au niveau de l'organisation et peuvent être réutilisés par plusieurs bases.

<Tabs items="[&#x22;Canaux de notification&#x22;, &#x22;Canaux de stockage&#x22;]">
  <Tab value="Canaux de notification">
    **Créer un canal :**

    1. **Organisation > Notifications > Channels > Add channel**
    2. Choisissez le provider

        <img alt="Choisir un provider de notification" src="__img9" />

    3. Renseignez les informations de connexion
    4. Donnez un nom reconnaissable (ex : `Slack #ops-alerts`)
    5. Testez avec le bouton **Test**
    6. Activez le canal

    <Callout type="info">
      Un canal désactivé ne reçoit aucune notification même si des politiques
      d'alerte y sont associées. Utilisez ce flag pour mettre en pause un canal
      sans perdre sa configuration.
    </Callout>
  </Tab>

  <Tab value="Canaux de stockage">
    **Créer un canal :**

    1. **Organisation > Storages > Channels > Add channel**
    2. Choisissez le provider

        <img alt="Choisir un provider de stockage" src="__img10" />

    3. Renseignez les paramètres de connexion
    4. Donnez un nom au canal (ex : `S3 Backup Bucket EU`)
    5. Activez le canal

    <Callout type="warn">
      Le provider **Local** stocke les fichiers sur le serveur de l'agent, pas sur
      le serveur du dashboard. Si l'agent est déplacé ou le disque change, les
      backups locaux ne seront plus accessibles.
    </Callout>
  </Tab>
</Tabs>

***

## Mettre en place les politiques [#mettre-en-place-les-politiques]

Les politiques se configurent au niveau de chaque base de données. Une base peut cumuler plusieurs politiques de différents types.

### Planning de sauvegarde (cron) [#planning-de-sauvegarde-cron]

**Où le configurer :** fiche de la base > onglet **Schedule**

Le planning est une expression cron qui définit quand les sauvegardes automatiques se déclenchent.

```
┌──────── minute (0–59)
│  ┌───── heure (0–23)
│  │  ┌── jour du mois (1–31)
│  │  │  ┌─ mois (1–12)
│  │  │  │  ┌ jour de la semaine (0–7, 0 et 7 = dimanche)
│  │  │  │  │
*  *  *  *  *
```

| Expression    | Résultat                     |
| :------------ | :--------------------------- |
| `0 2 * * *`   | Tous les jours à 2h du matin |
| `0 */6 * * *` | Toutes les 6 heures          |
| `0 2 * * 1`   | Tous les lundis à 2h         |
| `0 2 1 * *`   | Le 1er de chaque mois à 2h   |

Besoin d'aide pour construire une expression ? Utilisez [crontab.guru](https://crontab.guru/?utm_source=portabase.io).

<img alt="Configuration du planning de sauvegarde" src="__img11" />

Pour désactiver les sauvegardes automatiques, passez en mode **Manual**. Vous pourrez toujours déclencher des sauvegardes manuelles depuis le bouton **Backup now**.

<Callout type="warn">
  Supprimer le planning supprime également la politique de rétention associée.
  Si vous remettez un planning, vous devrez reconfigurer la rétention.
</Callout>

### Politique de rétention [#politique-de-rétention]

**Où la configurer :** fiche de la base > onglet **Schedule** > section **Retention**

**Prérequis :** un planning cron doit être actif sur la base.

<Tabs items="[&#x22;count&#x22;, &#x22;days&#x22;, &#x22;gfs&#x22;]">
  <Tab value="count">
    Conserve uniquement les N dernières sauvegardes. Les plus anciennes sont supprimées au fur et à mesure.

    | Paramètre         | Min | Max | Défaut |
    | :---------------- | :-: | :-: | :----: |
    | Nombre de backups |  1  | 100 |    7   |

    Idéal pour les bases en développement ou quand l'espace disque est limité.
  </Tab>

  <Tab value="days">
    Conserve tous les backups des N derniers jours.

    | Paramètre       | Min |  Max  | Défaut |
    | :-------------- | :-: | :---: | :----: |
    | Nombre de jours |  1  | 3 650 |   30   |

    Idéal pour les bases avec des obligations légales de conservation sur une durée précise.
  </Tab>

  <Tab value="gfs">
    La stratégie **Grandfather-Father-Son** conserve le meilleur représentant de chaque période pour maximiser la couverture historique.

    | Niveau           | Ce qui est conservé                        | Défaut | Max |
    | :--------------- | :----------------------------------------- | :----: | :-: |
    | **Journalier**   | Les N derniers jours                       |    7   |  31 |
    | **Hebdomadaire** | Le dernier backup des N dernières semaines |    4   |  52 |
    | **Mensuel**      | Le dernier backup des N derniers mois      |   12   | 120 |
    | **Annuel**       | Le dernier backup des N dernières années   |    3   |  50 |

    Avec les valeurs par défaut : 26 backups maximum pour couvrir 3 ans d'historique.

    Idéal pour les bases de production avec des exigences de conformité long terme.
  </Tab>
</Tabs>

<Callout type="info">
  Il ne peut y avoir qu'une seule politique de rétention par base. Si vous en
  créez une nouvelle, elle remplace l'ancienne automatiquement.
</Callout>

<img alt="Configuration de la politique de rétention" src="__img12" />

### Politiques d'alerte [#politiques-dalerte]

**Où les configurer :** fiche de la base > onglet **Alerts**

**Prérequis :** avoir au moins un canal de notification configuré et activé.

| Événement               | Quand est-il déclenché ?                          |
| :---------------------- | :------------------------------------------------ |
| `error_backup`          | Une sauvegarde échoue                             |
| `success_backup`        | Une sauvegarde réussit                            |
| `error_restore`         | Une restauration échoue                           |
| `success_restore`       | Une restauration réussit                          |
| `error_health_database` | L'agent signale que la base n'est plus accessible |

<Callout type="warn">
  L'événement `weekly_report` n'est pas encore implémenté. Envie de contribuer ?
  Consultez le guide [Contribution](/docs/contributing).
</Callout>

**Créer une politique :**

1. Onglet **Alerts > Add policy**
2. Sélectionnez le canal de notification cible
3. Cochez les événements à surveiller
4. Activez et sauvegardez

<img alt="Panneau des politiques de notification" src="__img13" />

<Callout type="info">
  Vous pouvez créer plusieurs politiques sur une même base - par exemple, Slack
  pour les erreurs et SMTP pour les succès. Chaque politique peut être
  désactivée individuellement sans la supprimer.
</Callout>

### Politiques de stockage [#politiques-de-stockage]

**Où les configurer :** fiche de la base > onglet **Storage**

**Prérequis :** avoir au moins un canal de stockage configuré et activé.

**Créer une politique :**

1. Onglet **Storage > Add policy**
2. Sélectionnez le canal de stockage cible
3. Activez et sauvegardez

<img alt="Panneau des politiques de stockage" src="__img14" />

Vous pouvez créer plusieurs politiques sur une même base. Le fichier de backup sera envoyé **simultanément** vers toutes les destinations actives.

Depuis l'onglet **Backups**, chaque backup affiche le statut d'envoi vers chaque canal :

| Statut    | Signification                                |
| :-------- | :------------------------------------------- |
| `pending` | En attente d'envoi                           |
| `success` | Envoyé (chemin, taille et checksum vérifiés) |
| `failed`  | Échec de l'envoi vers ce canal               |

***

## Référence rapide [#référence-rapide]

| Ce que vous cherchez               | Chemin                                                    |
| :--------------------------------- | :-------------------------------------------------------- |
| Créer un agent                     | **Settings > Agents > Add agent**                         |
| Voir la clé d'un agent             | **Settings > Agents > \[agent] > Show Key**               |
| Créer un projet                    | **Projects > New project**                                |
| Voir les bases d'un agent          | **Settings > Agents > \[agent] > Databases**              |
| Configurer le planning             | **Projects > \[projet] > \[base] > Schedule**             |
| Configurer la rétention            | **Projects > \[projet] > \[base] > Schedule > Retention** |
| Configurer les alertes             | **Projects > \[projet] > \[base] > Alerts**               |
| Configurer le stockage des backups | **Projects > \[projet] > \[base] > Storage**              |
| Ajouter un canal de notification   | **Organisation > Notifications > Channels > Add channel** |
| Ajouter un canal de stockage       | **Organisation > Storages > Channels > Add channel**      |
| Logs de notification               | **Organisation > Notifications > Logs**                   |
| Santé des agents                   | **Settings > Agents > \[agent] > Health**                 |

***

<Cards>
  <Card href="/docs/dashboard/usage/storage/local" title="Configurer le stockage" icon="<DatabaseIcon />" description="Stockage local, S3, Google Drive, Azure Blob Storage." />

  <Card href="/docs/dashboard/usage/notifications/slack" title="Configurer les notifications" icon="<BellIcon />" description="Slack, Discord, Telegram, Email et bien d'autres canaux." />
</Cards>


# Serveur MCP 



Le serveur MCP Portabase expose votre dashboard via le [Model Context Protocol](https://modelcontextprotocol.io/), permettant aux assistants IA (Claude, Cursor, Windsurf, etc.) de gérer les bases de données, les agents et les sauvegardes en langage naturel.

## Prérequis [#prérequis]

* Dashboard Portabase démarré avec `API_ENABLED=true` et `MCP_ENABLED=true`
* Un token d'API (voir [Introduction à l'API](/docs/dashboard/api/introduction))
* Node.js 18+ sur la machine qui fait tourner votre assistant IA

## Activer le MCP [#activer-le-mcp]

Définissez les deux variables d'environnement avant de démarrer votre dashboard :

```bash
API_ENABLED=true
MCP_ENABLED=true
```

* `API_ENABLED=true` : active toutes les routes API sous `/api/v1`
* `MCP_ENABLED=true` : active le serveur MCP à `/api/v1/mcp`

## Connexion [#connexion]

Ajoutez la configuration suivante dans les paramètres MCP de votre assistant, en remplaçant l'URL et le token par les vôtres :

<Tabs items="[&#x22;Claude Desktop&#x22;, &#x22;Cursor / Windsurf&#x22;, &#x22;Autre&#x22;]">
  <Tab value="Claude Desktop">
    Éditez `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :

    ```json
    {
      "mcpServers": {
        "portabase": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://votre-dashboard.exemple.com/api/v1/mcp",
            "--header",
            "x-api-key: VOTRE_TOKEN_API"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Cursor / Windsurf">
    Ouvrez **Paramètres → Serveurs MCP** et ajoutez :

    ```json
    {
      "portabase": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://votre-dashboard.exemple.com/api/v1/mcp",
          "--header",
          "x-api-key: VOTRE_TOKEN_API"
        ]
      }
    }
    ```
  </Tab>

  <Tab value="Autre">
    Tout client compatible MCP acceptant une configuration JSON :

    ```json
    {
      "mcpServers": {
        "portabase": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://votre-dashboard.exemple.com/api/v1/mcp",
            "--header",
            "x-api-key: VOTRE_TOKEN_API"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  Ne commitez jamais votre token API dans le contrôle de version. Utilisez la gestion des secrets de votre environnement pour l'injecter si possible.
</Callout>

## Vérifier la connexion [#vérifier-la-connexion]

Redémarrez votre assistant IA. Demandez-lui :

> "Liste mes bases de données Portabase"

Une réponse réussie confirme que le serveur MCP est connecté.

## Outils disponibles [#outils-disponibles]

Consultez la [référence des outils](/docs/dashboard/mcp/tools) pour la liste complète des opérations.


# Référence des outils MCP 



Le serveur MCP Portabase expose 12 outils regroupés en trois catégories : **Agents**, **Bases de données** et **Sauvegardes**.

***

## Agents [#agents]

### `list_agents` [#list_agents]

Liste tous les agents accessibles à l'utilisateur authentifié.

**Paramètres :** aucun

**Retourne :** Tableau d'objets agent.

***

### `get_agent` [#get_agent]

Récupère les détails d'un agent spécifique, y compris ses bases de données associées.

| Paramètre | Type   | Requis | Description   |
| :-------- | :----- | :----: | :------------ |
| `id`      | string |   Oui  | ID de l'agent |

**Retourne :** Objet agent avec les bases de données associées.

***

### `create_agent` [#create_agent]

Crée un nouvel agent, éventuellement rattaché à une organisation.

| Paramètre        | Type          | Requis | Description                                       |
| :--------------- | :------------ | :----: | :------------------------------------------------ |
| `name`           | string        |   Oui  | Nom de l'agent (min 1 caractère)                  |
| `organizationId` | string (UUID) |   Non  | ID de l'organisation à laquelle rattacher l'agent |

**Retourne :** Objet agent créé.

***

### `delete_agent` [#delete_agent]

Supprime un agent par son ID.

| Paramètre | Type   | Requis | Description   |
| :-------- | :----- | :----: | :------------ |
| `id`      | string |   Oui  | ID de l'agent |

**Retourne :** Message de confirmation.

***

### `get_agent_key` [#get_agent_key]

Récupère la clé edge d'un agent. Cette clé est utilisée par le binaire agent pour s'authentifier auprès de Portabase.

| Paramètre | Type   | Requis | Description   |
| :-------- | :----- | :----: | :------------ |
| `id`      | string |   Oui  | ID de l'agent |

**Retourne :** Objet contenant la clé edge.

<Callout type="warn">
  La clé edge donne accès à votre instance Portabase. Traitez-la comme un mot de passe et ne l'exposez jamais dans des logs ou dans le contrôle de version.
</Callout>

***

## Bases de données [#bases-de-données]

### `list_databases` [#list_databases]

Liste toutes les bases de données accessibles à l'utilisateur authentifié.

**Paramètres :** aucun

**Retourne :** Tableau d'objets base de données.

***

### `get_database` [#get_database]

Récupère les détails d'une base de données spécifique.

| Paramètre | Type   | Requis | Description              |
| :-------- | :----- | :----: | :----------------------- |
| `id`      | string |   Oui  | ID de la base de données |

**Retourne :** Objet base de données.

***

### `get_database_status` [#get_database_status]

Récupère le statut actuel d'une base de données, incluant la dernière sauvegarde et l'état de restauration.

| Paramètre | Type   | Requis | Description              |
| :-------- | :----- | :----: | :----------------------- |
| `id`      | string |   Oui  | ID de la base de données |

**Retourne :** Objet statut avec l'état de sauvegarde et de restauration.

***

## Sauvegardes [#sauvegardes]

### `list_backups` [#list_backups]

Liste toutes les sauvegardes d'une base de données, triées de la plus récente à la plus ancienne.

| Paramètre    | Type   | Requis | Description              |
| :----------- | :----- | :----: | :----------------------- |
| `databaseId` | string |   Oui  | ID de la base de données |

**Retourne :** Tableau d'objets sauvegarde.

***

### `get_backup` [#get_backup]

Récupère les détails d'une sauvegarde spécifique, y compris ses emplacements de stockage.

| Paramètre    | Type   | Requis | Description              |
| :----------- | :----- | :----: | :----------------------- |
| `databaseId` | string |   Oui  | ID de la base de données |
| `backupId`   | string |   Oui  | ID de la sauvegarde      |

**Retourne :** Objet sauvegarde avec un tableau `storages`. Utilisez les valeurs `id` de `storages` comme `backupStorageId` dans `trigger_restore`.

***

### `trigger_backup` [#trigger_backup]

Déclenche une sauvegarde immédiate pour une base de données.

| Paramètre    | Type   | Requis | Description              |
| :----------- | :----- | :----: | :----------------------- |
| `databaseId` | string |   Oui  | ID de la base de données |

**Retourne :** Objet job de sauvegarde.

<Callout type="info">
  Retourne `409 Conflict` si une sauvegarde est déjà en cours pour cette base de données.
</Callout>

***

### `trigger_restore` [#trigger_restore]

Déclenche une restauration de base de données depuis un stockage de sauvegarde spécifique. Utilisez `get_backup` pour trouver les valeurs `backupStorageId` disponibles.

| Paramètre         | Type          | Requis | Description                                                               |
| :---------------- | :------------ | :----: | :------------------------------------------------------------------------ |
| `databaseId`      | string        |   Oui  | ID de la base de données                                                  |
| `backupId`        | string (UUID) |   Oui  | ID de la sauvegarde                                                       |
| `backupStorageId` | string (UUID) |   Oui  | ID du stockage de sauvegarde (depuis la liste `storages` de `get_backup`) |

**Retourne :** Objet job de restauration.

<Callout type="info">
  Retourne `409 Conflict` si une restauration est déjà en cours pour cette base de données.
</Callout>


# Configuration Globale 



Ces variables contrôlent le comportement général de l'authentification et de la sécurité des comptes.

## Paramètres Généraux [#paramètres-généraux]

<TypeTable
  type="{
  AUTH_EMAIL_PASSWORD_ENABLED: {
    description: &#x22;Désactive complètement la connexion traditionnelle par email et mot de passe.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_SIGNUP_ENABLED: {
    description: &#x22;Autorise ou interdit la création de nouveaux comptes par les visiteurs.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_PASSKEY_ENABLED: {
    description: &#x22;Active le support des Passkeys (WebAuthn) pour une connexion sans mot de passe.&#x22;,
    type: 'boolean',
    default: 'false',
  },
  AUTH_SYNC_OIDC_ROLES_ON_LOGIN: {
    description: &#x22;Met à jour les rôles de l'utilisateur à chaque connexion OIDC en fonction des groupes distants.&#x22;,
    type: 'boolean',
    default: 'true',
  },
    TRUSTED_DOMAINS: {
        description: &#x22;Spécifiez les origines de confiance, séparées par des virgules&#x22;,
        type: 'string',
        default: null,
    },
}"
/>

<Callout type="warn">
  Si vous désactivez `AUTH_EMAIL_PASSWORD_ENABLED`, assurez-vous d'avoir configuré au moins un fournisseur OAuth2 ou OIDC fonctionnel, sinon vous pourriez perdre l'accès à votre instance.
</Callout>

## Association de Comptes [#association-de-comptes]

Ces variables contrôlent l'association d'un compte Portabase à un fournisseur OAuth2 ou OIDC. Elles s'appliquent à tous les fournisseurs configurés.

<TypeTable
  type="{
  AUTH_ALLOW_LINKING: {
    description: &#x22;Autorise l'association d'un fournisseur OAuth2 ou OIDC à un compte existant. Si désactivée, un fournisseur ne permet de se connecter qu'à un compte auquel il est déjà associé.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_ALLOW_UNLINKING: {
    description: &#x22;Autorise l'utilisateur à retirer lui-même un fournisseur associé à son compte, depuis le dashboard, une fois l'association définie.&#x22;,
    type: 'boolean',
    default: 'true',
  },
}"
/>

<Callout type="warn">
  Gardez `AUTH_ALLOW_UNLINKING` à `false` lorsque le fournisseur est le seul accès au compte : avec `AUTH_EMAIL_PASSWORD_ENABLED` désactivé et aucune passkey enregistrée, un utilisateur qui retire son dernier fournisseur se coupe l'accès à son compte.
</Callout>

## Recommandations de Sécurité [#recommandations-de-sécurité]

* **Passkeys** : Nous recommandons d'activer `AUTH_PASSKEY_ENABLED` pour offrir une expérience de connexion plus sécurisée et fluide.
* **Inscription** : Pour une instance privée, passez `AUTH_SIGNUP_ENABLED` à `false` après avoir créé vos comptes administrateurs.
* **Association de comptes** : Sur une instance partagée, passez `AUTH_ALLOW_LINKING` à `false` sauf si votre fournisseur vérifie les adresses email. Un fournisseur qui renvoie une adresse non vérifiée pourrait sinon servir à prendre le contrôle d'un compte existant ayant le même email.


# Apprise 



[Apprise](https://github.com/caronc/apprise) est une passerelle de notifications qui relaie un seul message vers plus de 100 services (Discord, Telegram, Slack, email, ntfy, Gotify, et bien d'autres). Portabase communique avec un serveur [Apprise API](https://github.com/caronc/apprise-api) auto-hébergé à l'aide d'une **configuration persistante**.

## Configuration sur votre serveur Apprise API [#configuration-sur-votre-serveur-apprise-api]

<Steps>
  <Step>
    Lancez une instance Apprise API (par exemple l'image Docker `caronc/apprise`) et notez son URL de base (ex: `http://localhost:8000`).
  </Step>

  <Step>
    Enregistrez une **configuration persistante** sous une clé de votre choix. Portabase envoie vers `POST /notify/{key}`, cette clé doit donc exister sur le serveur. Ajoutez les URL des services cibles (Discord, Telegram, etc.) à cette configuration.
  </Step>

  <Step>
    Copiez la **clé de configuration** que vous avez choisie (ex: `my-alerts`).
  </Step>
</Steps>

<Callout type="info">
  Portabase ne stocke pas les URL des services de destination. Elles vivent dans la configuration persistante de
  votre serveur Apprise ; Portabase la référence uniquement via sa clé de configuration.
</Callout>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Apprise**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les informations suivantes :

    * **Channel Name** : Le libellé de ce canal dans Portabase.
    * **Apprise Server URL** : L'URL de base de votre serveur Apprise API (ex: `http://localhost:8000`).
    * **Config Key** : La clé de configuration persistante enregistrée sur votre serveur (ex: `my-alerts`).
    * **Custom Headers** (Optionnel) : Ajoutez des en-têtes si votre serveur est derrière un reverse proxy ou une authentification basique (ex: `Authorization`).

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/apprise/configuration.png" alt="Apprise channel configuration" width="493" height="654" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Le message doit être relayé vers tous les services de votre configuration Apprise.
  </Step>
</Steps>


# Discord 



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]

<Steps>
  <Step>
    Dans Discord, allez dans les **Paramètres du serveur** > **Intégrations** > **Webhooks**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/fr/1.png" alt="Discord configuration" width="1151" height="1079" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Créez un nouveau Webhook et copiez son **URL**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/fr/2.png" alt="Discord configuration" width="1166" height="1079" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Discord**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Saisissez l'URL du webhook Discord obtenue précédemment (ex. : `https://discord.com/api/webhooks/...`) et cliquez sur **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/discord/configuration.png" alt="Discord channel configuration" width="504" height="426" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Email (SMTP) 



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]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Email**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    * **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`).

    <Callout type="info">
      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.
    </Callout>

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/smtp/configuration.png" alt="SMTP channel configuration" width="504" height="789" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Gotify 



[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]

<Steps>
  <Step>
    Connectez-vous à votre instance Gotify.
  </Step>

  <Step>
    Créez une nouvelle **Application** (ex: "Portabase").
  </Step>

  <Step>
    Copiez le **Token** généré pour cette application.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Gotify**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

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

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/gotify/configuration.png" alt="Gotify channel configuration" width="504" height="492" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Healthchecks.io 



[Healthchecks.io](https://healthchecks.io) attend des pings censés arriver à intervalle régulier. Si un ping n'arrive pas à temps, le service vous alerte.

Cela inverse le modèle habituel. Slack ou Discord vous préviennent qu'une sauvegarde a *échoué* ; Healthchecks vous prévient qu'une sauvegarde **ne se produit plus du tout** — un agent planté, une planification en pause, un conteneur jamais redémarré. Ce sont ces pannes silencieuses que l'on remarque trop tard.

<Callout type="info">
  Healthchecks.io est open source. Ces étapes valent aussi bien pour le service hébergé que pour une instance
  auto-hébergée — seule l'URL du serveur de ping change.
</Callout>

## Choisir entre un UUID de check et une clé de ping de projet [#choisir-entre-un-uuid-de-check-et-une-clé-de-ping-de-projet]

Portabase peut adresser vos checks de deux façons. Choisissez avant de configurer le canal.

|                    | UUID de check        | Clé de ping de projet                  |
| ------------------ | -------------------- | -------------------------------------- |
| Ping               | un seul check        | n'importe quel check, adressé par slug |
| Canaux nécessaires | un par check         | un seul pour toutes les bases          |
| Où la trouver      | sur la page du check | dans les paramètres du projet          |

## Configuration sur Healthchecks [#configuration-sur-healthchecks]

<Steps>
  <Step>
    Créez un check et nommez-le, par exemple `portabase-production`.
  </Step>

  <Step>
    Réglez la **Period** sur l'intervalle entre deux sauvegardes, et le **Grace Time** sur le retard que vous tolérez avant d'être alerté. Une sauvegarde quotidienne qui dure une vingtaine de minutes s'accommode d'une période d'un jour et d'un délai de grâce d'une heure.
  </Step>

  <Step>
    Copiez l'**UUID** du check ou, si vous comptez couvrir plusieurs bases depuis un seul canal, copiez plutôt la **clé de ping** dans les paramètres de votre projet.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Healthchecks.io**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les informations suivantes :

    * **Channel Name** : Le libellé de ce canal dans Portabase.
    * **Ping Server URL** : Laissez `https://hc-ping.com` tel quel pour le service hébergé, ou pointez vers votre instance auto-hébergée.
    * **Check UUID or Ping Key** : L'UUID du check, ou la clé de ping du projet si vous souhaitez adresser les checks par slug.
    * **Use database name as slug** (Optionnel) : Un seul canal pour toutes les bases — le slug est dérivé du nom de la base de chaque événement. Nécessite une clé de ping de projet, pas un UUID de check.
    * **Slug** (Optionnel) : Le slug à pinguer. Laissez vide quand le champ précédent contient un UUID de check.
    * **Create missing checks** (Optionnel) : Ajoute `?create=1` pour qu'un slug sans check correspondant soit créé au premier ping. Ignoré lors du ping d'un UUID de check.

    Cliquez ensuite sur **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/healthchecks/configuration.png" alt="Healthchecks.io channel configuration" width="448" height="746" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Le check devrait passer au vert dans Healthchecks en quelques secondes.
  </Step>
</Steps>

<Callout type="warn">
  Traitez l'UUID de check et la clé de ping de projet comme des mots de passe. Quiconque les possède peut marquer vos
  checks comme actifs et masquer une panne réelle.
</Callout>


# Microsoft Teams 



Les notifications Microsoft Teams utilisent un connecteur **Incoming Webhook** pour poster des messages dans un canal spécifique.

## Configuration Microsoft Teams [#configuration-microsoft-teams]

<Steps>
  <Step>
    Dans Teams, allez sur le canal à notifier, puis **Options du canal > Connecteurs** (ou **Workflows** selon votre tenant).
  </Step>

  <Step>
    Ajoutez un connecteur **Incoming Webhook**, donnez-lui un nom (ex : "Portabase"), puis copiez l'**URL du webhook** générée.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Microsoft Teams**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les informations suivantes :

    * **Channel Name** : Le libellé de ce canal dans Portabase.
    * **Teams Webhook URL** : L'URL du webhook obtenue précédemment.

    Cliquez ensuite sur **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/ms-teams/configuration.png" alt="Microsoft Teams channel configuration" width="495" height="412" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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 Teams choisi.
  </Step>
</Steps>


# Ntfy 



[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]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez
    **ntfy.sh**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

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

    <Callout type="warn">
      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.
    </Callout>

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/ntfy/configuration.png" alt="Ntfy channel configuration" width="504" height="790" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Pushover 



[Pushover](https://pushover.net) est un service permettant d'envoyer des notifications push en temps réel sur votre téléphone, tablette ou ordinateur.

## Création d'une application sur Pushover [#création-dune-application-sur-pushover]

<Steps>
  <Step>
    Connectez-vous à votre compte [Pushover](https://pushover.net).
  </Step>

  <Step>
    Allez dans **Create an Application/API Token** et enregistrez une nouvelle application (ex : "Portabase").
  </Step>

  <Step>
    Copiez l'**API Token/Key** générée.
  </Step>

  <Step>
    Sur votre tableau de bord Pushover, copiez votre **User Key** (en haut à droite de la page).
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Pushover**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les informations suivantes :

    * **Channel Name** : Le libellé de ce canal dans Portabase.
    * **User Key** : Votre clé utilisateur personnelle, ou votre **Group Key** pour notifier une équipe.
    * **App API Token** : Le jeton de l'application créée précédemment.
    * **Message Priority** (Optionnel) : La priorité « emergency » se répète toutes les 60 secondes jusqu'à acquittement, pendant une heure au maximum.
    * **Device Name** (Optionnel) : Cible un appareil enregistré précis. Laissez vide pour envoyer à tous.

    Cliquez ensuite sur **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/pushover/configuration.png" alt="Pushover channel configuration" width="501" height="778" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Pour tester la configuration, cliquez sur l'icône d'édition du channel, puis sur **Test Channel**. Le message devrait apparaître instantanément sur votre/vos appareil(s).
  </Step>
</Steps>


# Slack 



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]

<Steps>
  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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**.
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Slack**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Saisissez l'URL du webhook Slack obtenue précédemment `https://hooks.slack.com/services/...` et cliquez sur **Add Channel**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/slack/configuration.png" alt="Slack channel configuration" width="504" height="421" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Telegram 



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]

<Steps>
  <Step>
    Contactez [@BotFather](https://t.me/botfather) sur Telegram pour créer un nouveau bot et obtenir votre
    **Token** (ex: `123456:ABC-DEF1234...`).
  </Step>

  <Step>
    Démarrez une conversation avec votre bot (cliquez sur "Start").
  </Step>

  <Step>
    Récupérez votre **Chat ID** (vous pouvez utiliser un bot comme `@userinfobot` pour le trouver).
  </Step>
</Steps>

<Callout type="warn" title="Attention">
  Vous devez accorder au bot les permissions appropriées (administrateur ou au moins le droit de gérer les topics).
</Callout>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez
    **Telegram**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les informations suivantes :

    * **Bot Token** : Le jeton fourni par BotFather.
    * **Chat ID** : L'identifiant numérique de la conversation ou du groupe.
    * **Topic ID** : L'identifiant numérique du topic que vous souhaitez surveiller (optionnel, pour filtrer les notifications).

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/telegram/configuration.png" alt="Telegram channel configuration" width="499" height="664" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Webhook 



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]

<Steps>
  <Step>
    Allez dans **Notifications > Channels*&#x2A;, cliquez sur **+ Add Notification Channel** et sélectionnez **Webhook**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/choose-provider.png" alt="Choose notification provider" width="452" height="550" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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`.

    <div className=" align-middle justify-items-center">
      <Image src="/static/notifications/webhook/configuration.png" alt="Webhook channel configuration" width="504" height="553" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    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.
  </Step>
</Steps>


# Azure Blob Storage 



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 compte de stockage et d'un conteneur [#création-dun-compte-de-stockage-et-dun-conteneur]

<Steps>
  <Step>
    Allez sur le [portail Azure](https://portal.azure.com) et créez un **Storage Account** (ou utilisez-en un existant).
  </Step>

  <Step>
    Dans le Storage Account, allez dans **Containers** et créez un nouveau conteneur pour vos sauvegardes.
  </Step>

  <Step>
    Allez dans **Access keys** et notez le **nom du compte de stockage** et la **clé**.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Storage > Channels*&#x2A;, cliquez sur **+ Add Storage Channel** et sélectionnez **Azure Blob Storage**.
  </Step>

  <Step>
    Entrez le nom du compte de stockage, la clé et le nom du conteneur notés précédemment.
  </Step>

  <Step>
    Cliquez sur **Add Channel** pour finaliser la configuration.
  </Step>
</Steps>

***

## Vérification [#vérification]

1. Redémarrez votre dashboard :

```bash
portabase restart .
```

2. Connectez-vous à l'interface web.
3. Lancez une sauvegarde manuelle sur un agent.
4. Vérifiez dans votre conteneur Azure que le fichier de sauvegarde est bien présent.


# Google Cloud Storage 



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 compte de service et d'un bucket [#création-dun-compte-de-service-et-dun-bucket]

<Steps>
  <Step>
    Accédez à la [Google Cloud Console](https://console.cloud.google.com) et sélectionnez votre projet (ou créez-en un nouveau).
  </Step>

  <Step>
    Allez dans **Cloud Storage > Buckets** et créez un nouveau bucket pour vos sauvegardes. Notez le **nom du bucket**.
  </Step>

  <Step>
    Allez dans **IAM & Admin > Comptes de service** et créez un nouveau compte de service.
  </Step>

  <Step>
    Assignez le rôle **Administrateur des objets Storage** (`roles/storage.objectAdmin`) au compte de service sur le bucket.
  </Step>

  <Step>
    Dans les détails du compte de service, allez dans **Clés > Ajouter une clé > Créer une clé** et sélectionnez **JSON**. Téléchargez le fichier de clé généré.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Storage > Channels*&#x2A;, cliquez sur **+ Add Storage Channel** et sélectionnez **Google Cloud Storage**.
  </Step>

  <Step>
    Entrez le nom du bucket et collez le contenu du fichier JSON de clé du compte de service.
  </Step>

  <Step>
    Cliquez sur **Add Channel** pour finaliser la configuration.
  </Step>
</Steps>

***

## Vérification [#vérification]

1. Redémarrez votre dashboard :

```bash
portabase restart .
```

2. Connectez-vous à l'interface web.
3. Lancez une sauvegarde manuelle sur un agent.
4. Vérifiez dans votre bucket Google Cloud Console que le fichier de sauvegarde est bien présent.


# Google Drive 



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]

<Steps>
  <Step>
    Allez sur la [Google Cloud Console](https://console.cloud.google.com).
  </Step>

  <Step>
    Dans le menu latéral, accédez à **API et services > Identifiants**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-identifiant.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Cliquez sur **Créer des identifiants > ID client OAuth**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-identifiant-2.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Sélectionnez le type **Application web**, puis configurez en fonction de votre nom de domaine :

    * **Origines JavaScript autorisées**
    * **URL de redirection autorisés**

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/fr/gcc-oauth-2.png" alt="Google Cloud Console configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    Cliquez sur **Créer**, puis notez l’**ID client** et le **Code secret du client** générés.
  </Step>
</Steps>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Storage > Channels*&#x2A;, cliquez sur **+ Add Storage Channel** et sélectionnez **Google Drive**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/choose-provider.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les identifiants précédemment générés.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/google-drive/configuration.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Cliquez sur **Connect Google Drive** pour lancer le flux d’authentification OAuth 2.0.
  </Step>

  <Step>
    Cliquez sur **Add Channel** pour finaliser la configuration.
  </Step>
</Steps>


# Stockage Local 



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 `data` :

```yaml title="docker-compose.yml"
services:
  portabase:
    # ...
    volumes:
      - portabase-data:/data
```

Les sauvegardes sont stockées à l'intérieur de `/data/private/backups`.


# Stockage objet (S3) 



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é]

<Tabs items="[&#x22;MinIO&#x22;, &#x22;RustFS&#x22;]">
  <Tab value="MinIO">
    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`.

    <Callout type="info">
      MinIO utilise deux ports :

      * **9000** : L'API S3 (C'est ce que Portabase utilise).
      * **9001** : La Console Web (Interface d'administration pour vous).
    </Callout>

    ```yaml title="docker-compose.yml"
    name: portabase-stack

    services:
      portabase:
        image: portabase/portabase:latest
        container_name: portabase-app
        env_file: .env
        volumes:
          - portabase-data:/data
        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-data:
      postgres-data:
      minio-data: # Volume persistant pour MinIO

    networks:
      traefik_network:
        external: true
    ```
  </Tab>

  <Tab value="RustFS">
    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
    ```
  </Tab>
</Tabs>

## Configuration sur le tableau de bord [#configuration-sur-le-tableau-de-bord]

<Steps>
  <Step>
    Allez dans **Storage > Channels*&#x2A;, cliquez sur **+ Add Storage Channel** et sélectionnez **S3**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/choose-provider.png" alt="Google Drive configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Entrer les identifiants précédemment générés.

    <div className=" align-middle justify-items-center">
      <Image src="/static/storages/s3/configuration.png" alt="S3 configuration" width="1280" height="1080" className="w-128 border-2" />
    </div>
  </Step>

  <Step>
    Cliquez sur **Add Channel** pour finaliser la configuration.
  </Step>
</Steps>

***

## Vérification [#vérification]

Pour vérifier que la connexion fonctionne :

1. Redémarrez votre dashboard :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>

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.


# Configuration OAuth2 



Portabase prend en charge l'ajout dynamique de fournisseurs OAuth2 grâce à une série de variables `AUTH_SOCIAL_*`. Cette page explique le fonctionnement général, les variables disponibles et la gestion des rôles.

## Mise en place rapide [#mise-en-place-rapide]

<Steps>
  <Step>
    ### Activer un fournisseur [#activer-un-fournisseur]

    Définissez un couple Client ID et Client Secret pour le fournisseur de votre choix (ex: Google, GitHub).
  </Step>

  <Step>
    ### Déployer [#déployer]

    Appliquez ces variables d'environnement sur votre instance Portabase.
  </Step>

  <Step>
    ### Configurer le Callback [#configurer-le-callback]

    Ajoutez l'URL de redirection dans la console du fournisseur :
    `https://<votre-domaine>/api/auth/callback/<providerId>`
  </Step>

  <Step>
    ### Vérifier [#vérifier]

    Testez la connexion depuis la page de login de votre tableau de bord.
  </Step>
</Steps>

## Variables de Configuration [#variables-de-configuration]

Vous pouvez configurer un fournisseur "par défaut" via `AUTH_SOCIAL_*` ou plusieurs fournisseurs via `AUTH_SOCIAL_<NOM>_*`.

<TypeTable
  type="{
  AUTH_SOCIAL_CLIENT: {
    description: &#x22;Client ID fourni par le service OAuth2.&#x22;,
    type: 'string',
  },
  AUTH_SOCIAL_SECRET: {
    description: &#x22;Client Secret fourni par le service OAuth2.&#x22;,
    type: 'string',
  },
  AUTH_SOCIAL_ICON: {
    description: &#x22;Icône à afficher (identifiant Lucide,Iconify ou un lien).&#x22;,
    type: 'string',
    default: 'lucide:building',
  },
  AUTH_ALLOW_LINKING: {
    description: &#x22;Autorise l'association d'un fournisseur à un compte existant.&#x22;,
    type: 'boolean',
    default: 'true',
  },
  AUTH_ROLE_MAP: {
    description: &#x22;Mapping des rôles distants vers les rôles Portabase.&#x22;,
    type: 'string',
  },
}"
/>

L'association d'un fournisseur à un compte existant est contrôlée par `AUTH_ALLOW_LINKING`, et la possibilité pour l'utilisateur de le retirer ensuite par `AUTH_ALLOW_UNLINKING`. Les deux sont décrites dans [Association de Comptes](/docs/dashboard/configuration/auth/configuration#association-de-comptes).

### Fournisseurs dynamiques [#fournisseurs-dynamiques]

Pour ajouter plusieurs services, utilisez le préfixe `AUTH_SOCIAL_<PROVIDER>_*`. Le `providerId` sera la version en minuscules du préfixe.

```bash
# Exemple pour Google
AUTH_SOCIAL_GOOGLE_CLIENT="xxx"
AUTH_SOCIAL_GOOGLE_SECRET="yyy"
AUTH_SOCIAL_GOOGLE_TITLE="Google Enterprise"
```

<Callout type="info">
  Si vous utilisez des noms standards (`google`, `github`, `discord`, etc.), Portabase applique automatiquement l'icône et la couleur de marque correspondantes.
</Callout>

## Gestion des Rôles [#gestion-des-rôles]

La variable `AUTH_ROLE_MAP` permet de faire correspondre les groupes/rôles de votre fournisseur aux rôles internes de Portabase. Elle utilise le format `role_distant:role_portabase`, séparé par des virgules.

* `admin:admin` : Mappe le rôle "admin" distant vers le rôle "admin" local.
* `default:user` : Définit le rôle par défaut si aucune correspondance n'est trouvée.

Exemple complet : `admin:admin,editor:member,default:user`



## Guides de Configuration [#guides-de-configuration]

Choisissez un fournisseur pour voir ses étapes de configuration spécifiques :

<Cards>
  <Card title="Google" href="./configurations/google" icon="<Icon icon=&#x22;logos:google-icon&#x22; />" />

  <Card title="GitHub" href="./configurations/github" icon="<Icon icon=&#x22;logos:github-icon&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Discord" href="./configurations/discord" icon="<Icon icon=&#x22;logos:discord-icon&#x22; />" />

  <Card title="Apple" href="./configurations/apple" icon="<Icon icon=&#x22;logos:apple&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="LinkedIn" href="./configurations/linkedin" icon="<Icon icon=&#x22;logos:linkedin-icon&#x22; />" />

  <Card title="X (Twitter)" href="./configurations/x" icon="<Icon icon=&#x22;logos:twitter&#x22; />" />

  <Card title="Reddit" href="./configurations/reddit" icon="<Icon icon=&#x22;logos:reddit-icon&#x22; />" />
</Cards>


# Configuration OIDC 



L'intégration &#x2A;*OpenID Connect (OIDC)** permet de connecter Portabase à n'importe quel fournisseur d'identité compatible, tel que Keycloak, Auth0, Authentik ou Okta.

## Mise en œuvre [#mise-en-œuvre]

Pour configurer un fournisseur OIDC, vous devez définir un ensemble de variables d'environnement commençant par `AUTH_OIDC_`.

<Steps>
  <Step>
    ### Créer le Client [#créer-le-client]

    Sur votre serveur d'identité (ex: Keycloak), créez un nouveau client de type "OIDC" ou "OpenID Connect".
  </Step>

  <Step>
    ### Configurer les URLs [#configurer-les-urls]

    Définissez l'URL de redirection (Redirect URI) :
    `https://<votre-domaine>/api/auth/sso/callback/<providerId>`
  </Step>

  <Step>
    ### Saisir les Variables [#saisir-les-variables]

    Ajoutez les identifiants obtenus dans votre configuration Portabase.
  </Step>
</Steps>

## Paramètres du Fournisseur [#paramètres-du-fournisseur]

<TypeTable
  type="{
  AUTH_OIDC_ID: {
    description: &#x22;Identifiant interne unique (ex: keycloak). Requis.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_TITLE: {
    description: &#x22;Texte affiché sur le bouton de connexion.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_DESC: {
    description: &#x22;Description courte affichée sous le titre.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_ICON: {
    description: &#x22;Icône à afficher (identifiant Lucide,Iconify ou un lien).&#x22;,
    type: 'string',
  },
  AUTH_OIDC_ISSUER_URL: {
    description: &#x22;URL de l'émetteur (Issuer) pour la découverte automatique.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_CLIENT: {
    description: &#x22;Identifiant client (Client ID). Requis.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_SECRET: {
    description: &#x22;Secret client (Client Secret). Requis.&#x22;,
    type: 'string',
  },
  AUTH_OIDC_SCOPES: {
    description: &#x22;Permissions demandées.&#x22;,
    type: 'string',
    default: 'openid profile email',
  },
  AUTH_OIDC_PKCE: {
    description: &#x22;Active le flux PKCE pour plus de sécurité.&#x22;,
    type: 'boolean',
    default: 'false',
  },
  AUTH_OIDC_HOST: {
    description: &#x22;Adresse interne du serveur OIDC (pour la communication Docker à Docker).&#x22;,
    type: 'string',
  },
}"
/>

L'association d'un fournisseur à un compte existant est contrôlée par `AUTH_ALLOW_LINKING`, et la possibilité pour l'utilisateur de le retirer ensuite par `AUTH_ALLOW_UNLINKING`. Les deux sont décrites dans [Association de Comptes](/docs/dashboard/configuration/auth/configuration#association-de-comptes).

## Plusieurs Fournisseurs [#plusieurs-fournisseurs]

Portabase supporte la configuration de plusieurs fournisseurs OIDC simultanément. Pour ce faire, remplacez le préfixe `AUTH_OIDC_` par `AUTH_OIDC_<NOM>_`.

### Exemple avec Pocket [#exemple-avec-pocket]

```bash
AUTH_OIDC_POCKET_ID="portabase-pocketid"
AUTH_OIDC_POCKET_TITLE="Pocket ID"
AUTH_OIDC_POCKET_DESC=""
AUTH_OIDC_POCKET_ICON="https://github.com/user-attachments/assets/4ceb2708-9f29-4694-b797-be833efce17d"
AUTH_OIDC_POCKET_CLIENT="portabase"
AUTH_OIDC_POCKET_SECRET="dkNOnQwhDQVwLxoNbQOkJioMA3sQIPdk"
AUTH_OIDC_POCKET_ISSUER_URL="http://localhost:3055"
AUTH_OIDC_POCKET_HOST="localhost:8080"
```

<Callout type="info">
  L'utilisation d'un préfixe spécifique permet d'isoler les configurations si vous utilisez plusieurs serveurs d'identité.
</Callout>

## Exemples de Configuration [#exemples-de-configuration]

Découvrez comment intégrer des solutions spécifiques :

<Tabs items="[&#x22;Keycloak&#x22;, &#x22;PocketID&#x22;]">
  <Tab value="Keycloak">
    Découvrez comment configurer Keycloak avec Portabase pour une gestion d'identité d'entreprise.
    [Voir le guide complet](./examples/keycloak)
  </Tab>

  <Tab value="PocketID">
    Une alternative légère pour les auto-hébergeurs.
    [Voir le guide complet](./examples/pocketid)
  </Tab>
</Tabs>

## Groupes et Rôles [#groupes-et-rôles]

Vous pouvez restreindre l'accès à Portabase à un groupe spécifique de votre fournisseur OIDC via la variable `ALLOWED_GROUP`. Si l'utilisateur n'appartient pas à ce groupe, la connexion sera refusée.


# Apple 



L'intégration Apple (Sign in with Apple) permet à vos utilisateurs de se connecter via leur compte Apple, offrant une expérience sécurisée et respectueuse de la vie privée.

<Callout type="warning">
  Sign in with Apple nécessite un compte **Apple Developer** (programme payant).
</Callout>

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Accéder au Apple Developer Portal [#accéder-au-apple-developer-portal]

    Connectez-vous à votre compte sur le [Apple Developer Portal](https://developer.apple.com/account/).
  </Step>

  <Step>
    ### Créer un Identifiant (Services ID) [#créer-un-identifiant-services-id]

    Dans **Certificates, Identifiers & Profiles** > **Identifiers**, créez un nouveau **Services ID**.

    * Sélectionnez le type **Services IDs**.
    * Donnez un nom et un identifiant unique (ex: `com.votre-domaine.portabase`).
  </Step>

  <Step>
    ### Configurer Sign In with Apple [#configurer-sign-in-with-apple]

    Activez **Sign In with Apple** pour ce Services ID et cliquez sur **Configure**.

    * Dans **Primary App ID**, sélectionnez votre application principale ou créez-en une.
    * Dans **Domains and Subdomains**, ajoutez votre domaine (ex: `portabase.votre-domaine.com`).
    * Dans **Return URLs**, ajoutez : `https://portabase.votre-domaine.com/api/auth/callback/apple`
  </Step>

  <Step>
    ### Créer une Clé d'Authentification [#créer-une-clé-dauthentification]

    Dans **Keys**, créez une nouvelle clé.

    * Cochez **Sign In with Apple**.
    * Associez-la au Services ID créé précédemment.
    * Téléchargez le fichier `.p8` (conservez-le, il n'est téléchargeable qu'une seule fois).
  </Step>

  <Step>
    ### Récupérer les Informations [#récupérer-les-informations]

    Notez les éléments suivants :

    * **Services ID** (votre Client ID).
    * **Team ID** (visible dans votre profil Apple Developer).
    * **Key ID** (affiché dans les détails de votre clé).
  </Step>

  <Step>
    ### Générer le Client Secret [#générer-le-client-secret]

    Apple n'utilise pas de secret statique mais un jeton JWT signé. Utilisez un script ou votre pipeline pour générer ce secret en utilisant votre fichier `.p8`.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Ajoutez ces variables à votre configuration :

```bash
AUTH_SOCIAL_APPLE_CLIENT="votre-services-id-apple"
AUTH_SOCIAL_APPLE_SECRET="votre-jwt-signe-apple"
AUTH_SOCIAL_APPLE_APP_BUNDLE_IDENTIFIER="com.votre-domaine.portabase"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Discord 



L'intégration Discord est idéale pour les communautés et les équipes utilisant déjà Discord pour leur communication.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer une nouvelle application [#créer-une-nouvelle-application]

    Rendez-vous sur le [Discord Developer Portal](https://discord.com/developers/applications) et cliquez sur **New Application**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/discord/en/create-new-app.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configurer OAuth2 [#configurer-oauth2]

    Allez dans l'onglet **OAuth2** :

    * Ajoutez l'URL de redirection : `https://portabase.votre-domaine.com/api/auth/callback/discord`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/discord/en/oauth2-configuration.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Sélectionner les permissions [#sélectionner-les-permissions]

    Dans **OAuth2** > **URL Generator**, sélectionnez les scopes `identify` et `email`. Ces permissions sont nécessaires pour créer le compte utilisateur.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/discord/en/oauth2-url-generator.png" alt="GitHub Developer Settings" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Récupérer les identifiants [#récupérer-les-identifiants]

    Copiez le **Client ID**. Cliquez sur **Reset Secret** pour obtenir votre **Client Secret**.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Ajoutez ces lignes à votre configuration :

```bash
AUTH_SOCIAL_DISCORD_CLIENT="votre-client-id-discord"
AUTH_SOCIAL_DISCORD_SECRET="votre-client-secret-discord"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# GitHub 



L'intégration GitHub permet aux développeurs et aux membres de votre organisation de se connecter facilement.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Accéder aux Paramètres Développeur [#accéder-aux-paramètres-développeur]

    Connectez-vous à [GitHub](https://github.com/) et allez dans **Settings** > **Developer settings** > **OAuth Apps**.
  </Step>

  <Step>
    ### Enregistrer une Application [#enregistrer-une-application]

    Cliquez sur **New OAuth App** :

    * **Application name** : Portabase.
    * **Homepage URL** : Votre domaine (ex: `https://portabase.your-domain.com`).
    * **Authorization callback URL** : `https://portabase.your-domain.com/api/auth/callback/github`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/github/en/register-oauth-app.png" alt="GitHub OAuth app creation" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Générer les Clés [#générer-les-clés]

    Cliquez sur **Register application**. Copiez le **Client ID**, puis générez un **Client Secret** et conservez-le précieusement.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Utilisez le préfixe `GITHUB` pour vos variables :

```bash
AUTH_SOCIAL_GITHUB_CLIENT="votre-client-id-github"
AUTH_SOCIAL_GITHUB_SECRET="votre-client-secret-github"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Google 



L'intégration Google permet à vos utilisateurs de se connecter via leur compte Google ou Google Workspace.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Création du Projet [#création-du-projet]

    Accédez à la [Google Cloud Console](https://console.cloud.google.com/) et créez un nouveau projet ou sélectionnez-en un existant.
  </Step>

  <Step>
    ### Écran de Consentement [#écran-de-consentement]

    Rendez-vous dans **APIs & Services** > **OAuth consent screen** :

    * Choisissez le type d'utilisateur : **External** (tout compte Google) ou **Internal** (réservé à votre organisation Workspace).
    * Complétez les informations obligatoires (Nom de l'app, email).
  </Step>

  <Step>
    ### Création des Identifiants [#création-des-identifiants]

    Ouvrez **APIs & Services** > **Credentials**.
    Cliquez sur **Create Credentials** > **OAuth client ID**.
    Sélectionnez **Web application**.
  </Step>

  <Step>
    ### URLs de Redirection [#urls-de-redirection]

    Dans **Authorized redirect URIs**, ajoutez l'URL suivante :
    `https://portabase.votre-domaine.com/api/auth/callback/google`
  </Step>

  <Step>
    ### Récupération des Clés [#récupération-des-clés]

    Validez pour obtenir votre **ID client** et votre **Secret client**.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Ajoutez les variables suivantes à votre fichier `.env` ou à votre configuration Docker :

```bash
AUTH_SOCIAL_GOOGLE_CLIENT="votre-client-id-google"
AUTH_SOCIAL_GOOGLE_SECRET="votre-client-secret-google"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# LinkedIn 



L'intégration LinkedIn permet à vos utilisateurs de s'identifier via leur profil professionnel LinkedIn.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer une Application LinkedIn [#créer-une-application-linkedin]

    Accédez au [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps) et cliquez sur **Create app**.

    * Renseignez le nom, l'organisation (ou profil personnel) et l'URL de votre site.
    * Acceptez les conditions d'utilisation.

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/linkedin/en/create-an-app.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Activer le Produit Sign In with LinkedIn [#activer-le-produit-sign-in-with-linkedin]

    Dans l'onglet **Products**, trouvez **Sign In with LinkedIn** et cliquez sur **Request access**. Cela est nécessaire pour permettre l'authentification.
  </Step>

  <Step>
    ### Configurer OAuth 2.0 [#configurer-oauth-20]

    Allez dans l'onglet **Auth** :

    * Dans **Authorized redirect URLs for your app**, ajoutez : `https://portabase.votre-domaine.com/api/auth/callback/linkedin`
  </Step>

  <Step>
    ### Récupérer les Identifiants [#récupérer-les-identifiants]

    Toujours dans l'onglet **Auth**, vous trouverez votre **Client ID** et votre **Client Secret**.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Utilisez ces variables pour configurer l'authentification LinkedIn :

```bash
AUTH_SOCIAL_LINKEDIN_CLIENT="votre-client-id-linkedin"
AUTH_SOCIAL_LINKEDIN_SECRET="votre-client-secret-linkedin"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Reddit 



L'intégration Reddit permet à vos utilisateurs de se connecter via leur compte Reddit, idéal pour les plateformes communautaires.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Accéder aux Applications Reddit [#accéder-aux-applications-reddit]

    Connectez-vous à votre compte sur [Reddit](https://www.reddit.com/) et rendez-vous sur [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps).

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/reddit/en/authorized-applications.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Créer une Application [#créer-une-application]

    En bas de la page, cliquez sur &#x2A;*Create another app...** :

    * **Name** : Portabase.
    * Sélectionnez **Web app**.
    * **Description** : Plateforme de gestion de données.
    * **Redirect URI** : `https://portabase.votre-domaine.com/api/auth/callback/reddit`

      <div className=" align-middle justify-items-center">
        <Image src="/static/authentication/reddit/en/create-application.png" alt="Reddit - Create application" width="1280" height="1080" className="w-256 border-2" />
      </div>
  </Step>

  <Step>
    ### Récupérer les Identifiants [#récupérer-les-identifiants]

    Après avoir cliqué sur **Create app**, vous verrez :

    * Le **Client ID** (indiqué juste sous le nom de l'application).
    * Le **Client Secret** (indiqué à côté du champ secret).
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Utilisez ces variables pour configurer l'authentification Reddit :

```bash
AUTH_SOCIAL_REDDIT_CLIENT="votre-client-id-reddit"
AUTH_SOCIAL_REDDIT_SECRET="votre-client-secret-reddit"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# X (Twitter) 



L'intégration avec X (Twitter) permet aux utilisateurs de se connecter via leur compte social.

<Callout type="info">
  Consultez la [configuration OAuth2](../setup) pour comprendre les variables globales et la gestion des rôles.
</Callout>

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer une Application [#créer-une-application]

    Connectez-vous à la [Console Twitter](https://console.x.com/) et créez un **Project** ainsi qu'une **App**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/authentication/twitter/fr/developer-enrolment.png" alt="Reddit - Authorized applications" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Paramètres OAuth 2.0 [#paramètres-oauth-20]

    Dans **User authentication settings**, activez **OAuth 2.0** et choisissez le type **Web App, Automated App or Bot**.
  </Step>

  <Step>
    ### URLs et Scopes [#urls-et-scopes]

    * **Callback URL** : `https://portabase.votre-domaine.com/api/auth/callback/x`
    * **Scopes** : Sélectionnez au minimum `users.read` et `tweet.read`.
  </Step>

  <Step>
    ### Identifiants [#identifiants]

    Enregistrez pour obtenir votre **Client ID** et votre **Client Secret**.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Vous pouvez utiliser le préfixe `X` ou `TWITTER` selon vos préférences (assurez-vous que l'URL de callback correspond au préfixe en minuscules).

```bash
AUTH_SOCIAL_X_CLIENT="votre-client-id-x"
AUTH_SOCIAL_X_SECRET="votre-client-secret-x"
```

## Redémarrer le Dashboard [#redémarrer-le-dashboard]

Après avoir mis à jour votre fichier `.env`, redémarrez l'instance :

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)">
    ```bash
    portabase restart .
    ```
  </Tab>

  <Tab value="Via Docker Compose">
    ```bash
    docker-compose down && docker-compose up -d
    ```
  </Tab>
</Tabs>


# Authentik 



L'intégration de [Authentik](https://github.com/goauthentik/authentik) offre une solution d'authentification moderne, idéale pour le self-hosting de votre instance Portabase.

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer une Application [#créer-une-application]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/1.png" alt="Authentik - Configuration de l'application" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Choix du type de fournisseur [#choix-du-type-de-fournisseur]

    Choisissez **OAuth2/OpenID Provider**.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/2.png" alt="Authentik - Choix du type de fournisseur" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configuration du fournisseur OAuth2 [#configuration-du-fournisseur-oauth2]

    Définissez l'URL de redirection autorisée pour permettre le retour vers Portabase après la connexion :

    * **Redirect URLs/Origins**: [https://portabase.your-domain.com/api/auth/sso/callback/authentik](https://portabase.your-domain.com/api/auth/sso/callback/authentik)

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/3.png" alt="Authentik - Configuration du fournisseur OAuth2" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Configuration des liaisons [#configuration-des-liaisons]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/4.png" alt="Authentik - Configuration des liaisons" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Revue de l'application et du fournisseur [#revue-de-lapplication-et-du-fournisseur]

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/authentik/5.png" alt="Authentik - Revue de l'application et du fournisseur" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Configurez Portabase avec les valeurs suivantes. Cet exemple utilise le préfixe dynamique `AUTH_OIDC_AUTHENTIK_` pour isoler la configuration.

```bash
# Identifiant et Titre
AUTH_OIDC_AUTHENTIK_ID="authentik"
AUTH_OIDC_AUTHENTIK_TITLE="Authentik"
AUTH_OIDC_AUTHENTIK_DESC="Connexion via mon instance Authentik"

# Identifiants OIDC
AUTH_OIDC_AUTHENTIK_CLIENT="portabase"
AUTH_OIDC_AUTHENTIK_SECRET="votre-secret-authentik"
AUTHENTIK_ISSUER_URL="https://authentik.your-domain.com/application/o/<authentik-slug>/"
AUTH_OIDC_AUTHENTIK_HOST="authentik:3000" # Si dans le même réseau Docker ou authentik.your-domain.com

# Paramètres Avancés
AUTH_OIDC_AUTHENTIK_SCOPES="openid profile email groups"
AUTH_OIDC_AUTHENTIK_PKCE=true

# Mapping des Rôles
AUTH_OIDC_AUTHENTIK_ROLE_MAP="admin:admin,default:user"
AUTH_OIDC_AUTHENTIK_ALLOW_UNLINKING=false

TRUSTED_DOMAINS="https://{Authentik URL}, https://{Portabase URL}"

```

## Endpoints Spécifiques (Optionnel) [#endpoints-spécifiques-optionnel]

Si la découverte automatique ne fonctionne pas, vous pouvez spécifier manuellement les points de terminaison :

```bash
AUTH_OIDC_AUTHENTIK_DISCOVERY_ENDPOINT="https://authentik.your-domain.com//application/o/<authentik-slug>/.well-known/openid-configuration"
AUTH_OIDC_AUTHENTIK_JWKS_ENDPOINT="https://authentik.your-domain.com//application/o/<authentik-slug>/.well-known/jwks.json"
```


# Keycloak 



L'intégration de [Keycloak](https://www.keycloak.org/) offre une gestion d'identité robuste et des capacités SSO pour votre instance Portabase.

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer un Client [#créer-un-client]

    Connectez-vous à la console d'administration Keycloak, choisissez votre Realm, et créez un nouveau client :

    * **Client type** : `OpenID Connect`.
    * **Client ID** : `portabase`.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/1.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Authentification et Flux [#authentification-et-flux]

    Dans **Capability config**, activez **Client authentication** (Client Confidentiel) et assurez-vous que **Standard flow** est sélectionné.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/2.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Paramètres de Login [#paramètres-de-login]

    Définissez les URLs autorisées :

    * **Valid redirect URIs** : `https://portabase.votre-domaine.com/api/auth/sso/callback/votre-provider-id`

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/keycloak/3.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Récupérer le Secret [#récupérer-le-secret]

    Enregistrez, puis allez dans l'onglet **Credentials** pour copier votre **Client Secret**.
  </Step>

  <div className=" align-middle justify-items-center">
    <Image src="/static/auth/keycloak/4.png" alt="Keycloak configuration" width="1280" height="1080" className="w-256 border-2" />
  </div>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Configurez Portabase avec les valeurs suivantes :

```bash
# Identifiant et Titre
AUTH_OIDC_ID="votre-provider-id"
AUTH_OIDC_TITLE="Keycloak"
AUTH_OIDC_DESC=""
AUTH_OIDC_ICON=""

# Identifiants OIDC
AUTH_OIDC_CLIENT="portabase"
AUTH_OIDC_SECRET="votre-secret-keycloak"
AUTH_OIDC_ISSUER_URL="https://keycloak.your-domain.com/realms/your-realm"
AUTH_OIDC_HOST="keycloak.your-domain.com"

# Paramètres Avancés
AUTH_OIDC_SCOPES="openid profile email"
AUTH_OIDC_PKCE=true

# Mapping des Rôles
AUTH_OIDC_ROLE_MAP="admin:admin,default:pending"

TRUSTED_DOMAINS="https://{Keycloak URL}, https://{Portabase URL}"

```

<Callout type="info">
  Si vous avez changé `AUTH_OIDC_ID`, n'oubliez pas d'ajuster l'URL de redirection dans Keycloak en conséquence.
</Callout>

## Endpoints Spécifiques (Optionnel) [#endpoints-spécifiques-optionnel]

Si la découverte automatique ne fonctionne pas, vous pouvez spécifier manuellement les points de terminaison :

```bash
AUTH_OIDC_POCKET_DISCOVERY_ENDPOINT="https://keycloak.votre-domaine.com/realms/votre-realm/.well-known/openid-configuration"
AUTH_OIDC_POCKET_JWKS_ENDPOINT="https://keycloak.votre-domaine.com/realms/votre-realm/protocol/openid-connect/certs"
```


# PocketID 



L'intégration de [PocketID](https://github.com/pocket-id/pocket-id) offre une solution d'authentification légère, idéale pour le self-hosting de votre instance Portabase.

## Étapes de configuration [#étapes-de-configuration]

<Steps>
  <Step>
    ### Créer une Application [#créer-une-application]

    Connectez-vous à l'interface d'administration de PocketID et créez une nouvelle application :

    * **Nom de l'application** : `portabase` (ou le nom de votre choix).

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/pocketid/1.png" alt="PocketID configuration de l'application" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Paramètres de Redirection [#paramètres-de-redirection]

    Définissez l'URL de redirection autorisée pour permettre le retour vers Portabase après la connexion :

    * **Callback URL / Redirect URI** : `https://portabase.votre-domaine.com/api/auth/sso/callback/pocketid`

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/pocketid/2.png" alt="PocketID configuration de l'URL de redirection" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>

  <Step>
    ### Récupérer les Identifiants [#récupérer-les-identifiants]

    Enregistrez la configuration. Vous pourrez alors copier le **Client ID** et générer votre **Client Secret** pour les ajouter à vos variables d'environnement.

    <div className=" align-middle justify-items-center">
      <Image src="/static/auth/pocketid/3.png" alt="PocketID récupération des identifiants" width="1280" height="1080" className="w-256 border-2" />
    </div>
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Configurez Portabase avec les valeurs suivantes. Cet exemple utilise le préfixe dynamique `AUTH_OIDC_POCKET_` pour isoler la configuration.

```bash
# Identifiant et Titre
AUTH_OIDC_POCKET_ID="pocketid"
AUTH_OIDC_POCKET_TITLE="PocketID"
AUTH_OIDC_POCKET_DESC="Connexion via mon instance PocketID"
AUTH_OIDC_POCKET_ICON="https://github.com/user-attachments/assets/4ceb2708-9f29-4694-b797-be833efce17d"

# Identifiants OIDC
AUTH_OIDC_POCKET_CLIENT="portabase"
AUTH_OIDC_POCKET_SECRET="votre-secret-pocketid"
AUTH_OIDC_POCKET_ISSUER_URL="https://pocketid.your-domain.com"
AUTH_OIDC_POCKET_HOST="pocketid:3000" # Si dans le même réseau Docker ou pocketid.your-domain.com

# Paramètres Avancés
AUTH_OIDC_POCKET_SCOPES="openid profile email groups"
AUTH_OIDC_POCKET_PKCE=true

# Mapping des Rôles
AUTH_OIDC_POCKET_ROLE_MAP="admin:admin,default:user"

AUTH_OIDC_POCKET_ALLOW_UNLINKING=false

TRUSTED_DOMAINS="https://{Pocket ID URL},https://{Portabase URL}"


```

<Callout type="info">
  PocketID permet de transmettre les groupes de l'utilisateur. Utilisez `AUTH_OIDC_POCKET_ROLE_MAP` pour accorder automatiquement le rôle d'administrateur aux membres de votre groupe `admin`.
</Callout>

## Endpoints Spécifiques (Optionnel) [#endpoints-spécifiques-optionnel]

Si la découverte automatique ne fonctionne pas, vous pouvez spécifier manuellement les points de terminaison :

```bash
AUTH_OIDC_POCKET_DISCOVERY_ENDPOINT="https://pocketid.votre-domaine.com/.well-known/openid-configuration"
AUTH_OIDC_POCKET_JWKS_ENDPOINT="https://pocketid.votre-domaine.com/.well-known/jwks.json"
```