Skip to content
PingclairPingclair

Install

Pingclair targets Linux. Release binaries are published for x86_64 and aarch64. macOS builds from source are supported for development; macOS is not a shipping platform.

📌 Release status

Section titled “📌 Release status”

The default installation target is v0.2.0-rc.3, a release candidate. The install script prints the tag it is installing and verifies the published SHA-256 checksum before unpacking.

The v0.1.x line is unmaintained: it receives no fixes, no backports, and no security advisories. One reason to move is that v0.1.x parsed the Admin API api_key field and never read it, so the field protected nothing.

📦 Install from a release binary

Section titled “📦 Install from a release binary”
Terminal window
curl -fsSL https://raw.githubusercontent.com/dorianverlaine/pingclair/main/scripts/install.sh | sudo bash

The script downloads the release binary for the current architecture, verifies its checksum, installs pingclair together with the pc alias, creates an unprivileged pingclair user, grants that user the capabilities needed to bind low ports, and installs a systemd unit.

To build and install the main branch instead of the latest release:

Terminal window
curl -fsSL https://raw.githubusercontent.com/dorianverlaine/pingclair/main/scripts/install.sh | sudo bash -s -- --main

--main compiles the server locally. It requires Rust 1.98 or newer and the C toolchain that BoringSSL and jemalloc need: cmake, clang, libclang-dev, g++, and git.

Verify either installation:

Terminal window
pingclair version
pc version

🐳 Docker

Section titled “🐳 Docker”

The image already runs config-file mode: its entrypoint is pingclair and its default command is run /etc/pingclair/Pingclairfile. A Compose service therefore only has to mount the configuration and the data store.

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3
    volumes:
      - ./conf:/etc/pingclair:ro
      - ./site:/srv
      - pingclair_tls:/var/lib/pingclair/certs


volumes:
  pingclair_tls:

Place the Pingclairfile in ./conf/ and static files under ./site/, which the configuration reaches with an absolute container path such as root /srv. HTTPS, the port 80 redirect, and HTTP/3 behave the same as in a host deployment.

Two points are easy to get wrong:

  • 🔒 The TLS volume is state, not cache. It holds issued certificates, ACME account keys, and the internal certificate authority. Removing it means reissuing certificates, and trusting clients have to trust the new internal root.
  • ⚠️ Do not add command:. The image default is already run /etc/pingclair/Pingclairfile; overriding it replaces that command.

For production, pin a released tag instead of latest. Published tags are listed on the package page.

🛠️ Build from source

Section titled “🛠️ Build from source”
Terminal window
git clone https://github.com/dorianverlaine/pingclair
cd pingclair
cargo build --release

Requirements: Rust 1.98.1 (the version CI pins), cmake, clang, libclang-dev, g++, and git. BoringSSL is compiled from source as part of the build, so the first build takes several minutes.

🧭 Next steps

Section titled “🧭 Next steps”