Skip to content

OpenFin Service Deployment

Prerequisites

  • Python 3.12+
  • uv package manager
  • systemd (Linux)
  • A Telegram bot token (create via @BotFather)

Installation

# Create service user
sudo useradd -r -m -d /opt/openfin -s /bin/bash openfin

# Clone and install
sudo -u openfin git clone <repo-url> /opt/openfin
cd /opt/openfin
sudo -u openfin uv sync

# Create artifacts directory
sudo -u openfin mkdir -p /opt/openfin/artifacts

Environment Setup

Bootstrap the data directory and enter credentials interactively:

sudo -u openfin OPENFIN_HOME=/opt/openfin/.openfin uv run openfin init

This creates /opt/openfin/.openfin/ with: - credentials.toml — API keys (file mode 0600) - theses/ — investment thesis YAML files (seeded from repo examples) - scoring/ — rubric definitions

To edit credentials later:

sudo -u openfin vi /opt/openfin/.openfin/credentials.toml
TOML key Required Description
[snaptrade] client_id Yes SnapTrade API client ID
[snaptrade] consumer_key Yes SnapTrade API consumer key
[snaptrade] user_id Yes SnapTrade user ID
[snaptrade] user_secret Yes SnapTrade user secret
[finnhub] api_key Yes Finnhub market data API key
[sec] user_agent Yes User-agent string for SEC EDGAR requests
[fred] api_key Yes FRED economic data API key
[telegram] bot_token Yes Telegram bot token from @BotFather
[brave] api_key No Brave Search API key

The systemd units set OPENFIN_HOME=/opt/openfin/.openfin. Credentials are loaded from credentials.toml at process startup — no EnvironmentFile needed.

Getting Your Telegram Chat ID

  1. Send any message to your bot in Telegram.
  2. Run:
curl -s "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | python3 -m json.tool
  1. Find "chat": {"id": <number>} in the response. That number is your TELEGRAM_CHAT_ID.

Install and Start the Service

# Install the unit file
sudo cp /opt/openfin/deploy/openfin-service.service /etc/systemd/system/
sudo systemctl daemon-reload

# Enable and start
sudo systemctl enable openfin-service
sudo systemctl start openfin-service

# Check status
sudo systemctl status openfin-service

Viewing Logs

# Follow live logs
journalctl -u openfin-service -f

# Last 100 lines
journalctl -u openfin-service -n 100

# Logs since last boot
journalctl -u openfin-service -b

Testing

Once the service is running, send these commands to your bot in Telegram:

Command Description
/status Check service health and connected accounts
/review Trigger an on-demand weekly review
/help List all available commands

Troubleshooting

Service fails to start

journalctl -u openfin-service -n 50 --no-pager

Check for missing environment variables or invalid API keys.

Permission denied errors

The unit file uses ProtectSystem=strict with only /opt/openfin/artifacts writable. If the service needs to write elsewhere, add the path to ReadWritePaths= in the unit file.

Bot not responding

  • Verify [telegram] bot_token is correct in credentials.toml.
  • Confirm the bot has not been stopped in @BotFather.
  • Check that the server has outbound HTTPS access to api.telegram.org.

Scheduled review not firing

  • Confirm the system timezone or verify the schedule timezone in the ExecStart line (America/Chicago).
  • Check logs around the expected trigger time for errors.

Updating the service

cd /opt/openfin
sudo -u openfin git pull
sudo -u openfin uv sync
sudo -u openfin OPENFIN_HOME=/opt/openfin/.openfin uv run openfin init --no-input
sudo systemctl restart openfin-service