Pharos Framework

← Back

Pharos Runtime Operations

This guide covers how to configure and operate the shared Pharos runtime.

Install Pharos

Install the package for your target system:

  • Debian or Ubuntu: install the matching .deb
  • RPM-based systems: install the matching .rpm

The packaged runtime expects these directories:

  • /etc/pharos for configuration
  • /srv/pharos for the runtime home
  • /srv/pharos/apps for app bundles
  • /var/log/pharos for runtime logs
  • /var/lib/pharos for packaged database files
  • /var/state/pharos for runtime scratch state exports

Shared runtime configuration

The shared runtime configuration file is usually /etc/pharos/pharos.conf.

A practical first-time configuration looks like this:

host=127.0.0.1
port=7323
db_backend=sqlite
db_path=/var/lib/pharos/pharos.sqlite3
apps_dir=/srv/pharos/apps
worker_count=8
worker_queue_capacity=256
log_path=/var/log/pharos/runtime.log
required_env=SMTP_HOST,SMTP_FROM
secret_env=PHAROS_DB_PASSWORD,SMTP_API_KEY
error_report_path=/var/log/pharos/runtime.error.jsonl
backup_dir=/var/backups/pharos

Use app-local config for per-app settings such as base_path, state_dir, state_path, log_path, and app-specific database settings.

Native worker-pool sizing

Pharos serves runtime and app traffic through a bounded native worker pool.

When you do not set explicit worker-pool values in pharos.conf, Pharos resolves them like this:

  • worker_count defaults to the detected online CPU count
  • worker_count is clamped to a minimum of 1 and a maximum of 256
  • worker_queue_capacity defaults to floor(total_physical_memory_bytes / 8 MiB)
  • worker_queue_capacity is clamped to a minimum of 32 and a maximum of 8192
  • if Pharos cannot detect physical memory, worker_queue_capacity falls back to 128

Operator guidance:

  • leave the defaults alone when you want the runtime to scale conservatively with the host
  • set worker_count explicitly when you need a fixed concurrency budget for a small container or a noisy shared machine
  • set worker_queue_capacity explicitly when you need a predictable overload envelope instead of a memory-derived default

Database behavior

Pharos stores dynamic app data in the configured database backend.

  • db_backend=sqlite uses the local SQLite file at db_path
  • PostgreSQL can be enabled per app where the app contract allows it
  • Pharos does not switch to a JSON fallback source of truth for relational apps
  • runtime scratch state files remain useful operational exports, but they are not the canonical database authority when relational storage is active

App-local config

An app-local configuration file usually lives beside the app manifest as <app>/app.conf.

Typical values:

base_path=/ucal
state_dir=/var/state/pharos
log_path=/var/log/pharos/ucal.log
db_backend=sqlite
db_path=/var/lib/pharos/ucal.sqlite3

Health probes

Pharos exposes these standard probe endpoints:

  • /health
  • /ready
  • /live

Use /ready before sending traffic so the runtime can confirm that its required backing services are reachable.

First checks after install

After installing the package and writing config:

  1. confirm /etc/pharos/pharos.conf points at the bundled app directory
  2. confirm /var/lib/pharos, /var/log/pharos, and /var/state/pharos are writable by the runtime user
  3. run pharos doctor app <app_id> --build-dir dist --text
  4. run pharos deploy check app <app_id> --build-dir dist --text
  5. start the runtime with pharos serve runtime shared --conf /etc/pharos/pharos.conf
  6. probe /ready before exposing the service

Operational commands

Check app runtime and config state:

pharos doctor app ucal --build-dir dist --text

Run deployment preflight checks:

pharos deploy check app ucal --build-dir dist --text

Check migration drift:

pharos drift check app ucal --build-dir dist --text

Create a backup bundle:

pharos backup app ucal --build-dir dist --text

Restore from a backup bundle:

pharos restore app ucal --build-dir dist --input-dir <backup_dir> --text

Logging and error reports

Pharos writes plain-text logs to the configured log_path.

Pharos writes JSONL error reports to error_report_path for runtime failures, malformed requests, upstream app failures, and framework-generated 4xx and 5xx responses.

pharos doctor and pharos deploy check report whether those paths exist and are writable.