Skip to content

docs: add deployment guide for Robrix + Palpo + Octos#40

Open
TigerInYourDream wants to merge 6 commits intomainfrom
docs/deployment-guide
Open

docs: add deployment guide for Robrix + Palpo + Octos#40
TigerInYourDream wants to merge 6 commits intomainfrom
docs/deployment-guide

Conversation

@TigerInYourDream
Copy link
Copy Markdown

Summary

Add a one-stop deployment guide that walks users through setting up the complete Robrix + Palpo + Octos AI chat system.

  • Bilingual: English (docs/deployment-guide.md) + Chinese (docs/deployment-guide-zh.md)
  • Self-contained: all configs inline with field-level explanations, no need to jump to external docs
  • Ready-to-run: example configs in docs/examples/ — user only needs to set one API key
  • Tested end-to-end: Quick Start verified on macOS (ARM64) with Docker, Robrix registration → bot chat works

What's included

File Purpose
docs/deployment-guide.md English deployment guide (7 sections)
docs/deployment-guide-zh.md Chinese deployment guide
docs/examples/compose.yml Docker Compose (Palpo + PostgreSQL + Octos, built from source)
docs/examples/palpo.toml Palpo homeserver config
docs/examples/appservices/octos-registration.yaml Appservice registration
docs/examples/config/botfather.json Octos bot profile
docs/examples/config/octos.json Octos global config
docs/examples/setup.sh One-time setup script (clones repos, creates .env)
docs/examples/.env.example Environment variables template
docs/images/register-account.png Registration screenshot
README.md Added TIP box linking to the deployment guide

Key design decisions

  • Build from source in Docker (not pre-built images) — supports all architectures (x86_64, ARM64/Apple Silicon)
  • server_name = "127.0.0.1:8128" — works with matrix-rust-sdk's server_name_or_homeserver_url() discovery
  • created_at/updated_at in botfather.json — required by Octos profile loader (missing = bot silently skipped)
  • No federation content — that's Palpo's advanced topic, kept out of scope

Test plan

  • Clean environment: rm -rf data/./setup.shdocker compose up -d → all 3 services healthy
  • Robrix registration against http://127.0.0.1:8128 succeeds
  • Bot responds to messages (curl verified: register → create room → invite bot → send message → receive AI reply)
  • Verify docs render correctly on GitHub (images, tables, code blocks)
  • Verify Chinese version renders correctly

Add a comprehensive, self-contained deployment guide (English + Chinese)
with ready-to-run Docker Compose example configs. Users can go from zero
to a working Robrix → Palpo → Octos → LLM setup in 5 steps.

Includes:
- Step-by-step quick start with setup.sh for repo cloning
- Full configuration reference (palpo.toml, appservice registration,
  botfather.json, compose.yml) with field-level explanations
- Robrix client usage guide (registration, bot interaction, bot management)
- End-to-end verification checklist and troubleshooting tables
- Example configs that work out of the box (only API key needed)
- Registration screenshot
- README link to the deployment guide
Restructure the monolithic deployment guide into a clear documentation
hierarchy with two categories and descriptive filenames:

- robrix/ — standalone Robrix getting-started guide
- robrix-with-palpo-and-octos/ — integrated system docs:
  01-deploying-palpo-and-octos (deployment)
  02-how-robrix-palpo-octos-work-together (architecture/App Service)
  03-using-robrix-with-palpo-and-octos (usage with screenshots)
  04-federation-with-palpo (federation deployment and usage)

Move deployment configs from docs/examples/ to palpo-and-octos-deploy/
at the project root, separating runnable files from documentation.

Each document now has a clear goal statement at the top. Bilingual
(EN/ZH) versions maintained for all files.
@ZhangHanDong ZhangHanDong added documentation Improvements or additions to documentation Feature-Octos Priority-High labels Apr 3, 2026
… visibility

Add Section 7 to usage guides (EN/ZH) covering:
- BotFather slash commands (/createbot, /deletebot, /listbots, /bothelp)
- BotFather vs child bot comparison table
- Public/private bot visibility model with examples
- Owner-based delete permissions and operator override

Based on octos-org/octos#69 (owner & visibility model).
- Add login screen and registration screenshots (compressed via pngquant)
- Add bot naming explanation in usage guide Section 5.2
- Extract Palpo Dockerfile from compose.yml inline to standalone file
- Update compose.yml to reference palpo.Dockerfile
- Add compressed search-invite-bot.png showing the search → People workflow
- Update Section 5.2 (EN/ZH) with step-by-step bot search instructions
- Fix image tags to use <img width="600"> for consistent display
- Add "Download pre-built release" section to Chinese getting-started
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation Feature-Octos Priority-High

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants