---
title: Deployment & Operations
summary: Running TerraFin in local, demo, and operator-managed environments.
---

# Deployment & Operations

This page is the operational companion to [Getting Started](getting-started.md).
It focuses on running the interface safely and predictably.

## Start Modes

Run the interface from `src/TerraFin/interface/`.

```bash
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.

## Related Docs

- [Configuration](configuration.md)
- [Interface Overview](interface.md)
- [Agent Model Management](agent/models.md)
- [License & Data Rights](legal.md)