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

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

### `update` [#update-1]

Update 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-1]

<Accordions>
  <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="/docs/dashboard/setup#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="/docs/agent/setup#development" title="Agent Development" icon="<WaypointsIcon />" description="Improve the Python-based agent that handles backups and communication with the dashboard." />

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

***

### General Workflow [#general-workflow]

1. **Fork** the repository you want to contribute to.
2. **Clone** your fork locally.
3. **Create a branch** for your changes.
4. **Commit** your work with clear and concise messages.
5. **Push** to your fork and **open a Pull Request**.

Thank you for helping make Portabase better!

### 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">
  <Accordion title="Why use an agent-based architecture?">
    An agent-based architecture enables decentralized processing and improved scalability. It also makes it easier
    to work with databases that are not publicly exposed, thereby enhancing security.
  </Accordion>

  <Accordion title="Why is it called Portabase?">
    Inspired by Portainer, the name “Portabase” combines “Porta” (from seaport) and “base” (as in database).
    It represents a platform that centralizes and connects multiple data sources.
  </Accordion>

  <Accordion title="How can I join the Portabase community?">
    You can join our community of developers, DBAs, and DevOps engineers on
    [our Discord server](https://discord.gg/Wgv7xZ8fWJ). It is a space to ask questions, share feedback,
    get help with configuration, and stay informed about the latest features and updates.
  </Accordion>
</Accordions>


# Getting Started 



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

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

  <Card href="/docs/agent/setup" 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
```


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

***

## 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** | ❌ Ongoing | -                            | 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 ([documentation](/docs/dashboard/advanced/storage/s3)).
* ✅ **Google Drive**
* [ ] **Azure Blob Storage** : coming soon.
* [ ] **Google Cloud Storage** : coming soon.

<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/dashboard/setup" title="The Dashboard" icon="<DatabaseIcon />" description="The web interface to control your backups, view history, and restore your data if needed." />

  <Card href="/docs/agent/setup" 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+.


# Roadmap 

If you are not redirected, [click here](https://github.com/orgs/Portabase/projects/1).


# 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 v4. Do not invent a simple random string.
</Callout>

**How to generate a UUID:**

* **Terminal**: `uuidgen`.
* **Python**: `python3 -c "import uuid; print(uuid.uuid4())"`.
* **Online**: [https://www.uuidgenerator.net/](https://www.uuidgenerator.net/).

***

## Docker mount [#docker-mount]

If you edit the file manually, ensure it's mounted into the agent container.

```yaml title="docker-compose.yml"
services:
  agent:
    # ...
    volumes:
      - ./databases.json:/config/config.json
```

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


# Installation 



The **Portabase Agent** is a lightweight connector that runs on your servers. Its role is to:

1. Secure the connection with the Dashboard.
2. Execute backup tasks.
3. Manage local (or remote) databases.

It can manage existing databases (already installed on your server) or create new ones via Docker.

***

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    Need to be update, check docker install

    The CLI guides you step by step: it configures the agent and offers to add databases immediately.

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

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

  <Tab value="Via Docker Compose" id="docker">
    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]

        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]

        Create the `docker-compose.yml`. Note the use of `extra_hosts` so the agent can reach the host's services via `localhost`.

        ```yaml title="docker-compose.yml"
        name: portabase-agent

        services:
            app:
                container_name: portabase-agent
                image: portabase/agent:latest
                restart: always
                volumes:
                    # Mount the DB config file
                    - ./databases.json:/config/config.json
                extra_hosts:
                    # Allows the agent to contact the host's 'localhost'
                    - "localhost:host-gateway"
                environment:
                    TZ: "UTC"
                    POLLING: 5
                    APP_ENV: production
                    DATA_PATH: "/data"
                    LOG: info
                    # If you prefer using .toml files, please check configuration section
                    # DATABASES_CONFIG_FILE: "config.toml"
                    EDGE_KEY: "${EDGE_KEY}"
                networks:
                    - portabase

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

        *Note: Create the `portabase_network` manually if it does not exist: `docker network create portabase_network`.*
      </Step>

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

        Add your key and optional configurations to the `.env` file:

        ```bash title=".env"
        EDGE_KEY=your_edge_key_here
        TZ=UTC
        POLLING=5
        APP_ENV=production
        DATA_PATH=/data
        ```

        | Variable    | Description                                                | Default      |
        | :---------- | :--------------------------------------------------------- | :----------- |
        | `EDGE_KEY`  | Your agent's unique key from the dashboard.                | **Required** |
        | `TZ`        | Timezone for the agent (e.g., `UTC`, `Europe/Paris`).      | `UTC`        |
        | `POLLING`   | Frequency (in seconds) to check for new tasks.             | `5`          |
        | `APP_ENV`   | Environment type (`production`, `staging`, `development`). | `production` |
        | `DATA_PATH` | Internal path where the agent stores its data.             | `/data`      |
      </Step>

      <Step>
        ### Start [#start-1]

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

***

## Development [#development]

To set up the agent in a development environment:

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

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

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

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

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

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

***

## Lifecycle commands [#lifecycle-commands]

As with the dashboard, you can control the agent with standard commands:

| Command                      | Description                                                            |
| :--------------------------- | :--------------------------------------------------------------------- |
| `portabase start <path>`     | Start the agent.                                                       |
| `portabase stop <path>`      | Stop the agent.                                                        |
| `portabase logs <path>`      | Check whether the agent is connected to the dashboard ("Ping server"). |
| `portabase uninstall <path>` | Remove the agent and its configuration.                                |


# Portabase vs Databasus 

Portabase and Databasus are two recent tools with user-friendly web interfaces.

## Feature Comparison [#feature-comparison]

| Feature                    |                                     Portabase                                    |                                                 Databasus                                                 |
| -------------------------- | :------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: |
| Multi-DBMS Support         |                    PostgreSQL, MySQL, MariaDB, SQLite, MongoDB                   |                                    PostgreSQL, MySQL, MariaDB, MongoDB                                    |
| Notifications System       |              Telegram, Discord, Webhook, Ntfy, Gotify, Slack, Email              |                              Slack, Discord, Telegram, Teams, Email, Webhooks                             |
| Supported Storage Backends | Local storage, AWS S3 and any S3-compatible service, Cloudflare R2, Google Drive | Local storage, AWS S3 and any S3-compatible service, Cloudflare R2, Google Drive, Azure Blob Storage, NAS |


# Draft 

[//]: # "| Feature | Portabase | Barman | pgBackRest | WAL-G | PgBackWeb | Databasus |"

[//]: # "|---------|:--------:|:------:|:----------:|:-----:|:---------:|:---------:|"

[//]: # "| Supported DB | PostgreSQL, MySQL, MariaDB, MongoDB, SQLite | PostgreSQL | PostgreSQL | PostgreSQL, MySQL, MS SQL | PostgreSQL | PostgreSQL, MySQL, MariaDB, MongoDB |"

[//]: # "| Interface | Web UI | CLI | CLI / config files | CLI | Web UI | Web UI |"

[//]: # "| Agent Architecture | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |"

[//]: # "| Backup type | Logical | Physical | Physical | Incremental | Logical | Logical |"

[//]: # "| Parallel operations | ✅ (backup & restore) | ❌ | ✅ (backup & restore) | ✅ (multi-processor) | ❌ | ✅ (restore only) |"

[//]: # "| Organizations/Teams | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |"

[//]: # "| Notifications | Slack, Discord, Telegram, Webhook, Email, Ntfy, Gotify | Custom scripting | Custom scripting | Custom scripting | Webhooks | Slack, Discord, Teams, Telegram, Email, Webhook |"

[//]: # "| OIDC/OAuth2 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |"

[//]: # "| Scheduler | Built-in (cron and interval) | External | External | External | External | Built-in |"

[//]: # "| Installation | One-line / Docker / CLI | Manual | Manual | Binary / config | Docker / manual | One-line script / Docker |"

[//]: # "| Management of multi-DB / multi-instance | ✅ (via multi-agents) | ❌ | ❌ | ❌ | ✅ (multiple connections) | ✅ |"

[//]: # "| Self-hosted support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |"

[//]: # "| Encryption | AES-256-GCM (optional) | ❌ | ❌ (but supports repo encryption via external means) | GPG / libsodium | ❌ | AES-256-GCM |"

[//]: # "| Storage backends | Local, S3, Cloudflare R2, Google Drive | Local | Local (but supports S3/Azure/GCS/SFTP via repo config) | S3-compatible + others | S3-compatible | Local, S3, Cloudflare R2, Google Drive, Azure Blob, NAS, FTP, SFTP, rclone |"

[//]: # "| Retention policies | ✅ (fixed / time-based / GFS strategies) | ❌ | ❌ (but flexible expiration options) | ❌ | ❌ | ✅ |"

[//]: # "| License | **Apache‑2.0** | **GNU GPL‑3.0** | **MIT** | **Apache‑2.0** | **AGPL‑3.0** | **Apache‑2.0** |"

| Feature                                 |                        Portabase                       |      Barman      |                       pgBackRest                       |           WAL-G           |         PgBackWeb        |                                  Databasus                                 |                    Veeam                    |
| --------------------------------------- | :----------------------------------------------------: | :--------------: | :----------------------------------------------------: | :-----------------------: | :----------------------: | :------------------------------------------------------------------------: | :-----------------------------------------: |
| Supported DB                            |       PostgreSQL, MySQL, MariaDB, MongoDB, SQLite      |    PostgreSQL    |                       PostgreSQL                       | PostgreSQL, MySQL, MS SQL |        PostgreSQL        |                     PostgreSQL, MySQL, MariaDB, MongoDB                    |             PostgreSQL, MySQL\*             |
| Interface                               |                         Web UI                         |        CLI       |                   CLI / config files                   |            CLI            |          Web UI          |                                   Web UI                                   |               Web UI + Console              |
| Agent Architecture                      |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ❌                                     |                      ✅                      |
| Backup type                             |                         Logical                        |     Physical     |                        Physical                        |        Incremental        |          Logical         |                                   Logical                                  |         Incremental & Image/physical        |
| Parallel operations                     |                  ✅ (backup & restore)                  |         ❌        |                  ✅ (backup & restore)                  |    ✅ (multi-processor)    |             ❌            |                              ✅ (restore only)                              |                      ✅                      |
| Organizations/Teams                     |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ✅                                     |                      ✅                      |
| Notifications                           | Slack, Discord, Telegram, Webhook, Email, Ntfy, Gotify | Custom scripting |                    Custom scripting                    |      Custom scripting     |         Webhooks         |               Slack, Discord, Teams, Telegram, Email, Webhook              |                      ✅                      |
| OIDC/OAuth2                             |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ❌                                     |          ✅ (via AD / SSO possible)          |
| Scheduler                               |              Built-in (cron and interval)              |     External     |                        External                        |          External         |         External         |                                  Built-in                                  |                   Built-in                  |
| Installation                            |                 One-line / Docker / CLI                |      Manual      |                         Manual                         |      Binary / config      |      Docker / manual     |                          One-line script / Docker                          |             Installer (Windows)             |
| Management of multi-DB / multi-instance |                  ✅ (via multi-agents)                  |         ❌        |                            ❌                           |             ❌             | ✅ (multiple connections) |                                      ✅                                     |                      ✅                      |
| Self-hosted support                     |                            ✅                           |         ✅        |                            ✅                           |             ✅             |             ✅            |                                      ✅                                     |                      ✅                      |
| Encryption                              |                 AES-256-GCM (optional)                 |         ❌        |                      ❌ (external)                      |      GPG / libsodium      |             ❌            |                                 AES-256-GCM                                |                      ✅                      |
| Storage backends                        |         Local, S3, Cloudflare R2, Google Drive         |       Local      | Local (but supports S3/Azure/GCS/SFTP via repo config) |   S3-compatible + others  |       S3-compatible      | Local, S3, Cloudflare R2, Google Drive, Azure Blob, NAS, FTP, SFTP, rclone | Wide enterprise targets (disk, tape, cloud) |
| Retention policies                      |         ✅ (fixed / time-based / GFS strategies)        |         ❌        |                 ❌ (flexible expiration)                |             ❌             |             ❌            |                                      ✅                                     |                      ✅                      |
| License                                 |                     **Apache‑2.0**                     |  **GNU GPL‑3.0** |                         **MIT**                        |       **Apache‑2.0**      |       **AGPL‑3.0**       |                               **Apache‑2.0**                               | Commercial (VUL / Subscription / Perpetual) |
| Open‑Source                             |                            ✅                           |         ✅        |                            ✅                           |             ✅             |             ✅            |                                      ✅                                     |                      ❌                      |


# 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\"]"


# Portabase vs Veeam 

Portabase and Veeam are both agent-based architecture.

## Feature comparison [#feature-comparison]

| Feature | Portabase | Databasus |
| ------- | :-------: | :-------: |
| lorem   |   lorem   |   lorem   |


# Portabase vs WAL-G 

Portabase and WAL-G are both ...

## Feature comparison [#feature-comparison]

| Feature | Portabase | Databasus |
| ------- | :-------: | :-------: |
| lorem   |   lorem   |   lorem   |


# 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": "..."
    }
    ```
  </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`      | ❌ En cours | -                             | 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>

<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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </Tab>
</Tabs>

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


# 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": "..."
    }
    ```

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

## 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": "..."
    }
    ```

    **Specific Parameters:**

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

## 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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </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>


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

***

## 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. `backup.my-company.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. Nginx example [#2-nginx-example]

    Create a server block that proxies requests to the local port 8887.

    ```nginx title="/etc/nginx/sites-available/portabase"
    server {
        server_name portabase.example.com;

        location / {
            proxy_pass http://portabase:80;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }
    ```
  </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>


# Setup 



The **Portabase Dashboard** is the central interface that allows you to manage your agents, configure your backups, and visualize the state of your infrastructure.

You have 4 methods to install it:

1. **Via CLI**: Ideal for getting started quickly locally.
2. **Via Docker Run**: For quick tests.
3. **Via Docker Compose**: Recommended for advanced production environments or GitOps.
4. **Via Kubernetes (Helm Chart)**: Recommended for advanced production environments or GitOps with knowledge in Kubernetes configuration.

***

<Tabs items="[&#x22;Via CLI (Recommended)&#x22;, &#x22;Via Docker Run&#x22;, &#x22;Via Docker Compose&#x22;, &#x22;Via Kubernetes (Helm Chart)&#x22;]">
  <Tab value="Via CLI (Recommended)" id="cli">
    The CLI takes care of everything: it downloads templates, generates encryption secrets (`PROJECT_SECRET`),
    configures the internal database, and launches the containers.

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

    <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="Via Docker Run" id="docker">
    If you don't want to use the CLI, you can deploy the stack with Docker Run. It is recommended for testing but not for production use, as you will be using the internal PostgreSQL database.

    <Callout type="warn">
      Ensure you already installed Docker engine.
    </Callout>

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

        Run the following command to start the Portabase service.

        ```bash
        docker run -d \
            --name portabase-app-prod \
            -p 8887:80 \
            --restart unless-stopped \
            -e TZ="Europe/Paris" \
            --env-file .env \
            -v ./portabase-data:/data \
            portabase/portabase:latest
        ```
      </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="Via Docker Compose" id="docker-compose">
    If you don't want to use the CLI, you can deploy the stack manually.

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

        ```bash
        mkdir portabase-dashboard && cd portabase-dashboard
        ```

        ### Docker configuration [#docker-configuration-1]

        ```yaml title="docker-compose.yml"
        name: portabase-dashboard

        services:
          portabase:
            container_name: portabase-app
            image: portabase/portabase:latest
            restart: always
            env_file: .env
            environment:
              - TZ=Europe/Paris
            ports:
              - "8887:80"
            volumes:
              - portabase-data:/data
            depends_on:
              db:
                condition: service_healthy

          db:
            container_name: portabase-pg
            image: postgres:17-alpine
            restart: always
            volumes:
              - postgres-data:/var/lib/postgresql/data
            environment:
              - POSTGRES_DB=${POSTGRES_DB}
              - POSTGRES_USER=${POSTGRES_USER}
              - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
            healthcheck:
              test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
              interval: 10s
              timeout: 5s
              retries: 5

        volumes:
          postgres-data:
          portabase-data:
        ```
      </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-2]

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

  <Tab value="Via Kubernetes (Helm Chart)" id="helm">
    For Kubernetes deployments, install directly from the OCI registry.

    ## With ClusterIP + port-forward (for development/testing): [#with-clusterip--port-forward-for-developmenttesting]

    ```bash
    helm install portabase 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>
</Tabs>

***

## Development [#development]

If you want to contribute to the Dashboard or run it 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>

## Daily management (CLI) [#daily-management-cli]

The CLI offers convenient shortcuts to manage your dashboard's lifecycle without having to type complex Docker commands.

| Action        | Command                      | Description                                                  |
| :------------ | :--------------------------- | :----------------------------------------------------------- |
| **Start**     | `portabase start <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). |
| **Uninstall** | `portabase uninstall <path>` | ⚠️ Removes containers **and** data volumes.                  |


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

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


# 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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>


# 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="1280" height="1080" 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="1280" height="1080" 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>


# 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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>


# 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',
  },
}"
/>

### 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="<Icons.Icon icon=&#x22;logos:google-icon&#x22; />" />

  <Card title="GitHub" href="./configurations/github" icon="<Icons.Icon icon=&#x22;logos:github-icon&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Discord" href="./configurations/discord" icon="<Icons.Icon icon=&#x22;logos:discord-icon&#x22; />" />

  <Card title="Apple" href="./configurations/apple" icon="<Icons.Icon icon=&#x22;logos:apple&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Facebook" href="./configurations/facebook" icon="<Icons.Icon icon=&#x22;logos:facebook&#x22; />" />

  <Card title="LinkedIn" href="./configurations/linkedin" icon="<Icons.Icon icon=&#x22;logos:linkedin-icon&#x22; />" />

  <Card title="X (Twitter)" href="./configurations/x" icon="<Icons.Icon icon=&#x22;logos:twitter&#x22; />" />

  <Card title="Reddit" href="./configurations/reddit" icon="<Icons.Icon icon=&#x22;logos:reddit-icon&#x22; />" />

  <Card title="Figma" href="./configurations/figma" icon="<Icons.Icon icon=&#x22;logos:figma&#x22; />" />

  <Card title="TikTok" href="./configurations/tiktok" icon="<Icons.Icon icon=&#x22;logos:tiktok-icon&#x22; className=&#x22;dark:invert&#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',
  },
}"
/>

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


# Figma 



Figma integration allows designers and creative teams to sign in directly with their Figma account.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Create a Figma Application [#create-a-figma-application]

    Log in to your Figma account and go to the [Developers](https://www.figma.com/developers/api#authentication) page.
  </Step>

  <Step>
    ### Register an OAuth App [#register-an-oauth-app]

    Click **Create a new OAuth App**:

    * **App Name**: Portabase.
    * **Description**: Data management platform.
    * **Callback URL**: `https://portabase.your-domain.com/api/auth/callback/figma`
  </Step>

  <Step>
    ### Configure Scopes [#configure-scopes]

    Select at least the `file_read` scope to allow Portabase to validate the user profile during login.
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    Copy your **Client ID**. Click the button to generate and copy your **Client Secret** (will only be displayed once).
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Add these variables to your configuration file:

```bash
AUTH_SOCIAL_FIGMA_CLIENT="your-figma-client-id"
AUTH_SOCIAL_FIGMA_SECRET="your-figma-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>


# TikTok 



TikTok integration allows your users to sign in via their TikTok account, offering a seamless experience for social and creative platforms.

<Callout type="info">
  Check the [OAuth2 configuration](../setup) to understand global variables and role management.
</Callout>

## Configuration Steps [#configuration-steps]

<Steps>
  <Step>
    ### Access TikTok for Developers [#access-tiktok-for-developers]

    Go to the [TikTok for Developers Portal](https://developers.tiktok.com/) and log in.
  </Step>

  <Step>
    ### Create a Project and an Application [#create-a-project-and-an-application]

    Create a new project or select an existing one, then create an **App**.

    * Give your application a name and an icon.
    * Fill in your organization's information.
  </Step>

  <Step>
    ### Configure OAuth [#configure-oauth]

    In the **Auth** section of your application:

    * Add the redirect URL: `https://portabase.your-domain.com/api/auth/callback/tiktok`
    * Select the required scopes, such as `user.info.basic`.
  </Step>

  <Step>
    ### Get Credentials [#get-credentials]

    Once the application is created, you will get your **Client Key** (which serves as the Client ID) and your **Client Secret**.
  </Step>

  <Step>
    ### Submit for Review (Optional) [#submit-for-review-optional]

    For the application to be accessible to all users, submit it for review. In development mode, only test accounts are allowed.
  </Step>
</Steps>

## Environment Variables [#environment-variables]

Add these variables to your TikTok configuration:

```bash
AUTH_SOCIAL_TIKTOK_CLIENT="your-tiktok-client-key"
AUTH_SOCIAL_TIKTOK_SECRET="your-tiktok-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/callback/authentik](https://portabase.your-domain.com/api/auth/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"
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
```

## 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/.well-known/openid-configuration"
AUTH_OIDC_AUTHENTIK_JWKS_ENDPOINT="https://authentik.your-domain.com/.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"
```

<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

```

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

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

### `update` [#update-1]

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

<Accordions>
  <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="/docs/dashboard/setup#développement" 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="/docs/agent/setup#développement" title="Développement Agent" icon="<WaypointsIcon />" description="Améliorez l'agent en Python 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 Go qui orchestre tout l'écosystème." />
</Cards>

***

### Flux de travail général [#flux-de-travail-général]

1. **Forkez** le dépôt auquel vous souhaitez contribuer.
2. **Clonez** votre fork localement.
3. **Créez une branche** pour vos modifications.
4. **Commitez** votre travail avec des messages clairs et concis.
5. **Poussez** sur votre fork et **ouvrez une Pull Request**.

Merci de nous aider à rendre Portabase meilleur !

### 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">
  <Accordion title="Pourquoi l’architecture par agents ?">
    L’architecture orientée agents permet un traitement décentralisé et une meilleure évolutivité. De plus, elle
    facilite la connexion de bases de données non exposées publiquement, renforçant ainsi la sécurité.
  </Accordion>

  <Accordion title="Pourquoi s’appelle-t-il Portabase ?">
    Inspiré de Portainer, le nom « Portabase » combine « Porta » (du port maritime) et « base » (de base de données).
    Il désigne une plateforme qui centralise et connecte différentes sources de données.
  </Accordion>

  <Accordion title="Comment rejoindre la communauté Portabase ?">
    Vous pouvez rejoindre notre communauté de développeurs, DBA et ingénieurs DevOps sur
    [notre serveur Discord](https://discord.gg/Wgv7xZ8fWJ). Cet espace permet de poser des questions, partager
    des retours d’expérience, obtenir de l’aide sur la configuration et rester informé des dernières fonctionnalités
    et mises à jour.
  </Accordion>
</Accordions>


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

<Cards>
  <Card href="/docs/dashboard/setup" 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/agent/setup" 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
```


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

***

## 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** | ❌ En cours | -                            | Yes          |

### Sauvegardes planifiées [#sauvegardes-planifiées]

* **Planification Cron** : Contrôle total sur la fréquence.
* **Déclenchement manuel** : Support des sauvegardes à la demande.

### Solutions de stockage [#solutions-de-stockage]

* ✅ **Système de fichiers local** : Sauvegardes stockées directement sur le serveur.
* ✅ **Compatible S3** : AWS S3, Minio, RustFS, etc ([documentation](/docs/dashboard/advanced/storage/s3)).
* ✅ **Google Drive**
* [ ] **Azure Blob Storage** : à venir.
* [ ] **Google Cloud Storage** : à venir.

<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/dashboard/setup" 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/agent/setup" 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+.


# Roadmap 

Si vous n'êtes pas redirigé, [cliquez ici](https://github.com/orgs/Portabase/projects/1).


# 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 v4 valide. N'inventez pas une chaîne aléatoire simple.
</Callout>

**Comment générer un UUID valide ?**

* **Via terminal** : `uuidgen` (sur Mac/Linux).
* **Via Python** : `python3 -c "import uuid; print(uuid.uuid4())"`.
* **En ligne** : Utilisez un générateur comme [uuidgenerator.net](https://www.uuidgenerator.net/).

***

## Montage dans Docker [#montage-dans-docker]

Si vous modifiez ce fichier manuellement, assurez-vous qu'il est bien monté dans le volume du conteneur Docker de l'agent.

```yaml title="docker-compose.yml"
services:
    agent:
        # ...
        volumes:
            # Montage du fichier local vers le chemin interne de l'agent
            - ./databases.json:/config/config.json

```

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


# Installation 



L'**Agent Portabase** est un connecteur léger qui s'exécute sur vos serveurs. Son rôle est de :

1. Sécuriser la connexion avec le Dashboard.
2. Exécuter les tâches de sauvegarde.
3. Gérer les bases de données locales (ou distantes).

Il peut gérer des bases de données existantes (déjà installées sur votre serveur) ou en créer de nouvelles via Docker.

***

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;, &#x22;Via Docker Compose&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Mise à jour à venir, se référer à l’installation via Docker Compose.

    Le CLI vous guide pas à pas : il configure l'agent et vous propose d'ajouter immédiatement des bases de données.

    <Callout type="warn">
      Assurez-vous que le CLI est installé en premier. Si ce n’est pas le cas, suivez les instructions [ici](/docs/cli#installation).
    </Callout>

    <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 va ajouter un conteneur PostgreSQL ou MariaDB dans le fichier `docker-compose.yml` de l'agent. C'est idéal pour démarrer un nouveau projet propre.

        * **Manual (External/Existing)** : Pour connecter une base de données déjà existante sur votre serveur (ou sur un serveur distant RDS/Managed). Vous devrez fournir l'hôte, le port et les identifiants.
      </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>

  <Tab value="Via Docker Compose" id="docker">
    Pour une installation manuelle, vous devez créer la structure de fichiers et configurer la connexion réseau pour que l'agent puisse voir vos bases de données locales.

    <Steps>
      <Step>
        ### Structure des fichiers [#structure-des-fichiers]

        Créez un dossier et préparez les fichiers nécessaires :

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

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

        Créez le fichier `docker-compose.yml`. Notez l'utilisation de `extra_hosts` qui permet à l'agent d'accéder aux services de l'hôte via `localhost`.

        ```yaml title="docker-compose.yml"
        name: portabase-agent

        services:
            app:
                container_name: portabase-agent
                image: portabase/agent:latest
                restart: always
                volumes:
                    # Montage du fichier de configuration des DBs
                    # - ./databases.toml:/config/config.toml
                    - ./databases.json:/config/config.json
                extra_hosts:
                    # Permet à l'agent de contacter le 'localhost' de la machine hôte
                    - "localhost:host-gateway"
                environment:
                    LOG: info
                    # DATABASES_CONFIG_FILE: "config.toml"
                    TZ: "UTC"
                    POLLING: 5
                    APP_ENV: production
                    DATA_PATH: "/data"
                    EDGE_KEY: "${EDGE_KEY}"
                networks:
                    - portabase

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

        *Note : Vous devez créer le réseau `portabase_network` manuellement si ce n'est pas fait : `docker network create portabase_network`.*
      </Step>

      <Step>
        ### Variables d'environnement [#variables-denvironnement]

        Ajoutez votre clé et les configurations optionnelles dans le fichier `.env` :

        ```bash title=".env"
        EDGE_KEY=coller_votre_clé_ici
        TZ=UTC
        POLLING=5
        APP_ENV=production
        DATA_PATH=/data
        ```

        | Variable    | Description                                                    | Défaut       |
        | :---------- | :------------------------------------------------------------- | :----------- |
        | `EDGE_KEY`  | La clé unique de votre agent récupérée sur le dashboard.       | **Requis**   |
        | `TZ`        | Fuseau horaire de l'agent (ex: `UTC`, `Europe/Paris`).         | `UTC`        |
        | `POLLING`   | Fréquence (en secondes) de vérification des nouvelles tâches.  | `5`          |
        | `APP_ENV`   | Type d'environnement (`production`, `staging`, `development`). | `production` |
        | `DATA_PATH` | Chemin interne où l'agent stocke ses données.                  | `/data`      |
      </Step>

      <Step>
        ### Démarrage [#démarrage]

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

***

## Développement [#développement]

Pour mettre en place l'agent dans un environnement de développement :

<Steps>
  <Step>
    ### Cloner le dépôt [#cloner-le-dépôt]

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

  <Step>
    ### Compiler l'agent [#compiler-lagent]

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

  <Step>
    ### Démarrer en mode développement [#démarrer-en-mode-développement]

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

***

## Commandes de cycle de vie [#commandes-de-cycle-de-vie]

Comme pour le dashboard, vous pouvez piloter l'agent avec les commandes standards :

| Commande                     | Description                                                        |
| :--------------------------- | :----------------------------------------------------------------- |
| `portabase start <path>`     | Démarre l'agent.                                                   |
| `portabase stop <path>`      | Arrête l'agent.                                                    |
| `portabase logs <path>`      | Vérifie si l'agent est bien connecté au dashboard ("Ping server"). |
| `portabase uninstall <path>` | Supprime l'agent et sa configuration.                              |


# Portabase vs Databasus 

# Draft 

[//]: # "| Feature | Portabase | Barman | pgBackRest | WAL-G | PgBackWeb | Databasus |"

[//]: # "|---------|:--------:|:------:|:----------:|:-----:|:---------:|:---------:|"

[//]: # "| Supported DB | PostgreSQL, MySQL, MariaDB, MongoDB, SQLite | PostgreSQL | PostgreSQL | PostgreSQL, MySQL, MS SQL | PostgreSQL | PostgreSQL, MySQL, MariaDB, MongoDB |"

[//]: # "| Interface | Web UI | CLI | CLI / config files | CLI | Web UI | Web UI |"

[//]: # "| Agent Architecture | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |"

[//]: # "| Backup type | Logical | Physical | Physical | Incremental | Logical | Logical |"

[//]: # "| Parallel operations | ✅ (backup & restore) | ❌ | ✅ (backup & restore) | ✅ (multi-processor) | ❌ | ✅ (restore only) |"

[//]: # "| Organizations/Teams | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |"

[//]: # "| Notifications | Slack, Discord, Telegram, Webhook, Email, Ntfy, Gotify | Custom scripting | Custom scripting | Custom scripting | Webhooks | Slack, Discord, Teams, Telegram, Email, Webhook |"

[//]: # "| OIDC/OAuth2 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |"

[//]: # "| Scheduler | Built-in (cron and interval) | External | External | External | External | Built-in |"

[//]: # "| Installation | One-line / Docker / CLI | Manual | Manual | Binary / config | Docker / manual | One-line script / Docker |"

[//]: # "| Management of multi-DB / multi-instance | ✅ (via multi-agents) | ❌ | ❌ | ❌ | ✅ (multiple connections) | ✅ |"

[//]: # "| Self-hosted support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |"

[//]: # "| Encryption | AES-256-GCM (optional) | ❌ | ❌ (but supports repo encryption via external means) | GPG / libsodium | ❌ | AES-256-GCM |"

[//]: # "| Storage backends | Local, S3, Cloudflare R2, Google Drive | Local | Local (but supports S3/Azure/GCS/SFTP via repo config) | S3-compatible + others | S3-compatible | Local, S3, Cloudflare R2, Google Drive, Azure Blob, NAS, FTP, SFTP, rclone |"

[//]: # "| Retention policies | ✅ (fixed / time-based / GFS strategies) | ❌ | ❌ (but flexible expiration options) | ❌ | ❌ | ✅ |"

[//]: # "| License | **Apache‑2.0** | **GNU GPL‑3.0** | **MIT** | **Apache‑2.0** | **AGPL‑3.0** | **Apache‑2.0** |"

| Feature                                 |                        Portabase                       |      Barman      |                       pgBackRest                       |           WAL-G           |         PgBackWeb        |                                  Databasus                                 |                    Veeam                    |
| --------------------------------------- | :----------------------------------------------------: | :--------------: | :----------------------------------------------------: | :-----------------------: | :----------------------: | :------------------------------------------------------------------------: | :-----------------------------------------: |
| Supported DB                            |       PostgreSQL, MySQL, MariaDB, MongoDB, SQLite      |    PostgreSQL    |                       PostgreSQL                       | PostgreSQL, MySQL, MS SQL |        PostgreSQL        |                     PostgreSQL, MySQL, MariaDB, MongoDB                    |             PostgreSQL, MySQL\*             |
| Interface                               |                         Web UI                         |        CLI       |                   CLI / config files                   |            CLI            |          Web UI          |                                   Web UI                                   |               Web UI + Console              |
| Agent Architecture                      |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ❌                                     |                      ✅                      |
| Backup type                             |                         Logical                        |     Physical     |                        Physical                        |        Incremental        |          Logical         |                                   Logical                                  |         Incremental & Image/physical        |
| Parallel operations                     |                  ✅ (backup & restore)                  |         ❌        |                  ✅ (backup & restore)                  |    ✅ (multi-processor)    |             ❌            |                              ✅ (restore only)                              |                      ✅                      |
| Organizations/Teams                     |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ✅                                     |                      ✅                      |
| Notifications                           | Slack, Discord, Telegram, Webhook, Email, Ntfy, Gotify | Custom scripting |                    Custom scripting                    |      Custom scripting     |         Webhooks         |               Slack, Discord, Teams, Telegram, Email, Webhook              |                      ✅                      |
| OIDC/OAuth2                             |                            ✅                           |         ❌        |                            ❌                           |             ❌             |             ❌            |                                      ❌                                     |          ✅ (via AD / SSO possible)          |
| Scheduler                               |              Built-in (cron and interval)              |     External     |                        External                        |          External         |         External         |                                  Built-in                                  |                   Built-in                  |
| Installation                            |                 One-line / Docker / CLI                |      Manual      |                         Manual                         |      Binary / config      |      Docker / manual     |                          One-line script / Docker                          |             Installer (Windows)             |
| Management of multi-DB / multi-instance |                  ✅ (via multi-agents)                  |         ❌        |                            ❌                           |             ❌             | ✅ (multiple connections) |                                      ✅                                     |                      ✅                      |
| Self-hosted support                     |                            ✅                           |         ✅        |                            ✅                           |             ✅             |             ✅            |                                      ✅                                     |                      ✅                      |
| Encryption                              |                 AES-256-GCM (optional)                 |         ❌        |                      ❌ (external)                      |      GPG / libsodium      |             ❌            |                                 AES-256-GCM                                |                      ✅                      |
| Storage backends                        |         Local, S3, Cloudflare R2, Google Drive         |       Local      | Local (but supports S3/Azure/GCS/SFTP via repo config) |   S3-compatible + others  |       S3-compatible      | Local, S3, Cloudflare R2, Google Drive, Azure Blob, NAS, FTP, SFTP, rclone | Wide enterprise targets (disk, tape, cloud) |
| Retention policies                      |         ✅ (fixed / time-based / GFS strategies)        |         ❌        |                 ❌ (flexible expiration)                |             ❌             |             ❌            |                                      ✅                                     |                      ✅                      |
| License                                 |                     **Apache‑2.0**                     |  **GNU GPL‑3.0** |                         **MIT**                        |       **Apache‑2.0**      |       **AGPL‑3.0**       |                               **Apache‑2.0**                               | Commercial (VUL / Subscription / Perpetual) |
| Open‑Source                             |                            ✅                           |         ✅        |                            ✅                           |             ✅             |             ✅            |                                      ✅                                     |                      ❌                      |


# 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                   |     ✅     |    ✅   |      ✅     |   ✅   |     ✅     |       ✅      |   ❌   |


# Portabase vs Veeam 

# Portabase vs WAL-G 

# 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": "..."
    }
    ```
  </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`      | ❌ Ongoing | -                             | 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>

<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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </Tab>
</Tabs>

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


# 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": "..."
    }
    ```

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

## 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": "..."
    }
    ```

    **Paramètres spécifiques :**

    * **database** : (Requis) Le nom exact de la base de données à dumper.
  </Tab>
</Tabs>

## 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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </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": "..."
    }
    ```
  </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>


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

***

## 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.mon-entreprise.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(`backup.exemple.com`)"
          - "traefik.http.routers.portabase.tls.certresolver=myresolver" # Si vous utilisez Let's Encrypt

      db:
        container_name: portabase-pg
        image: postgres:17-alpine
        restart: always
        volumes:
          - postgres-data:/var/lib/postgresql/data
        environment:
          - POSTGRES_DB=${POSTGRES_DB}
          - POSTGRES_USER=${POSTGRES_USER}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
          interval: 10s
          timeout: 5s
          retries: 5
        networks:
          - default

    volumes:
      postgres-data:
      portabase-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">
    ### 1. Configuration Portabase [#1-configuration-portabase]

    Modifiez votre fichier `docker-compose.yml` pour supprimer l'exposition directe du port.

    ### 2. Configuration Nginx [#2-configuration-nginx]

    Créez un bloc serveur (vhost) qui proxy les requêtes vers le port interne.

    ```nginx title="/etc/nginx/sites-available/portabase"
    server {
        server_name backup.example.com;

        location / {
            proxy_pass http://portabase:80;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }
    ```
  </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://backup.exemple.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>


# Mise en route 



Le **Dashboard Portabase** est l'interface centrale qui vous permet de gérer vos agents, configurer vos sauvegardes et visualiser l'état de votre infrastructure.

Vous avez deux méthodes pour l'installer :

1. **Via CLI** : Idéal pour démarrer rapidement en local.
2. **Via Docker Run** : Pour des tests rapides.
3. **Via Docker Compose** : Recommandé pour des environnements de production avancés ou GitOps.
4. **Via Kubernetes (Helm Chart)** : Recommandé pour des environnements de production avancés ou GitOps, avec des connaissances en configuration Kubernetes.

***

<Tabs items="[&#x22;Via CLI (Recommandé)&#x22;,&#x22;Via Docker CLI&#x22;, &#x22;Via Docker Compose&#x22;, &#x22;Via Kubernetes (Helm Chart)&#x22;]">
  <Tab value="Via CLI (Recommandé)" id="cli">
    Le CLI s'occupe de tout : il télécharge les templates, génère les secrets de chiffrement (`PROJECT_SECRET`),
    configure la base de données interne et lance les conteneurs.

    <Callout type="warn">
      Assurez-vous que le CLI est installé en premier. Si ce n’est pas le cas, suivez les instructions
      [ici](/docs/cli#installation).
    </Callout>

    <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="Via Docker CLI" id="docker">
    Si vous ne souhaitez pas utiliser la CLI, vous pouvez déployer avec Docker. Cela est recommandé pour les tests, mais pas pour un usage en production, car vous utiliserez la base de données PostgreSQL interne.

    <Callout type="warn">
      Assurez-vous d’avoir déjà installé Docker.
    </Callout>

    <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 tableau de bord [#démarrer-le-tableau-de-bord]

        Exécutez la commande suivante pour lancer le service Portabase.

        ```bash
        docker run -d \
            --name portabase-app-prod \
            -p 8887:80 \
            --restart unless-stopped \
            -e TZ="Europe/Paris" \
            --env-file .env \
            -v ./portabase-data:/data \
            portabase/portabase:latest
        ```
      </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)**.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Via Docker Compose" id="docker-compose">
    Si vous ne souhaitez pas utiliser le CLI, vous pouvez déployer avec Docker Compose.

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

        ```bash
        mkdir portabase-dashboard && cd portabase-dashboard
        ```

        ### Configuration Docker [#configuration-docker-1]

        ```yaml title="docker-compose.yml"
        name: portabase-dashboard

        services:
            portabase:
                container_name: portabase-app
                image: portabase/portabase:latest
                restart: always
                env_file: .env
                environment:
                    - TZ=Europe/Paris
                ports:
                    - "8887:80"
                volumes:
                    - portabase-data:/data
                depends_on:
                    db:
                        condition: service_healthy

            db:
                container_name: portabase-pg
                image: postgres:17-alpine
                restart: always
                volumes:
                    - postgres-data:/var/lib/postgresql/data
                environment:
                    - POSTGRES_DB=${POSTGRES_DB}
                    - POSTGRES_USER=${POSTGRES_USER}
                    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
                healthcheck:
                    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
                    interval: 10s
                    timeout: 5s
                    retries: 5

        volumes:
            postgres-data:
            portabase-data:
        ```
      </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-1]

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

      <Step>
        ### Accéder à l'interface [#accéder-à-linterface-2]

        Ouvrez votre navigateur : &#x2A;*[http://localhost:8887](http://localhost:8887)**.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Via Kubernetes (Helm Chart)" id="helm">
    Pour les déploiements Kubernetes, installez directement depuis le registre OCI.

    ## Avec ClusterIP + port-forward (pour le développement/test) : [#avec-clusterip--port-forward-pour-le-développementtest-]

    ```bash
    helm install portabase 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 (pour les environnements cloud) : [#avec-loadbalancer-pour-les-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 basé sur le domaine) : [#avec-ingress-accès-basé-sur-le-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>
</Tabs>

***

## Développement [#développement]

Si vous souhaitez contribuer au Dashboard ou l'exécuter 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>

## Gestion quotidienne (CLI) [#gestion-quotidienne-cli]

Le CLI offre des raccourcis pratiques pour gérer le cycle de vie de votre dashboard sans avoir à taper des commandes Docker complexes.

| Action           | Commande                     | Description                                                  |
| :--------------- | :--------------------------- | :----------------------------------------------------------- |
| **Démarrer**     | `portabase start <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). |
| **Désinstaller** | `portabase uninstall <path>` | ⚠️ Supprime les conteneurs **et** les volumes de données.    |


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

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


# 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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>


# 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="1280" height="1080" 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="1280" height="1080" 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>


# 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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="1280" height="1080" 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>


# 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',
  },
}"
/>

### 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="<Icons.Icon icon=&#x22;logos:google-icon&#x22; />" />

  <Card title="GitHub" href="./configurations/github" icon="<Icons.Icon icon=&#x22;logos:github-icon&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Discord" href="./configurations/discord" icon="<Icons.Icon icon=&#x22;logos:discord-icon&#x22; />" />

  <Card title="Apple" href="./configurations/apple" icon="<Icons.Icon icon=&#x22;logos:apple&#x22; className=&#x22;dark:invert&#x22; />" />

  <Card title="Facebook" href="./configurations/facebook" icon="<Icons.Icon icon=&#x22;logos:facebook&#x22; />" />

  <Card title="LinkedIn" href="./configurations/linkedin" icon="<Icons.Icon icon=&#x22;logos:linkedin-icon&#x22; />" />

  <Card title="X (Twitter)" href="./configurations/x" icon="<Icons.Icon icon=&#x22;logos:twitter&#x22; />" />

  <Card title="Reddit" href="./configurations/reddit" icon="<Icons.Icon icon=&#x22;logos:reddit-icon&#x22; />" />

  <Card title="Figma" href="./configurations/figma" icon="<Icons.Icon icon=&#x22;logos:figma&#x22; />" />

  <Card title="TikTok" href="./configurations/tiktok" icon="<Icons.Icon icon=&#x22;logos:tiktok-icon&#x22; className=&#x22;dark:invert&#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',
  },
}"
/>

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


# Figma 



L'intégration Figma permet aux designers et aux équipes créatives de se connecter directement avec leur compte Figma.

<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 Figma [#créer-une-application-figma]

    Connectez-vous à votre compte Figma et accédez à la page [Developers](https://www.figma.com/developers/api#authentication).
  </Step>

  <Step>
    ### Enregistrer une OAuth App [#enregistrer-une-oauth-app]

    Cliquez sur **Create a new OAuth App** :

    * **App Name** : Portabase.
    * **Description** : Plateforme de gestion de données.
    * **Callback URL** : `https://portabase.votre-domaine.com/api/auth/callback/figma`
  </Step>

  <Step>
    ### Configurer les Scopes [#configurer-les-scopes]

    Sélectionnez au minimum le scope `file_read` pour permettre à Portabase de valider le profil utilisateur lors de la connexion.
  </Step>

  <Step>
    ### Récupérer les Identifiants [#récupérer-les-identifiants]

    Copiez votre **Client ID**. Cliquez sur le bouton pour générer et copier votre **Client Secret** (ne sera affiché qu'une seule fois).
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Ajoutez ces variables à votre fichier de configuration :

```bash
AUTH_SOCIAL_FIGMA_CLIENT="votre-client-id-figma"
AUTH_SOCIAL_FIGMA_SECRET="votre-client-secret-figma"
```

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


# TikTok 



L'intégration TikTok permet à vos utilisateurs de se connecter via leur compte TikTok, offrant une expérience fluide pour les plateformes sociales et créatives.

<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 TikTok for Developers [#accéder-au-tiktok-for-developers]

    Rendez-vous sur le [TikTok for Developers Portal](https://developers.tiktok.com/) et connectez-vous.
  </Step>

  <Step>
    ### Créer un Projet et une Application [#créer-un-projet-et-une-application]

    Créez un nouveau projet ou sélectionnez-en un existant, puis créez une **App**.

    * Donnez un nom et une icône à votre application.
    * Remplissez les informations sur votre organisation.
  </Step>

  <Step>
    ### Configurer OAuth [#configurer-oauth]

    Dans la section **Auth** de votre application :

    * Ajoutez l'URL de redirection : `https://portabase.votre-domaine.com/api/auth/callback/tiktok`
    * Sélectionnez les scopes requis, tels que `user.info.basic`.
  </Step>

  <Step>
    ### Récupérer les Identifiants [#récupérer-les-identifiants]

    Une fois l'application créée, vous obtiendrez votre **Client Key** (qui sert de Client ID) et votre **Client Secret**.
  </Step>

  <Step>
    ### Soumettre pour Revue (Optionnel) [#soumettre-pour-revue-optionnel]

    Pour que l'application soit accessible à tous les utilisateurs, soumettez-la pour révision. En mode développement, seuls les comptes de test sont autorisés.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Ajoutez ces variables à votre configuration TikTok :

```bash
AUTH_SOCIAL_TIKTOK_CLIENT="votre-client-key-tiktok"
AUTH_SOCIAL_TIKTOK_SECRET="votre-client-secret-tiktok"
```

## 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/callback/authentik](https://portabase.your-domain.com/api/auth/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"
AUTH_OIDC_AUTHENTIK_ISSUER_URL="https://authentik.your-domain.com"
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
```

## 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.votre-domaine.com/.well-known/openid-configuration"
AUTH_OIDC_AUTHENTIK_JWKS_ENDPOINT="https://authentik.votre-domaine.com/.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"
```

<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

```

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


# Facebook 



L'intégration Facebook Login permet à vos utilisateurs de s'authentifier via leur compte Facebook ou Instagram.

<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 Meta [#créer-une-application-meta]

    Accédez à [Meta for Developers](https://developers.facebook.com/) et créez une nouvelle application (**Create App**).

    * Sélectionnez le type **Consumer** (ou celui adapté à vos besoins).
    * Donnez un nom et renseignez les informations de contact.
  </Step>

  <Step>
    ### Ajouter Facebook Login [#ajouter-facebook-login]

    Dans le tableau de bord de votre application, trouvez **Facebook Login** et cliquez sur **Set Up**.

    * Sélectionnez **Web** comme plateforme.
    * Configurez les paramètres de base.
  </Step>

  <Step>
    ### Configurer les URLs de Redirection [#configurer-les-urls-de-redirection]

    Allez dans **Facebook Login** > **Settings** :

    * Dans **Valid OAuth Redirect URIs**, ajoutez : `https://portabase.votre-domaine.com/api/auth/callback/facebook`
    * Activez les options **Client OAuth Login** et **Web OAuth Login**.
  </Step>

  <Step>
    ### Récupérer les Clés de l'Application [#récupérer-les-clés-de-lapplication]

    Rendez-vous dans **Settings** > **Basic** :

    * Copiez l'**App ID** (votre Client ID).
    * Cliquez sur **Show** pour copier votre **App Secret**.
  </Step>

  <Step>
    ### Passer en Mode Live (Optionnel) [#passer-en-mode-live-optionnel]

    Pour permettre à tous les utilisateurs Facebook de se connecter, basculez l'interrupteur **App Mode** de **Development** à **Live** en haut de la page.
  </Step>
</Steps>

## Variables d'environnement [#variables-denvironnement]

Utilisez ces variables dans votre configuration :

```bash
AUTH_SOCIAL_FACEBOOK_CLIENT="votre-app-id-facebook"
AUTH_SOCIAL_FACEBOOK_SECRET="votre-app-secret-facebook"
```

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