Server Setup - Pharos Documentation

:::tip[One-Liner Installation] Prefer a frictionless automated setup? Use our Automated Installation Guide to deploy the Pharos Server in under 60 seconds. :::

The pharos-server is an Invisible High-Performance Engine optimized for Linux (Ubuntu LTS). It acts as the central RFC 2378 backplane for the entire ecosystem, providing the lightning-fast data layer for your Agent-Native Control Plane.

🚀 3-Minute Quick Start: The “YOLO” Lab

Reach a success state in under 180 seconds. No installation required if you have Podman/Docker.

# Start the Pharos Server in the background
podman run -d --name pharos-demo -p 2378:2378 -p 9090:9090 ghcr.io/iamrichardd/pharos:latest

🛡️ Production Deployment

For production use, we recommend a native installation in a Proxmox LXC container or a dedicated Ubuntu VM.

🏠 Home Lab: Persistent JSON Storage

Perfect for Proxmox LXC containers. Pharos uses a simple, restart-survivable JSON file for your data.

1. Prepare the LXC Container

Ubuntu 24.04 with 512MB RAM and 2GB Disk is recommended.

2. Install the Pharos Server

wget https://github.com/iamrichardd/pharos/releases/download/v1.0.0/pharos-server-linux-x86_64
chmod +x pharos-server-linux-x86_64
mv pharos-server-linux-x86_64 /usr/local/bin/pharos-server

3. Configure as a Systemd Service

cat <<EOF > /etc/systemd/system/pharos.service
[Unit]
Description=Pharos Infrastructure Server
After=network.target

[Service]
ExecStart=/usr/local/bin/pharos-server
Environment=PHAROS_STORAGE_PATH=/var/lib/pharos/data.json
Environment=PHAROS_SECURITY_MODE=open
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now pharos

🏢 Enterprise: LDAP Integration (Read-Only)

Pharos integrates seamlessly with your Enterprise infrastructure by acting as a high-speed, Read-Only proxy for your central LDAP directory. This ensures high-performance discovery without requiring administrative write-access to your corporate source of truth.

1. Configure LDAP details:

export PHAROS_LDAP_URL="ldap://ldap.enterprise.com:389"
export PHAROS_LDAP_BIND_DN="cn=pharos,ou=services,dc=enterprise,dc=com"
export PHAROS_LDAP_BIND_PW="secret"
export PHAROS_LDAP_BASE_DN="dc=enterprise,dc=com"
export PHAROS_SECURITY_MODE="scoped"
./pharos-server

2. Field Mapping:

Pharos maps fields to standard object classes automatically:

People: inetOrgPerson (maps name -> cn, email -> mail)
Machines: ipHost (maps hostname -> cn, ip -> ipHostNumber)

🔐 Security Configuration

Pharos implements a tiered security model to balance accessibility and safety.

Mode	Description	Write Security
`open`	For local-only Home Labs.	Anyone can add/edit.
`protected`	Default for remote access.	Requires authorized SSH key.
`scoped`	For multi-tenant Enterprise teams.	Requires SSH key + LDAP group matching.

Enrolling SSH Keys

To authorize a user for write access, place their public key in the keys directory:

mkdir -p /etc/pharos/keys
cp ~/.ssh/id_ed25519.pub /etc/pharos/keys/admin.pub
export PHAROS_KEYS_DIR="/etc/pharos/keys"

📊 Monitoring & Observability

Pharos exposes Prometheus metrics on port 9090 to track performance and inventory health.

Endpoint: http://localhost:9090/metrics
Key Metrics:
- pharos_cpu_usage_percentage
- pharos_memory_usage_bytes
- pharos_total_records