Skip to content

Deployment & Operations

This page is the operational companion to Getting Started. It focuses on running the interface safely and predictably.

Start Modes

Run the interface from src/TerraFin/interface/.

python server.py run
python server.py start
python server.py stop
python server.py status
python server.py restart
Command Use when...
run You want a foreground dev server
start You want a simple background process on one machine
stop You need to stop the background process if it exists
status You are checking whether the PID-managed process is alive
restart You changed env vars or saved model credentials

Health And Readiness

These endpoints stay at the root even when TERRAFIN_BASE_PATH is set:

Path Purpose
/health Multi-component status page (HTML). Active probes for Agent / Telegram / Signals Provider with 30 s in-process cache and 2 s per-probe timeout. Append ?refresh=1 to bypass the cache.
/health.json Same data as JSON for scripts and uptime checks
/ready Readiness check with cache-manager and private-data validation

Use /ready for orchestration startup gating; use /health.json for periodic uptime probes (scrape interval should be ≥ the 30 s cache TTL to avoid wasted upstream calls). The HTML /health is meant for humans opening the page in a browser.

Base Paths

TERRAFIN_BASE_PATH prefixes the feature routes, but not the health endpoints.

Example:

  • TERRAFIN_BASE_PATH=/terrafin
  • page routes become /terrafin/chart, /terrafin/dashboard, and so on
  • /health and /ready remain unchanged

Public / Demo Mode

TerraFin can run without private infrastructure.

Recommended public-safe baseline:

  1. copy .env.example to .env
  2. leave TERRAFIN_PRIVATE_SOURCE_* unset
  3. optionally configure FRED_API_KEY
  4. set TERRAFIN_SEC_USER_AGENT if you want SEC-backed features

In this mode:

  • public market and economic providers still work
  • private-only widgets fall back to bundled fixtures or empty defaults
  • writable watchlists stay disabled unless MongoDB is configured

Operator-Managed Mode

Use operator-managed mode when you want:

  • private market-insight or dashboard data
  • writable watchlists
  • explicit hosted model/provider control
  • a deployment-specific auth and persistence boundary

At minimum, define:

  • TERRAFIN_PRIVATE_SOURCE_* for the private endpoint
  • TERRAFIN_MONGODB_URI if you want watchlist writes
  • provider credentials or terrafin-agent models ... state for hosted agent use

Hosted Agent Operational Notes

  • Restart the server after changing saved model-manager state.
  • Sessions pin a resolved provider/model on creation, so new env changes do not silently rewrite existing sessions.
  • GitHub Copilot login stores the GitHub token locally, then exchanges it for a short-lived Copilot API token at runtime.

Formal Docs Hosting

This repo now includes a formal docs site scaffold using MkDocs Material and a GitHub Pages workflow:

  • site config: mkdocs.yml
  • local preview: mkdocs serve
  • CI build/deploy: .github/workflows/docs-pages.yml

That keeps the docs static-hostable on GitHub without depending on a separate publish repo or docs SaaS.

GitHub Pages Source

The workflow deploys through GitHub Actions, not by publishing the repository root or docs/ folder directly.

If https://kiungsong.github.io/TerraFin/ is still showing the repository README instead of the MkDocs site, the repository is almost certainly still set to branch-based Pages publishing.

For this workflow to take over, switch the repository once in:

  1. Settings
  2. Pages
  3. Build and deployment
  4. Source = GitHub Actions

If that switch is not made, actions/deploy-pages may fail with a 404, and the old branch-based README site will continue to be served.