Deploying Pharos

Pharos is the server process. It runs the realm, holds the keypair, speaks SSH to travelers, and speaks porthmos to neighboring islands. This document walks from bare machine to live beacon.

Prerequisites

A Linux host with a public address and port 22 (or a port of your choosing) reachable from outside. 2 GB RAM and 20 GB disk will run a small island without strain.

A domain name you control. Travelers connect by hostname — ssh [email protected] — so DNS must resolve before you open to visitors.

Install

Download the latest pharos binary from the releases page, or build from source:

cargo install pharos

Verify:

$ pharos --version
pharos 0.9.0

Initialise

pharos init winding-stair

This creates winding-stair/ with the following layout:

Path	Contents
`realm.toml`	Configuration
`keys/realm.key`	Ed25519 private key
`keys/realm.pub`	Ed25519 public key
`store/`	Event store (empty)

The keypair is your realm’s cryptographic identity — every event, every item provenance record, every federation handshake carries its signature. Back up keys/ before you do anything else. A lost private key means a lost identity: federation partners will reject the replacement and trust relationships must be rebuilt from scratch.

Configure

Open realm.toml. The minimum configuration that will run:

[realm]
name        = "winding-stair"
hostname    = "winding-stair.example.com"
operator    = "did:archi:you"
mood        = "calm"

[realm.ssh]
port        = 22
host_key    = "keys/realm.key"

[realm.harbormaster]
name  = "The Harbormaster"
brief = "A figure by the gate, watching the water."
lines = [
  "Welcome. Mind the tide.",
]

hostname must match the DNS entry your travelers will use. operator is your DID — run pharos identity after first boot to see the value generated for you.

For the full set of configuration fields, see the realm.toml reference.

Run

pharos serve --realm winding-stair/

pharos 0.9.0 · realm: winding-stair
keypair: ed25519:3b4a…
SSH listening on 0.0.0.0:22
event store: winding-stair/store/ (0 events)
beacon: ● live

From another machine:

ssh [email protected]

If the harbormaster answers, the beacon is up.

Firewall

Open inbound TCP on your SSH port. Nothing else is required for a standalone island.

For federation, porthmos uses port 3456 by default. Open that port only to known peer addresses — there is no reason to expose it broadly:

[realm.federation]
port = 3456

Run as a service

Create /etc/systemd/system/pharos-winding-stair.service:

[Unit]
Description=pharos realm: winding-stair
After=network.target

[Service]
Type=simple
User=pharos
WorkingDirectory=/opt/pharos
ExecStart=/usr/local/bin/pharos serve --realm /opt/pharos/winding-stair/
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl enable pharos-winding-stair
systemctl start pharos-winding-stair

Configuration changes take effect on reload — the beacon stays lit:

systemctl reload pharos-winding-stair

Backup

Back up keys/ and store/. The keys are your identity. The store is your history — every event, every utterance, every item that has ever existed on the island. Everything else can be reconstructed from it.

0 4 * * * tar czf /backup/winding-stair-$(date +\%Y\%m\%d).tar.gz \
  /opt/pharos/winding-stair/keys/ \
  /opt/pharos/winding-stair/store/

Three days of backups, kept offsite. A year of active play on a small island is typically under a gigabyte.