Installation

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

You have two methods to install it:

Via CLI: Ideal for getting started quickly locally.
Via Docker Compose: Recommended for advanced production environments or GitOps.

The CLI takes care of everything: it downloads templates, generates encryption secrets (PROJECT_SECRET), configures the internal database, and launches the containers.

Ensure the CLI is installed first. If it isn’t, follow the instructions here.

Create the Dashboard

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

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

portabase dashboard my-dashboard --port 8887

Start the service

If you didn't use the --start option during creation, start the service manually:

portabase start my-dashboard

Access the interface

Open your browser: http://localhost:8887 (or the chosen port).

If you don't want to use the CLI, you can deploy the stack manually.

File structure

Create a folder and place two files in it: docker-compose.yml and .env.

mkdir portabase-dashboard && cd portabase-dashboard

Docker configuration

mkdir portabase-dashboard && cd portabase-dashboard

Docker configuration

docker-compose.yml

name: portabase-dashboard

services:
  portabase:
    container_name: portabase-app
    image: portabase/portabase:latest
    restart: always
    env_file: .env
    environment:
      - TZ=Europe/Paris
    ports:
      - "${HOST_PORT:-8887}:80"
    volumes:
      - portabase-private:/app/private
    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-private:

Environment variables

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

.env

# --- App Configuration ---
HOST_PORT=8887
PROJECT_NAME=portabase-dashboard
PROJECT_URL=http://localhost:8887

# ⚠️ GENERATE A STRONG SECRET (e.g., openssl rand -hex 32)
# This secret is used to encrypt communications with agents.
PROJECT_SECRET=change_me_please_generate_a_secure_hex_token

# --- Internal Database Configuration ---
POSTGRES_DB=portabase
POSTGRES_USER=portabase
POSTGRES_PASSWORD=change_me_secure_db_password
POSTGRES_HOST=db

# Connection URL (do not modify the structure)
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}?schema=public

Startup

docker compose up -d

Development

If you want to contribute to the Dashboard or run it from source:

Clone the repository

git clone https://github.com/Portabase/portabase.git
cd portabase

Install dependencies

pnpm install

Environment configuration

Copy the example environment file and adjust values if necessary:

cp .env.example .env

Start in development mode

make up

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.

Installation

On this page