Palephone

Install Pale Server on Linux with Docker Compose

Docker Compose is the quickest Linux path in this repository. It runs Pale Server with PostgreSQL, coturn, and NATS, then exposes the HTTP API on port 8090 and SIP on 5060/5061. Use this when you want the bundled stack managed together.

1. Install Docker and Docker Compose on a Linux host.
2. Clone the repository and enter the project directory.
3. Generate secrets, review the generated .env, then start the stack.

git clone https://github.com/loreste/palephone.git
cd palephone
./scripts/generate-secrets.sh
docker compose up -d
curl http://localhost:8090/health

Important Linux settings

• PALE_SERVER_TOKEN, PALE_ADMIN_PASSWORD, and PALE_STORAGE_KEY are required and must be at least 24 characters.
• PALE_DATABASE_URL points Pale Server at PostgreSQL. Docker Compose sets this for you.
• PALE_SIP_EXTERNAL_ADDR should be passed to Pale Server for remote SIP clients, especially when using a registrar path.
• PALE_SIP_BACKEND=pjsip requires a native PJSIP-enabled server build. The packaged server keeps the API online and disables the SIP listener if that native backend is unavailable. The udp-parser backend is a development fallback and requires PALE_ALLOW_INSECURE_SIP_UDP=1.

Install Pale Server from our Linux repositories

The production package repositories are hosted on drcpbx.com. Packages install the pale-server binary, a systemd unit, and an example environment file. They do not auto-start the service, because the server must be configured with your own secrets, database URL, TLS choices, and network settings first.

Debian and Ubuntu with apt

The APT repository is signed with the Pale repository key. This package depends on the runtime libraries Pale Server needs and recommends PostgreSQL and coturn.

curl -fsSL https://drcpbx.com/pale-repo.gpg | sudo tee /usr/share/keyrings/pale-repo.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/pale-repo.gpg] https://drcpbx.com/apt stable main" | sudo tee /etc/apt/sources.list.d/pale-server.list
sudo apt update
sudo apt install pale
# Server operators can also install:
sudo apt install pale-server

Red Hat, Rocky, AlmaLinux, CentOS Stream, and Fedora with dnf

The RPM repository is available for x86_64 systems. The RPM package declares the runtime libraries needed by the current server binary, including glibc and CA certificates, and recommends PostgreSQL and coturn. RPM package signing is not enabled yet, so verify the package checksum from the published checksum file when you deploy.

sudo curl -fsSL https://drcpbx.com/rpm/pale-server.repo -o /etc/yum.repos.d/pale-server.repo
sudo dnf makecache
sudo dnf install pale
# Server operators can also install:
sudo dnf install pale-server
curl -fsSL https://drcpbx.com/downloads/pale-client-SHA256SUMS.txt

Configure after package install

Both packages create a locked-down service user and install /etc/pale/pale-server.env.example. Copy it to the live environment file, replace every placeholder secret, then start the service.

sudo cp /etc/pale/pale-server.env.example /etc/pale/pale-server.env
sudo editor /etc/pale/pale-server.env
sudo chown root:pale /etc/pale/pale-server.env
sudo chmod 0640 /etc/pale/pale-server.env
sudo systemctl enable --now pale-server
sudo systemctl status pale-server
curl http://127.0.0.1:8080/health

Important package configuration values

• PALE_SERVER_TOKEN, PALE_ADMIN_PASSWORD, and PALE_STORAGE_KEY must be strong values with at least 24 characters.
• PALE_DATABASE_URL should point to your PostgreSQL database for production.
• PALE_HTTP_ADDR=127.0.0.1:8080 is a good default when Nginx, Caddy, or another reverse proxy terminates HTTPS.
• PALE_SIP_EXTERNAL_ADDR should be set when remote SIP clients need to reach this server.

Direct server downloads

Operators who do not want a package manager can download the release artifacts directly. The current server binaries were built on the production host from commit 8977191.

• Linux x86_64 tarball
• Pale Server Windows setup installer
• Versioned Windows setup installer
• Windows x86_64 zip, manual install
• SHA256 checksums
• Windows installer checksums

