Skip to content

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

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

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

Conversation

@TigerInYourDream
Copy link
Copy Markdown

@TigerInYourDream TigerInYourDream commented Apr 2, 2026

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.sh → docker 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

@TigerInYourDream
docs: add deployment guide for Robrix + Palpo + Octos
b05340a 
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
@TigerInYourDream
docs: restructure deployment guides into categorized documentation
c6e7641 
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
@TigerInYourDream
docs: add Octos bot commands, BotFather vs child bots, public/private…
bee2a80 
… 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).
@TigerInYourDream
docs: add screenshots, bot naming rules, extract palpo.Dockerfile
c1ae1ad 
- 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
@TigerInYourDream
Merge remote-tracking branch 'origin/main' into docs/deployment-guide
afc47ee
@TigerInYourDream
docs: add search/invite bot screenshot and fix image sizing
6fd25e5 
- 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
ZhangHanDong added a commit that referenced this pull request Apr 5, 2026
@ZhangHanDong @claude
Add Makepad 2.0 skills reference table to CLAUDE.md
97faa8c 
Maps common situations to the correct skill to invoke,
plus highlights project-specific pitfalls #40-#44.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@TigerInYourDream
Merge branch 'main' into docs/deployment-guide
28cfedc
@TigerInYourDream
docs: add OpenClaw + Matrix integration guide (zh/en)
967343b 
Add complete documentation for using Robrix with OpenClaw AI agents:
- 01: Deployment guide with tested config, Palpo vs matrix.org differences
- 02: Usage guide with screenshot placeholders for DM and room workflows
- 03: Architecture guide comparing client mode vs Octos AppService mode
- Update README.md with OpenClaw section

Based on hands-on testing with OpenClaw v2026.4.7 + local Palpo.
@TigerInYourDream
docs: reorder guides to deploy → usage → architecture
82cd640 
Swap doc ordering for both Palpo+Octos and OpenClaw series:
- 02: Usage guide (was 03) — let users get started first
- 03: Architecture/principles (was 02) — deeper reading for those interested

Update all cross-references across 11 files and README.
@TigerInYourDream
docs: add Palpo-to-matrix.org migration notes and OpenClaw disclaimer
c79e941 
- Add clear 3-step migration guide from local Palpo to matrix.org
- Strengthen OpenClaw disclaimer with links to official docs and issues
- Clarify Robrix is fully decoupled from OpenClaw via Matrix protocol
@TigerInYourDream
docs: add search screenshot, People tab hint, gateway.mode explanation
5bb99e3 
- Add openclaw-search-bot.png screenshot to usage guide
- Clarify users must search under People tab (bot is a regular user)
- Explain gateway.mode=local means gateway binds locally, not LLM location
@TigerInYourDream
docs: add bot reply and room join screenshots
21dd6dc 
- openclaw-bot-reply.png: conversation with OpenClaw bot (used in deploy + usage guides)
- openclaw-bot-join-room.png: bot accepting room invitation
- Replace all remaining screenshot placeholders
@TigerInYourDream
docs: mention Access Token auth as alternative to password
c837b1b
@TigerInYourDream
docs: remove Palpo cross-signing bug references
6f1a5eb
@TigerInYourDream
docs: add brief OpenClaw introduction to deployment guides
8c86e1e
@TigerInYourDream
docs: polish OpenClaw guides — remove unsupported items, add wait tips
2217267 
- Remove partially supported / unsupported feature entries from comparison
  tables (tracked in #67 for future enhancement)
- Add startup wait tip: OpenClaw needs time to complete Matrix login
- Add LLM response wait tip: replies may take a few seconds
- Minor formatting fixes from linter
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@TigerInYourDream @ZhangHanDong