[PR #329] docs: add installing and configuring guide for first deployment #325

New Issue

2026-06-06T22:10:14-04:00

yindo commented

2026-06-06 22:10:14 -04:00

📋 Pull Request Information

Original PR: https://github.com/vxcontrol/pentagi/pull/329
Author: @mason5052
Created: 6/3/2026
Status: 🔄 Open

Base: main ← Head: codex/issue-61-install-config-guide

📝 Commits (2)

5b957bd docs: add installing and configuring guide for first deployment
620e699 docs: address review feedback on install/config guide

📊 Changes

2 files changed (+186 additions, -0 deletions)

View changed files

📝 README.md (+5 -0)
➕ examples/guides/installation_configuration.md (+181 -0)

📄 Description

Summary

Add examples/guides/installation_configuration.md, a concise ordered walkthrough that takes a new user from installation to a configured, verified first run, and link it from the README Quick Start section. Docs only.

Problem

Issue #61 asked for a proper guide on how to start using PentAGI. A first-use guide (How to Use PentAGI After Login) already covers what to do after login. However, the maintainer kept the issue open with:

I left this issue open until the article about installing and configuring the product is published, I will add a comment here once it is published.

The README does contain detailed installer, manual-install, per-provider, and tester sections, but there is no single ordered "install -> configure -> test -> first run" article that threads them together. New users have to assemble that path themselves.

Solution

Add a standalone guide under examples/guides/ (matching the existing worker_node.md / vllm-qwen35-27b-fp8.md convention) that walks through, in order:

Choosing the interactive installer vs manual Docker Compose.
Setting the core server variables (PUBLIC_URL, CORS_ORIGINS, listen IP/port, COOKIE_SIGNING_SALT, DB passwords).
Configuring and testing an LLM provider with ctester.
Configuring and testing the embedding provider with etester.
Optionally configuring search providers.
Optionally enabling Graphiti / Langfuse / observability stacks.
Starting and verifying the stack (logs, ctester/etester/ftester, changing the default admin password).

It ends with a first-run checklist and links forward to the existing post-login usage guide. The guide links to the relevant README reference sections rather than duplicating them, and a single pointer link is added at the top of the README Quick Start section for discoverability.

User Impact

New users get one ordered article that connects installation and configuration, addressing the exact gap the maintainer flagged on issue #61.
The guide reuses and links existing reference sections, so it stays small and does not fork the documentation.
No behavior change: existing deployments are unaffected.

Test Plan

git diff --check clean.
Docs-only diff: README.md (+2 lines) and the new examples/guides/installation_configuration.md. No runtime, installer, schema, or env-var changes.
Verified all 34 environment variables named in the guide exist in .env.example and/or backend/pkg/config/config.go.
Verified the 14 README section anchors the guide links to resolve to real headings (installer, manual install, external networks, per-provider config, ctester/etester/ftester, after-login, web settings coverage).
Confirmed the three tester invocations match the README (ctester, etester test, ftester).
No unrelated files included.

Refs #61

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vxcontrol/pentagi/pull/329 **Author:** [@mason5052](https://github.com/mason5052) **Created:** 6/3/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/issue-61-install-config-guide` --- ### 📝 Commits (2) - [`5b957bd`](https://github.com/vxcontrol/pentagi/commit/5b957bde258f5ea5613728c57acdf9ffad734a4d) docs: add installing and configuring guide for first deployment - [`620e699`](https://github.com/vxcontrol/pentagi/commit/620e699e714354b1e1b297f52632607b5cb57127) docs: address review feedback on install/config guide ### 📊 Changes **2 files changed** (+186 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+5 -0) ➕ `examples/guides/installation_configuration.md` (+181 -0) </details> ### 📄 Description ## Summary Add `examples/guides/installation_configuration.md`, a concise ordered walkthrough that takes a new user from installation to a configured, verified first run, and link it from the README Quick Start section. Docs only. ## Problem Issue #61 asked for a proper guide on how to start using PentAGI. A first-use guide ([How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login)) already covers what to do *after* login. However, the maintainer kept the issue open with: > I left this issue open until the article about installing and configuring the product is published, I will add a comment here once it is published. The README does contain detailed installer, manual-install, per-provider, and tester sections, but there is no single ordered "install -> configure -> test -> first run" article that threads them together. New users have to assemble that path themselves. ## Solution Add a standalone guide under `examples/guides/` (matching the existing `worker_node.md` / `vllm-qwen35-27b-fp8.md` convention) that walks through, in order: 1. Choosing the interactive installer vs manual Docker Compose. 2. Setting the core server variables (`PUBLIC_URL`, `CORS_ORIGINS`, listen IP/port, `COOKIE_SIGNING_SALT`, DB passwords). 3. Configuring and testing an LLM provider with `ctester`. 4. Configuring and testing the embedding provider with `etester`. 5. Optionally configuring search providers. 6. Optionally enabling Graphiti / Langfuse / observability stacks. 7. Starting and verifying the stack (logs, `ctester`/`etester`/`ftester`, changing the default admin password). It ends with a first-run checklist and links forward to the existing post-login usage guide. The guide links to the relevant README reference sections rather than duplicating them, and a single pointer link is added at the top of the README Quick Start section for discoverability. ## User Impact - New users get one ordered article that connects installation and configuration, addressing the exact gap the maintainer flagged on issue #61. - The guide reuses and links existing reference sections, so it stays small and does not fork the documentation. - No behavior change: existing deployments are unaffected. ## Test Plan - [x] `git diff --check` clean. - [x] Docs-only diff: `README.md` (+2 lines) and the new `examples/guides/installation_configuration.md`. No runtime, installer, schema, or env-var changes. - [x] Verified all 34 environment variables named in the guide exist in `.env.example` and/or `backend/pkg/config/config.go`. - [x] Verified the 14 README section anchors the guide links to resolve to real headings (installer, manual install, external networks, per-provider config, ctester/etester/ftester, after-login, web settings coverage). - [x] Confirmed the three tester invocations match the README (`ctester`, `etester test`, `ftester`). - [x] No unrelated files included. Refs #61 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

yindo added the pull-request label 2026-06-06 22:10:14 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vxcontrol/pentagi#325