Install Pale Server on bare-metal Linux

You can run Pale Server directly on Linux without Docker. In that model, Pale Server is just a native binary managed by systemd, while PostgreSQL, coturn, TLS certificates, backups, and optional services such as NATS are installed and operated separately.

Install OS packages

sudo apt update
sudo apt install -y build-essential pkg-config python3 nasm \
  libssl-dev libasound2-dev libopus-dev uuid-dev libclang-dev clang \
  postgresql postgresql-contrib coturn curl git

Install Rust with the stable toolchain before building the server. On production hosts, pin the Rust version in your build process instead of building from an untracked shell history.

Create the database

sudo -u postgres createuser --pwprompt pale
sudo -u postgres createdb -O pale pale

Build and install the server

git clone https://github.com/loreste/palephone.git
cd palephone/src-tauri/crates/pale-server
cargo build --release --bin pale-server
sudo install -m 0755 ../../target/release/pale-server /usr/local/bin/pale-server
id -u pale >/dev/null 2>&1 || sudo useradd --system --home /var/lib/pale --create-home --shell /usr/sbin/nologin pale
sudo install -d -o root -g pale -m 0750 /etc/pale
sudo install -d -o pale -g pale -m 0750 /var/lib/pale

Create /etc/pale/pale-server.env

PALE_HTTP_ADDR=127.0.0.1:8080
PALE_SIP_ADDR=0.0.0.0:5060
PALE_DATA_DIR=/var/lib/pale
PALE_DATABASE_URL="host=localhost user=pale password=replace-with-db-password dbname=pale"
PALE_SERVER_TOKEN=replace-with-strong-token-24-plus-chars
PALE_ADMIN_PASSWORD=replace-with-strong-admin-password
PALE_STORAGE_KEY=replace-with-strong-storage-key
PALE_ADMIN_USERNAME=admin
PALE_SIP_BACKEND=pjsip
RUST_LOG=info

sudo chown root:pale /etc/pale/pale-server.env
sudo chmod 0640 /etc/pale/pale-server.env

Create a systemd service

sudo tee /etc/systemd/system/pale-server.service >/dev/null <<'EOF'
[Unit]
Description=Pale Server
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
User=pale
Group=pale
EnvironmentFile=/etc/pale/pale-server.env
ExecStart=/usr/local/bin/pale-server
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ReadWritePaths=/var/lib/pale

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now pale-server
curl http://127.0.0.1:8080/health

Install Pale Server on Windows

The recommended Windows path is the Pale Server setup installer. It installs the server binary, adds the Pale logo, creates a Windows service through WinSW, writes local config under C:\\ProgramData\\Pale Server, and keeps generated secrets on the machine.

1. Download PaleServerSetup.exe, or pin the versioned installer at PaleServerSetup-0.1.1-x64.exe.
2. Run the installer as Administrator.
3. Leave Run Pale Server configuration after install selected.
4. Choose the HTTP bind address, admin username, admin password, optional database URL, and SIP backend.
5. Use the Start Menu shortcuts to configure, start, stop, restart, or open the health check.

The manual zip and direct executable remain available for operators who already have their own service management and configuration process.

Set the required environment variables

$env:PALE_SERVER_TOKEN = "replace-with-strong-token-24-plus-chars"
$env:PALE_ADMIN_PASSWORD = "replace-with-strong-admin-password"
$env:PALE_STORAGE_KEY = "replace-with-strong-storage-key"
$env:PALE_HTTP_ADDR = "0.0.0.0:8080"
$env:PALE_DATABASE_URL = "host=localhost user=pale password=... dbname=pale"
C:\Pale\Server\pale-server.exe

Verify with curl http://localhost:8080/health. If Windows Firewall is enabled, allow the HTTP API and any SIP/TURN ports you plan to expose.

How-tos

Create an admin user

Pale Server ships with an admin account controlled by PALE_ADMIN_USERNAME and PALE_ADMIN_PASSWORD. You can also create users through the server CLI.

