feat: cloud deployment support with inline config, Dockerfile, and admin portal (#434)

2026-02-27 15:24:17 -08:00
parent 9421027234
commit 481b458af1
16 changed files with 682 additions and 56 deletions
--- a/docs/cloud-deploy.md
+++ b/docs/cloud-deploy.md
@@ -0,0 +1,155 @@
+# Cloud Deployment
+
+Deploy LettaBot to any cloud platform that supports Docker or Node.js.
+
+## Prerequisites
+
+- A [Letta API key](https://app.letta.com) (or a self-hosted Letta server -- see [Docker Server Setup](./selfhosted-setup.md))
+- At least one channel token (Telegram, Discord, or Slack)
+- A working `lettabot.yaml` config (run `lettabot onboard` to create one)
+
+## Configuration
+
+Cloud platforms typically don't support config files directly. LettaBot solves this with `LETTABOT_CONFIG_YAML` -- a single environment variable containing your entire config.
+
+### Encoding Your Config
+
+```bash
+# Using the CLI helper (recommended)
+lettabot config encode
+
+# Or manually
+base64 < lettabot.yaml | tr -d '\n'
+```
+
+Set the output as `LETTABOT_CONFIG_YAML` on your platform. This is the only env var you need -- everything (API key, channels, features) is in the YAML.
+
+Both base64-encoded and raw YAML values are accepted. Base64 is recommended since some platforms don't handle multi-line env vars well.
+
+### Verifying
+
+To decode and inspect what a `LETTABOT_CONFIG_YAML` value contains:
+
+```bash
+LETTABOT_CONFIG_YAML=... lettabot config decode
+```
+
+## Docker
+
+LettaBot includes a Dockerfile for containerized deployment.
+
+### Build and Run
+
+```bash
+docker build -t lettabot .
+
+docker run -d \
+  -e LETTABOT_CONFIG_YAML="$(base64 < lettabot.yaml | tr -d '\n')" \
+  -p 8080:8080 \
+  lettabot
+```
+
+### Docker Compose
+
+```yaml
+services:
+  lettabot:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      - LETTABOT_CONFIG_YAML=${LETTABOT_CONFIG_YAML}
+    restart: unless-stopped
+```
+
+If running alongside a self-hosted Letta server, see [Docker Server Setup](./selfhosted-setup.md) for the Letta container config.
+
+## Fly.io
+
+```bash
+# Install CLI
+brew install flyctl
+fly auth login
+
+# Launch (detects Dockerfile automatically)
+fly launch
+
+# Set your config
+fly secrets set LETTABOT_CONFIG_YAML="$(base64 < lettabot.yaml | tr -d '\n')"
+
+# Set a stable API key (optional, prevents regeneration across deploys)
+fly secrets set LETTABOT_API_KEY=$(openssl rand -hex 32)
+
+# Deploy
+fly deploy
+```
+
+`fly launch` generates a `fly.toml` with your app name. Edit it to keep the bot running (Fly defaults to stopping idle machines):
+
+```toml
+[http_service]
+  auto_stop_machines = false
+  min_machines_running = 1
+```
+
+Scale to 1 machine (multiple instances would conflict on channel tokens):
+
+```bash
+fly scale count 1
+```
+
+## Railway
+
+See [Railway Deployment](./railway-deploy.md) for the full guide including one-click deploy, persistent volumes, and Railway-specific configuration.
+
+The short version:
+
+1. Fork the repo and connect to Railway
+2. Set `LETTABOT_CONFIG_YAML` (or individual env vars for simple setups)
+3. Deploy
+
+## Other Platforms
+
+Any platform that runs Docker images or Node.js works. Set `LETTABOT_CONFIG_YAML` as an env var and you're done.
+
+**Render:** Deploy from GitHub, set env var in dashboard.
+
+**DigitalOcean App Platform:** Use the Dockerfile, set env var in app settings.
+
+**Any VPS (EC2, Linode, Hetzner):** Build the Docker image and run it, or install Node.js and run `npm start` directly.
+
+## Web Portal
+
+LettaBot includes an admin portal at `/portal` for managing pairing approvals from a browser. Navigate to `https://your-host/portal` and enter your API key to:
+
+- View pending pairing requests across all channels
+- Approve users with one click
+- Auto-refreshes every 10 seconds
+
+## API Key
+
+An API key is auto-generated on first boot and printed in logs. It's required for the web portal and HTTP API endpoints.
+
+To make it stable across deploys, set `LETTABOT_API_KEY` as an environment variable:
+
+```bash
+# Fly.io
+fly secrets set LETTABOT_API_KEY=$(openssl rand -hex 32)
+
+# Railway / Render / etc.
+# Set LETTABOT_API_KEY in the platform's env var UI
+```
+
+## Health Check
+
+LettaBot exposes `GET /health` which returns `ok`. Configure your platform's health check to use this endpoint.
+
+## Channel Limitations
+
+| Channel | Cloud Support | Notes |
+|---------|--------------|-------|
+| Telegram | Yes | Full support |
+| Discord | Yes | Full support |
+| Slack | Yes | Full support |
+| WhatsApp | No | Requires local QR code pairing |
+| Signal | No | Requires local device registration |