Palpo Build Guide
This document provides detailed instructions for building the Palpo Matrix server on various platforms.
Table of Contents
System Requirements
Basic Requirements
macOS/Linux Build
1. Install Dependencies
macOS
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install dependencies
brew install postgresql cmake
Additional resources:
Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
curl \
build-essential \
libclang-dev \
libpq-dev \
cmake \
postgresql \
postgresql-contrib
See also:
CentOS/RHEL/Fedora
# CentOS/RHEL
sudo yum install -y gcc gcc-c++ cmake postgresql-devel clang-devel
# Fedora
sudo dnf install -y gcc gcc-c++ cmake postgresql-devel clang-devel
Learn more:
2. Install Rust and Diesel CLI
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
# (Optional) Install Diesel CLI (PostgreSQL support)
cargo install diesel_cli --no-default-features --features postgres
Additional resources:
3. Clone and Build Project
# Clone project
git clone https://github.com/palpo/palpo.git
cd palpo
Next:
Database Configuration: Database Configuration
Development Environment Setup: Development Environment Setup
Windows Build
1. Install Dependencies
Using Chocolatey (Recommended)
# Run PowerShell as Administrator
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
# Install dependencies
choco install rust postgresql cmake git
See also:
2. Install Diesel CLI (Optional)
# Install Diesel CLI
cargo install diesel_cli --no-default-features --features postgres
3. Set Environment Variables
# Add to system PATH (adjust according to actual installation paths)
$env:PATH += ";C:\Program Files\PostgreSQL\15\bin"
$env:PATH += ";C:\Program Files\CMake\bin"
4. Build Project
# Clone project
git clone https://github.com/palpo/palpo.git
cd palpo
Next:
Database Configuration: Database Configuration
Development Environment Setup: Development Environment Setup
5. Windows WSL Build (Optional)
We recommend using the WSL environment for development on Windows systems. WSL (Windows Subsystem for Linux) allows you to run Linux command-line tools on Windows. For installation instructions, see the official guide: WSL Installation and Configuration.
Choose a Linux distribution you're familiar with, such as Debian or Ubuntu, as your WSL subsystem. Then follow the Linux development configuration from the previous section.
You can also use WSL to cross-compile Windows executable files. See: Cross-compilation and Installation in WSL Environment
Development Environment Setup: Development Environment Setup
Database Configuration
1. Create Database and User
macOS/Linux
# Start PostgreSQL
sudo systemctl start postgresql # Linux
brew services start postgresql # macOS
# Create database and user
sudo -u postgres psql -c "CREATE USER palpo_dev WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE palpo_dev OWNER palpo_dev;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE palpo_dev TO palpo_dev;"
Windows
# Start PostgreSQL service
net start postgresql-x64-15 # Adjust according to version
# Connect to database
psql -U postgres
Execute in psql
-- Create user
CREATE USER palpo WITH PASSWORD 'your_password';
-- Create database
CREATE DATABASE palpo OWNER palpo;
-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE palpo TO palpo;
-- Exit
\q
Reference:
Set environment variables or create a .env file:
# Method 1: Set environment variables
export DATABASE_URL="postgres://palpo:your_password@localhost:5432/palpo"
# Method 2: Create .env file
echo "DATABASE_URL=postgres://palpo:your_password@localhost:5432/palpo" > .env
3. Run Database Migrations (Optional)
Palpo now supports automated migrations, so manual migration commands are usually not required.
If you need to run migrations manually, execute the following commands.
# Navigate to data crate directory
cd crates/data
# Run migrations (create all tables and indexes)
diesel migration run
# Verify migration status
diesel migration list
4. Migration Management Commands (Optional)
# Check migration status
diesel migration list
# Rollback last migration
diesel migration revert
# Rerun all migrations
diesel migration redo
# Generate new migration file (for development)
diesel migration generate migration_name
Learn more:
5. Verify Database Structure
Connect to the database to verify successful table creation:
psql -U palpo -d palpo -h localhost
-- View all tables
\dt
-- View table structure examples
\d users
\d rooms
\d events
-- Exit
\q
Docker Development Environment
1. Build Palpo Container Image
We recommend using the official Rust Docker image to build Palpo. Reference configuration: Dockerfile
FROM rust:bookworm AS builder
WORKDIR /work
RUN apt-get update && apt-get install -y --no-install-recommends \
libclang-dev libpq-dev cmake postgresql postgresql-contrib
COPY Cargo.toml Cargo.toml
COPY crates crates
RUN cargo build --release
FROM debian:bookworm
WORKDIR /var/palpo
COPY --from=builder /work/target/release/palpo /var/palpo/palpo
# COPY crates/server/palpo-example.toml /var/palpo/palpo.toml
RUN apt-get update && apt-get install -y debian-keyring \
debian-archive-keyring apt-transport-https ca-certificates \
libpq-dev &&\
mkdir -p /var/palpo/media /var/palpo/certs /var/palpo/acme
ENV PALPO_CONFIG=/var/palpo/palpo.toml
ENV RUST_LOG="palpo=warn,palpo_core=error,salvo=error"
ENV LOG_FORMAT=json
EXPOSE 8008 8448
CMD /var/palpo/palpo
Save the Dockerfile as Dockerfile.palpo, place it in a separate directory, and build the image:
docker build -t palpo-dev -f Dockerfile.palpo .
Verify the built image:
docker images | grep palpo-dev
To run and test the image using Docker Compose, see: Docker Compose Configuration. Configure the palpo image to use your local palpo-dev image.
Before starting, edit the configuration file:
# Copy and edit configuration file
cp palpo.toml.example palpo.toml
# Edit palpo.toml to set your server name and database connection
Start services (includes automatic database migration): docker compose up -d.
Additional resources:
2. Docker Environment Database Migrations (Optional)
Database migrations in the Docker environment run automatically, but you can execute them manually if needed:
# Check migration status
docker compose exec palpo diesel migration list
# Run migrations manually
docker compose exec palpo diesel migration run
# Enter container for debugging if needed
docker compose exec palpo bash
Development Environment Setup
- rustfmt is Rust's code formatting tool.
- clippy is a code analysis tool.
- cargo-watch is a cargo watch tool for auto-reloading.
- cargo-edit is a cargo dependency management tool for adding dependencies.
# Install Rust development tools
rustup component add rustfmt clippy
# Install cargo extensions
cargo install cargo-watch cargo-edit
Reference:
2. Set Up Development Database
# Create development database
createdb palpo_dev
# Set development environment variables
export DATABASE_URL="postgres://palpo:your_password@localhost:5432/palpo_dev"
# Run migrations (optional)
cd crates/data
diesel migration run
3. Run Development Server
# Copy example configuration
cp crates/server/palpo.toml palpo-dev.toml
# Edit configuration file for development environment
# Modify server_name, listen_addr, database connection, etc.
# Run development server
PALPO_CONFIG=palpo-dev.toml cargo run
# Or use cargo-watch for auto-reload
cargo watch -x 'run'
4. Verify Server Operation
After successful startup, test if the server is running properly:
# Check server version information
curl http://yourservername:6006/_matrix/client/versions
# Expected JSON-formatted version information, similar to:
{
"versions": ["r0.5.0", "r0.6.0", "v1.1", "v1.2", "v1.3", "v1.4", "v1.5", "v1.6"],
"unstable_features": {}
}
If you receive the above JSON response, the Palpo server is running successfully.
Learn more about the Matrix API:
Database Schema Overview
Palpo uses the following main data tables:
- User-related:
users, user_passwords, user_sessions, user_profiles, user_access_tokens
- Room-related:
rooms, room_aliases, room_tags
- Event-related:
events, event_datas, event_points, threads
- Media-related:
media_metadatas, media_thumbnails, media_url_previews
- End-to-end Encryption:
e2e_device_keys, e2e_room_keys, e2e_room_keys_versions
- Statistics-related:
stats_user_daily_visits, stats_monthly_active_users, stats_room_currents
- Others:
threepid_*, user_pushers, server_signing_keys
View detailed table structures in the crates/data/migrations/ directory.
Troubleshooting
- Migration Failure:
# Check database connection
psql $DATABASE_URL -c "SELECT version();"
# Check migration status
diesel migration list
# Reset database (use with caution)
dropdb palpo_dev && createdb palpo_dev
diesel migration run
- Permission Issues:
-- Ensure user has sufficient permissions
GRANT ALL PRIVILEGES ON DATABASE palpo TO palpo;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO palpo;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO palpo;
- Connection Issues:
# Test database connection
pg_isready -h localhost -p 5432 -U palpo
# Check PostgreSQL status
sudo systemctl status postgresql # Linux
brew services list | grep postgres # macOS
Additional troubleshooting resources:
Common Issues
- Compilation Errors: Ensure all required system dependencies are installed
- Diesel CLI Installation Failure: Ensure
libpq-dev (Linux) or PostgreSQL development libraries are installed
- Port Conflicts: Modify
listen_addr to use a different port
- Permission Issues: Ensure Palpo has permission to access configuration files and media directories
Log Debugging
# Enable verbose logging
RUST_LOG=debug ./target/release/palpo
# Database query logging
RUST_LOG=diesel=debug ./target/release/palpo
Learn more about debugging:
