Host the API.
Keep control of your config.
Peerimeter Service is a small Go HTTP API for storing and exchanging network and node configuration with Peerimeter agents. Run it from source for a quick start, or deploy the multi-architecture container with Docker Compose.
Simple setup: run from source
This starts the service in the foreground on the local machine. It is useful for a small single-host installation or for trying the API.
- Install the Go version listed in the repository’s .go-version, then clone the repository.
git clone https://github.com/peerimeter/peerimeter-service.git cd peerimeter-service go build -trimpath -o peerimeter-service ./cmd/peerimeter-service
- Set a unique key, the persistent JSON file path, and the public HTTPS URL agents will use. The data directory is created when the service first saves configuration.
install -d -m 700 "$HOME/.local/share/peerimeter"
export PEERIMETER_API_KEY="$(openssl rand -hex 32)"
export PEERIMETER_DATA_FILE="$HOME/.local/share/peerimeter/config.json"
export PEERIMETER_PUBLIC_API_URL="https://service.example.com"
./peerimeter-service > service.log 2>&1 &
SERVICE_PID=$!
trap 'kill "$SERVICE_PID"' EXIT
SERVICE_READY=0
for attempt in $(seq 1 30); do
if curl --max-time 1 --fail --silent http://127.0.0.1:8080/healthz >/dev/null; then
SERVICE_READY=1
break
fi
sleep 1
done
if [ "$SERVICE_READY" -eq 1 ]; then
curl --max-time 2 --fail http://127.0.0.1:8080/healthz
curl --max-time 5 --fail -H "Authorization: Bearer $PEERIMETER_API_KEY" \
http://127.0.0.1:8080/api/v1/join-bundle
else
echo "Service did not become ready; see service.log" >&2
cat service.log
fi
Check the service
The commands above check the local source setup over loopback HTTP. Once an HTTPS reverse proxy is configured, verify its public URL with these additional checks:
curl --fail https://service.example.com/healthz curl --fail -H "Authorization: Bearer $PEERIMETER_API_KEY" \ https://service.example.com/api/v1/join-bundle
Agents can use config pull and config push to exchange network and node config files. This is explicit, one-shot transfer; the service does not automatically reconcile agent runtime state.
Docker Compose setup
The published image targets Linux amd64 and arm64 and runs as the unprivileged app user (UID/GID 1000). Select a versioned image tag from the service’s GitHub releases.
- Create a deployment directory, persistent data directory, and environment file.
mkdir -p peerimeter-service/data cd peerimeter-service sudo install -d -o 1000 -g 1000 data umask 077 cat > .env <<'EOF' SERVICE_IMAGE_TAG=replace-with-a-release-tag PEERIMETER_API_KEY=replace-with-a-unique-random-secret PEERIMETER_PUBLIC_API_URL=https://service.example.com EOF chmod 600 .env
Generate a key with openssl rand -hex 32 and replace the example value. Choose an image tag published for a service release. The ownership command assumes rootful Docker. With rootless Docker, assign the data directory to the host IDs mapped to container UID/GID 1000: add 999 to the first subordinate UID in /etc/subuid and the first subordinate GID in /etc/subgid for your user. With Docker’s userns-remap, add 1000 to the first subordinate UID and GID values configured for the remapped user.
- Save this as
compose.yamlalongside the environment file.
services:
peerimeter-service:
image: ghcr.io/peerimeter/peerimeter-service:${SERVICE_IMAGE_TAG:?Set a released SERVICE_IMAGE_TAG in .env}
restart: unless-stopped
env_file: .env
environment:
PEERIMETER_DATA_FILE: /var/lib/peerimeter/config.json
PEERIMETER_LISTEN_ADDR: 0.0.0.0
PORT: "8080"
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./data:/var/lib/peerimeter
read_only: true
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
- Pull and start the service. Configure your HTTPS reverse proxy to forward to
127.0.0.1:8080.
docker compose pull docker compose up -d docker compose logs -f peerimeter-service
./data/config.json. The file contains the network and node configurations managed by the service.What the initial service provides
Read the service README for the API contract, or visit the Peerimeter project site.
