How axis-oz/nanobot-railway-template works
This repo is a Railway deploy template that packages:
• a Python web admin panel (Starlette + uvicorn) providing a config UI + status dashboard + gateway control
• a managed nanobot “gateway” process that runs as an async subprocess inside the same container
• persistent storage via a Railway volume mounted at /data for config/data durability across restarts
So the architecture is essentially one container = one web server + one child gateway process, with external integrations to LLM providers and messaging channels.
What the file tree tells you to include (key components)
From the tree:
• templates/index.html → single web UI served by the Python server (browser-based admin).
• Dockerfile, start.sh, requirements.txt → packaging/runtime and entrypoint (deployment node).
• railway.toml → Railway-specific deployment configuration (service wiring, healthcheck expectations, etc.).
This is *not* a multi-service microservice architecture; it’s a single-service runtime with multiple internal modules and multiple external dependencies.
Python Web Server (Starlette + uvicorn)
• Serves / (UI), /health (unauth), and **/api/*** (auth).
• Implements Basic Auth for admin routes.
• Reads/writes config to persistent storage (/data).
• Manages the gateway lifecycle (start/stop/restart).
• Captures gateway stdout/stderr into a ring buffer for log viewing.
nanobot gateway (child process / async subprocess)
• Started/stopped by the web server.
• Uses configured providers/channels to operate.
• Emits logs to stdout/stderr (captured by the web server).
• Reads config/data (likely from /data and/or env vars).
Persistent Volume mounted at /data
• Stores config/data
• Used by the web server (and likely the gateway)
External actors and systems
• Admin user (Browser)
• Connects to GET / (UI) and GET/PUT /api/* endpoints
• Protected by Basic Auth (username/password via env)
• Railway routing / public URL
• Routes HTTP traffic to the container on $PORT
• Optionally: show “public endpoint removed after setup” as an operational note (not a runtime dependency)
• LLM Provider APIs (Anthropic/OpenAI/OpenRouter/DeepSeek/Groq/Gemini/Zhipu/vLLM)
• Outbound calls from the gateway (and/or nanobot core)
• Messaging Channels
• Telegram
• WhatsApp (via bridge)
• Feishu/Lark
Browser ↔ Web Server
• HTTPS/HTTP to:
• / (HTML UI from templates/index.html)
• /api/config (GET masked, PUT save)
• /api/status (gateway/provider/channel status)
• /api/logs (ring buffer lines)
• /api/gateway/* (control plane)
• A small “Basic Auth” annotation on these routes.
• /health separately as no-auth for platform checks.
Web Server → Persistent Volume (/data)
• Read/write config
• Possibly store generated admin password info (at least logs it)
Web Server ↔ Gateway Subprocess
• Web server issues lifecycle commands: start/stop/restart
• Gateway emits:
Gateway ↔ External Providers/Channels
• Gateway → Provider APIs (LLM inference requests)
• Gateway ↔ Messaging platforms (send/receive messages/events)
• Single-container, multi-process pattern: web control-plane + managed worker (gateway) as child process.
• Control plane vs data plane:
• Control plane: Web UI/API + auth + config management + process control
• Data plane: Gateway operations (channels/providers)
• Persistent state via mounted volume (/data) rather than an external DB.
• Observability via log ring buffer: gateway logs are captured and served to UI.
Labels on components:
• Python + Starlette + uvicorn (Web server)
• Docker (Dockerfile)
• Railway (deployment target, volume, env vars)
• Basic Auth (ADMIN_USERNAME/ADMIN_PASSWORD)
• nanobot gateway (subprocess)
• Persistent Volume /data
• HTML template (templates/index.html)
A small “Config sources” note:
• Primary: Web UI saved config
• Secondary: env vars with NANOBOT_ prefix (as fallback/override if relevant)
What *not* to overcomplicate
• Don’t invent extra services (no separate DB, no separate queue) unless you verify in code.
• Keep “Railway” as the hosting boundary rather than drawing Kubernetes-level primitives (unless you’re specifically documenting deployment internals).
• [ ] Admin Browser → Web Server endpoints (/, /api/*, /health)
• [ ] Basic Auth boundary on admin endpoints (not on /health)
• [ ] Web Server ↔ Gateway lifecycle control (start/stop/restart)
• [ ] Gateway logs → Web Server ring buffer → UI /api/logs
• [ ] Persistent volume /data used for config/data
• [ ] Gateway ↔ External Providers and Channels
• [ ] Railway env vars (PORT, ADMIN_USERNAME, ADMIN_PASSWORD, NANOBOT_*)