• English

      • Quick Start

      If you are deploying Palpo for the first time, follow the steps below to set up a functional Matrix server in minutes. This guide references other sections of the documentation for deeper exploration when needed.

      Prerequisites

      • A 64-bit Linux, macOS, or Windows server with at least 2 vCPUs and 4 GB RAM recommended.
      • PostgreSQL 17 or later. See the PostgreSQL Guide for installation instructions.
      • A publicly accessible domain name, and optionally a reverse proxy (Caddy, Traefik, Nginx, etc.).
      • Docker installed (recommended) or a shell environment capable of running the Palpo executable.

      1. Initialize the Database

      1. Install PostgreSQL for your platform by following the system-specific guides in the Installation section.

      2. Create a dedicated database user and database for Palpo:

        sudo -u postgres psql <<'SQL'
CREATE USER palpo WITH PASSWORD 'change_me';
CREATE DATABASE palpo OWNER palpo;
SQL

        Replace change_me with a strong password. If using the official Docker Compose template, this step can be completed directly via environment variables in the Compose file.

      2. Choose a Deployment Method

      1. Download the example configuration palpo.toml.

      2. Select a Compose template (basic, Caddy, Traefik, etc.) as needed, and rename compose.*.yml to compose.yml.

      3. Modify placeholders such as POSTGRES_PASSWORD and domain name, and create the Docker network for the proxy if required.

      4. Start the services:

        docker compose up -d

      For more details, refer to Docker Deployment.

      Direct Binary Execution

      1. Download the appropriate archive for your system from GitHub Releases.

      2. Extract the archive, copy the example configuration, and edit it:

        cp palpo-example.toml palpo.toml

      3. Follow the system-specific guides (Linux, macOS, Windows) to install dependencies and configure systemd/launchd/services.

      3. Initialize Configuration

      Open palpo.toml and configure at least the following settings:

      • server_name: Set to your primary domain, e.g., example.com.
      • [db].url: Provide the correct PostgreSQL connection string, e.g., postgresql://palpo:change_me@localhost:5432/palpo.
      • listen_addr: Set the local listen address, e.g., 0.0.0.0:8008. If you use a reverse proxy, consider binding to 127.0.0.1:8008.

      For additional options (registration policies, media directory, reverse proxy, TURN, etc.), see the Configuration section.

      4. Start Palpo

      • Docker: Run docker compose up -d or, after modifying the configuration, execute docker compose restart palpo.

      • Local binary: In the directory containing the Palpo executable, run:

        ./palpo --config palpo.toml

      When you see Server started in the logs, the service is listening on ports 8008/8448.

      5. Verify and Next Steps

      1. Visit https://your.domain/_matrix/client/versions. It should return JSON containing palpo, or directly visit https://your.domain to confirm you see “Hello Palpo!”.
      2. Use a client that supports registration tokens (e.g., Element Web) to connect to your server and create the first administrator account.
      3. Execute administrative commands in the #admins room or via palpo --console to generate more registration tokens or manage rooms. For details, see the Administration Guide.

      After completing the basic deployment, it is recommended to:

      Common Issues

      • Port already in use: Change listen_addr in palpo.toml to a different port, e.g., 0.0.0.0:8009.
      • Database connection refused: Verify PostgreSQL is running (systemctl status postgresql or brew services list), and check that the [db].url in palpo.toml matches your database credentials.
      • "Hello Palpo!" not showing: Ensure the domain or IP you are visiting matches server_name in the configuration. If using a reverse proxy, check that requests to /_matrix are being forwarded correctly.
      • Registration fails: Make sure you are using a client that supports registration tokens (e.g., Element Web). Open registration without tokens is disabled by default for security.

      You now have a functional Palpo server ready to invite users and start communicating.