docker compose exec pale-server pale-server user create \
  --username sip:admin@example.com \
  --display-name "Admin" \
  --password "replace-with-a-strong-password" \
  --role admin

On a bare-metal Linux server, load the same environment file first so the CLI connects to the same data store:

set -a
. /etc/pale/pale-server.env
set +a
pale-server user create \
  --username sip:admin@example.com \
  --display-name "Admin" \
  --password "replace-with-a-strong-password" \
  --role admin

Point a client at your server

1. Install the Palephone client for macOS, Linux, Windows, or Android.
2. Open Settings, set the server URL, and sign in with the SIP URI and password for that user.
3. Admin appears only for users whose server role is admin.

Check server health

curl https://your-domain.example/health

A healthy server returns JSON with ok, service, and status fields.

TLS guidance

We recommend TLS anywhere Pale is reachable outside a trusted local machine. The server handles sign-in, bearer tokens, admin actions, files, call records, presence, and meeting data. Sending that over plain HTTP makes credentials and session traffic easier to intercept.

HTTP API

The simplest production pattern is to terminate HTTPS at a reverse proxy such as Nginx, Caddy, or Traefik, then proxy to Pale Server on localhost or a private network. Pale Server can also serve TLS directly when PALE_HTTP_TLS_CERT and PALE_HTTP_TLS_KEY are set.

PALE_HTTP_ADDR=0.0.0.0:8080
PALE_HTTP_TLS_CERT=/etc/letsencrypt/live/your-domain/fullchain.pem
PALE_HTTP_TLS_KEY=/etc/letsencrypt/live/your-domain/privkey.pem

SIP signaling

SIP TLS should be used when SIP traffic crosses networks you do not fully control. Set PALE_SIP_TLS_CERT and PALE_SIP_TLS_KEY to enable SIP TLS, and expose port 5061 only when your deployment actually uses it.

PALE_SIP_TLS=true
PALE_SIP_TLS_CERT=/etc/letsencrypt/live/your-domain/fullchain.pem
PALE_SIP_TLS_KEY=/etc/letsencrypt/live/your-domain/privkey.pem
PALE_SIP_TLS_PORT=5061

Troubleshooting

Sign-in says unauthorized

• Confirm the client is using the same server URL you tested with /health.
• Check the SIP URI format. Use sip:name@domain when the user was created that way.
• Reset the user's password from the admin UI or recreate the user with the CLI.

The Admin tab disappears

• The tab is role-based. The signed-in user must have role admin.
• Sign out and sign back in after changing a user's role so the client refreshes the stored session.

SIP clients do not register

• Pass PALE_SIP_EXTERNAL_ADDR to Pale Server with the public SIP host and port clients should use.
• Use a dedicated SIP registrar/proxy for production, or use PALE_SIP_BACKEND=udp-parser plus PALE_ALLOW_INSECURE_SIP_UDP=1 only when you intentionally accept the current fallback parser path.
• Check firewall rules for SIP and RTP/TURN traffic.

Calls connect but audio fails

• Verify TURN settings: PALE_TURN_SERVER, PALE_TURN_USERNAME, PALE_TURN_PASSWORD, and PALE_TURN_REALM.
• Make sure UDP relay ports are reachable from the client networks.
• If you terminate TLS at a proxy, confirm WebSocket/SSE and long-running HTTP requests are not being buffered or dropped.

Browsers or clients reject the server

• Check that the certificate covers the exact hostname users enter in the client.
• Confirm the full certificate chain is served, not just the leaf certificate.
• If TLS terminates at a proxy, forward the original host and protocol headers so generated URLs stay correct.

Production notes

Pale gives you the communications surface and the admin hooks, but a production deployment still needs real infrastructure around it: DNS, TLS certificates, backups, monitoring, a TURN relay, PostgreSQL, and any external providers you decide to use for AI, speech, malware scanning, storage, PSTN, or E911.

• Keep .env and generated secrets out of Git.
• Back up PostgreSQL and any file storage location before upgrades.
• Rotate PALE_SERVER_TOKEN and admin passwords when staff changes.
• Use the admin readiness reports to separate configured providers from fully tested integrations.