From c19665d822d7e70dfbda5c487e7fd7cad2459eb4 Mon Sep 17 00:00:00 2001 From: Dmitry Ng <19asdek91@gmail.com> Date: Mon, 3 Aug 2026 17:02:06 +0300 Subject: [PATCH] fix(docs): improve clarity and formatting in installation guides - Consolidated sentences in the README and installation configuration guide for better readability. - Removed unnecessary line breaks and ensured consistent formatting for installation instructions and requirements. - Enhanced links to related documentation for a smoother user experience. --- README.md | 7 +- examples/guides/installation_configuration.md | 134 +++++------------- 2 files changed, 35 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index df6aacca..32bbf3b8 100644 --- a/README.md +++ b/README.md @@ -572,10 +572,7 @@ The system uses Docker containers for isolation and easy deployment, with separa ## Quick Start -For a step-by-step walkthrough that connects installation, configuration, LLM -and embedding provider testing, and your first login, see the -[Installing and Configuring PentAGI](examples/guides/installation_configuration.md) -guide. The sections below remain the detailed reference for each step. +For a step-by-step walkthrough that connects installation, configuration, LLM and embedding provider testing, and your first login, see the [Installing and Configuring PentAGI](examples/guides/installation_configuration.md) guide. The sections below remain the detailed reference for each step. ### System Requirements @@ -657,7 +654,7 @@ The PentAGI web console already manages several settings areas after the server The following configuration areas still need to be set on the server through environment variables, compose files, or mounted config files: - **LLM credentials and connection details**: API keys, endpoints, auth modes, and provider-specific connection settings for OpenAI, Anthropic, Bedrock, Ollama, custom providers, and similar backends; config-path settings apply only where supported, such as `OLLAMA_SERVER_CONFIG_PATH` and `LLM_SERVER_CONFIG_PATH`. -- **Search provider credentials and options**: Settings such as `DUCKDUCKGO_*`, `GOOGLE_*`, `TAVILY_API_KEY`, `FIRECRAWL_API_KEY`, `FIRECRAWL_API_URL`, `TRAVERSAAL_API_KEY`, `PERPLEXITY_*`, `SEARXNG_*`, `SPLOITUS_ENABLED`, and the optional `WEB_SEARCH_INTERNAL_*` browser-analytics fallback settings. +- **Search provider credentials and options**: Settings such as `DUCKDUCKGO_*`, `GOOGLE_*`, `TAVILY_API_KEY`, `FIRECRAWL_API_*`, `TRAVERSAAL_API_KEY`, `PERPLEXITY_*`, `SEARXNG_*`, `SPLOITUS_ENABLED`, and the optional `WEB_SEARCH_INTERNAL_*` browser-analytics fallback settings. - **Third-party integrations**: Langfuse, Graphiti, and similar external services remain server-side configuration. - **MCP server management**: MCP settings pages are not currently exposed as a live web-console feature. diff --git a/examples/guides/installation_configuration.md b/examples/guides/installation_configuration.md index 314cfbea..9b36afb9 100644 --- a/examples/guides/installation_configuration.md +++ b/examples/guides/installation_configuration.md @@ -1,85 +1,49 @@ # Installing and Configuring PentAGI -This guide is the bridge between installing PentAGI and using it. It walks you -through a first deployment in order: pick an installation method, set the core -server variables, configure and test at least one LLM provider, configure the -embedding provider, optionally add search and observability, then start the -stack and verify it before your first login. +This guide is the bridge between installing PentAGI and using it. It walks you through a first deployment in order: pick an installation method, set the core server variables, configure and test at least one LLM provider, configure the embedding provider, optionally add search and observability, then start the stack and verify it before your first login. -It is intentionally concise and links to the detailed reference sections in the -main [README](https://github.com/vxcontrol/pentagi#readme) instead of repeating -them. When you finish here, continue with -[How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login). +It is intentionally concise and links to the detailed reference sections in the main [README](https://github.com/vxcontrol/pentagi#readme) instead of repeating them. When you finish here, continue with [How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login). ## Before you start -- Docker and Docker Compose (or Podman), 2+ vCPU, 4+ GB RAM, 20+ GB free disk, - and outbound internet access for pulling images and reaching LLM providers. -- At least one LLM provider you can authenticate to (OpenAI, Anthropic, Gemini, - AWS Bedrock, or a local/Ollama/OpenAI-compatible backend). PentAGI will not - run without one. -- Decide how you want to install: the interactive installer (recommended) or a - manual Docker Compose deployment. +- Docker and Docker Compose (or Podman), 2+ vCPU, 4+ GB RAM, 20+ GB free disk, and outbound internet access for pulling images and reaching LLM providers. +- At least one LLM provider you can authenticate to (OpenAI, Anthropic, Gemini, AWS Bedrock, or a local/Ollama/OpenAI-compatible backend). PentAGI will not run without one. +- Decide how you want to install: the interactive installer (recommended) or a manual Docker Compose deployment. ## Step 1 - Choose an installation method ### Option A: Interactive installer (recommended) -The installer is a terminal UI that runs system checks, writes a sane `.env`, -helps you configure LLM and search providers, hardens credentials, and starts -the stack for you. Download the build for your platform and run it, then follow -the prompts. See -[Using Installer (Recommended)](https://github.com/vxcontrol/pentagi#using-installer-recommended) -for download links and the Docker socket permission notes. +The installer is a terminal UI that runs system checks, writes a sane `.env`, helps you configure LLM and search providers, hardens credentials, and starts the stack for you. Download the build for your platform and run it, then follow the prompts. See [Using Installer (Recommended)](https://github.com/vxcontrol/pentagi#using-installer-recommended) for download links and the Docker socket permission notes. -If you use the installer, it can take you through most of Steps 2-6 below -interactively. You can still use this guide as a checklist of what to confirm. +If you use the installer, it can take you through most of Steps 2-6 below interactively. You can still use this guide as a checklist of what to confirm. ### Option B: Manual Docker Compose -Create a working directory, copy `.env.example` to `.env`, fill in your keys, -and bring up the stack. The full sequence (including the example provider config -files and the `docker compose up -d` command) is in -[Manual Installation](https://github.com/vxcontrol/pentagi#manual-installation). +Create a working directory, copy `.env.example` to `.env`, fill in your keys, and bring up the stack. The full sequence (including the example provider config files and the `docker compose up -d` command) is in [Manual Installation](https://github.com/vxcontrol/pentagi#manual-installation). ## Step 2 - Set the core server variables -Whichever method you used, confirm these in your `.env` before exposing the -instance to anything but localhost: +Whichever method you used, confirm these in your `.env` before exposing the instance to anything but localhost: -- `PUBLIC_URL` - the URL users and the browser will actually load, for example - `https://pentagi.example.com` or `https://192.168.1.100:8443`. Use the real - hostname or IP, never `0.0.0.0`. -- `CORS_ORIGINS` - every origin that will reach the UI, comma-separated. Include - both `https://localhost:8443` and your external URL if you use both. -- `PENTAGI_LISTEN_IP` / `PENTAGI_LISTEN_PORT` - keep the default `127.0.0.1` for - localhost-only, or set the IP to `0.0.0.0` to accept external connections. -- `COOKIE_SIGNING_SALT` and the database passwords - (`PENTAGI_POSTGRES_PASSWORD`, `NEO4J_PASSWORD`) - change these away from the - defaults before real use. +- `PUBLIC_URL` - the URL users and the browser will actually load, for example `https://pentagi.example.com` or `https://192.168.1.100:8443`. Use the real hostname or IP, never `0.0.0.0`. +- `CORS_ORIGINS` - every origin that will reach the UI, comma-separated. Include both `https://localhost:8443` and your external URL if you use both. +- `PENTAGI_LISTEN_IP` / `PENTAGI_LISTEN_PORT` - keep the default `127.0.0.1` for localhost-only, or set the IP to `0.0.0.0` to accept external connections. +- `COOKIE_SIGNING_SALT` and the database passwords (`PENTAGI_POSTGRES_PASSWORD`, `NEO4J_PASSWORD`) - change these away from the defaults before real use. -For external access, firewall rules, and certificate notes, see -[Accessing PentAGI from External Networks](https://github.com/vxcontrol/pentagi#accessing-pentagi-from-external-networks). +For external access, firewall rules, and certificate notes, see [Accessing PentAGI from External Networks](https://github.com/vxcontrol/pentagi#accessing-pentagi-from-external-networks). ## Step 3 - Configure and test an LLM provider -Set the credentials for at least one provider in `.env`. Each provider has its -own reference section with the exact variables and supported models: +Set the credentials for at least one provider in `.env`. Each provider has its own reference section with the exact variables and supported models: -- [OpenAI](https://github.com/vxcontrol/pentagi#openai-provider-configuration) - (`OPEN_AI_KEY`, `OPEN_AI_SERVER_URL`) -- [Anthropic](https://github.com/vxcontrol/pentagi#anthropic-provider-configuration) - (`ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL`) -- [Google AI (Gemini)](https://github.com/vxcontrol/pentagi#google-ai-gemini-provider-configuration) - (`GEMINI_API_KEY`, `GEMINI_SERVER_URL`) -- [AWS Bedrock](https://github.com/vxcontrol/pentagi#aws-bedrock-provider-configuration) - (`BEDROCK_REGION` plus one auth method) -- [Custom OpenAI-compatible / local](https://github.com/vxcontrol/pentagi#custom-llm-provider-configuration) - (`LLM_SERVER_URL`, `LLM_SERVER_KEY`, `LLM_SERVER_MODEL`) and - [Ollama](https://github.com/vxcontrol/pentagi#ollama-provider-configuration) +- [OpenAI](https://github.com/vxcontrol/pentagi#openai-provider-configuration) (`OPEN_AI_KEY`, `OPEN_AI_SERVER_URL`) +- [Anthropic](https://github.com/vxcontrol/pentagi#anthropic-provider-configuration) (`ANTHROPIC_API_KEY`, `ANTHROPIC_SERVER_URL`) +- [Google AI (Gemini)](https://github.com/vxcontrol/pentagi#google-ai-gemini-provider-configuration) (`GEMINI_API_KEY`, `GEMINI_SERVER_URL`) +- [AWS Bedrock](https://github.com/vxcontrol/pentagi#aws-bedrock-provider-configuration) (`BEDROCK_REGION` plus one auth method) +- [Custom OpenAI-compatible / local](https://github.com/vxcontrol/pentagi#custom-llm-provider-configuration) (`LLM_SERVER_URL`, `LLM_SERVER_KEY`, `LLM_SERVER_MODEL`) and [Ollama](https://github.com/vxcontrol/pentagi#ollama-provider-configuration) -Before starting a full flow, confirm the provider actually answers and supports -the agent behaviors PentAGI needs by running `ctester`: +Before starting a full flow, confirm the provider actually answers and supports the agent behaviors PentAGI needs by running `ctester`: ```bash # From a local Go environment (run inside the backend directory) @@ -89,20 +53,11 @@ go run ./cmd/ctester -verbose docker exec -it pentagi /opt/pentagi/bin/ctester -verbose ``` -Full usage, including `-type`, `-config`, and per-agent testing, is in -[Testing LLM Agents](https://github.com/vxcontrol/pentagi#testing-llm-agents). -If `ctester` reports tool-call or function-call problems with a custom, -llama.cpp, vLLM, or SGLang backend, that points at the backend's tool-call -parser rather than PentAGI itself. +Full usage, including `-type`, `-config`, and per-agent testing, is in [Testing LLM Agents](https://github.com/vxcontrol/pentagi#testing-llm-agents). If `ctester` reports tool-call or function-call problems with a custom, llama.cpp, vLLM, or SGLang backend, that points at the backend's tool-call parser rather than PentAGI itself. ## Step 4 - Configure and test the embedding provider -PentAGI uses embeddings for semantic search, knowledge storage, and memory. The -default provider is OpenAI; when `EMBEDDING_URL` and `EMBEDDING_KEY` are empty -and `EMBEDDING_PROVIDER=openai`, it falls back to your `OPEN_AI_SERVER_URL` and -`OPEN_AI_KEY`. Relevant variables: `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, -`EMBEDDING_URL`, `EMBEDDING_KEY`, `EMBEDDING_BATCH_SIZE`, -`EMBEDDING_MAX_TEXT_BYTES`, `EMBEDDING_STRIP_NEW_LINES`. +PentAGI uses embeddings for semantic search, knowledge storage, and memory. The default provider is OpenAI; when `EMBEDDING_URL` and `EMBEDDING_KEY` are empty and `EMBEDDING_PROVIDER=openai`, it falls back to your `OPEN_AI_SERVER_URL` and `OPEN_AI_KEY`. Relevant variables: `EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, `EMBEDDING_URL`, `EMBEDDING_KEY`, `EMBEDDING_BATCH_SIZE`, `EMBEDDING_MAX_TEXT_BYTES`, `EMBEDDING_STRIP_NEW_LINES`. Verify embeddings with `etester`: @@ -114,49 +69,30 @@ go run ./cmd/etester test -verbose docker exec -it pentagi /opt/pentagi/bin/etester test -verbose ``` -If you later change the embedding provider or model, flush and reindex the -knowledge base. Details and the full command set are in -[Embedding Configuration and Testing](https://github.com/vxcontrol/pentagi#embedding-configuration-and-testing). +If you later change the embedding provider or model, flush and reindex the knowledge base. Details and the full command set are in [Embedding Configuration and Testing](https://github.com/vxcontrol/pentagi#embedding-configuration-and-testing). ## Step 5 - (Optional) Configure search providers -Search providers improve research quality but are optional. PentAGI supports -DuckDuckGo (`DUCKDUCKGO_ENABLED`), Sploitus (`SPLOITUS_ENABLED`), Google -(`GOOGLE_API_KEY`, `GOOGLE_CX_KEY`), Tavily (`TAVILY_API_KEY`), Traversaal -(`TRAVERSAAL_API_KEY`), Perplexity (`PERPLEXITY_API_KEY`), and a self-hosted -Searxng instance (`SEARXNG_URL`). Set the keys for the engines you want in -`.env`; the manual installation section shows the full block of search -variables. +Search providers improve research quality but are optional. PentAGI supports DuckDuckGo (`DUCKDUCKGO_ENABLED`), Sploitus (`SPLOITUS_ENABLED`), Google (`GOOGLE_API_KEY`, `GOOGLE_CX_KEY`), Tavily (`TAVILY_API_KEY`), Firecrawl (`FIRECRAWL_API_KEY`), Traversaal (`TRAVERSAAL_API_KEY`), Perplexity (`PERPLEXITY_API_KEY`), a self-hosted Searxng instance (`SEARXNG_URL`), and an optional internal browser-analytics fallback engine (`WEB_SEARCH_INTERNAL_ENABLED`, off by default). Set the keys for the engines you want in `.env`; the manual installation section shows the full block of search variables. ## Step 6 - (Optional) Enable Graphiti, Langfuse, and observability These are separate, optional stacks brought up with additional compose files: -- Graphiti knowledge graph (`GRAPHITI_ENABLED=true`, `GRAPHITI_URL`, plus the - `NEO4J_*` settings) via `docker-compose-graphiti.yml`. +- Graphiti knowledge graph (`GRAPHITI_ENABLED=true`, `GRAPHITI_URL`, plus the `NEO4J_*` settings) via `docker-compose-graphiti.yml`. - Langfuse analytics via `docker-compose-langfuse.yml`. - Monitoring (Grafana / OpenTelemetry) via `docker-compose-observability.yml`. -Run the base `docker-compose.yml` first so the shared Docker networks exist, -then bring up the optional stacks. The same ordering note appears in the manual -installation section. +Run the base `docker-compose.yml` first so the shared Docker networks exist, then bring up the optional stacks. The same ordering note appears in the manual installation section. ## Step 7 - Start and verify 1. Start the stack: `docker compose up -d`. -2. Watch the logs until the backend is ready: - `docker compose logs -f pentagi`. -3. Re-run `ctester` and `etester` if you changed any provider settings. For - deeper checks of individual agent functions and tools, use `ftester` (see - [Function Testing with ftester](https://github.com/vxcontrol/pentagi#function-testing-with-ftester)). -4. Open `https://localhost:8443` (or your `PUBLIC_URL`) and sign in with the - default `admin@pentagi.com` / `admin`, then change the password immediately. +2. Watch the logs until the backend is ready: `docker compose logs -f pentagi`. +3. Re-run `ctester` and `etester` if you changed any provider settings. For deeper checks of individual agent functions and tools, use `ftester` (see [Function Testing with ftester](https://github.com/vxcontrol/pentagi#function-testing-with-ftester)). +4. Open `https://localhost:8443` (or your `PUBLIC_URL`) and sign in with the default `admin@pentagi.com` / `admin`, then change the password immediately. -After the server is running, several areas are managed in the web console under -Settings (Providers, Prompts, PentAGI API tokens), while LLM and search -credentials, Langfuse, Graphiti, and MCP remain server-side configuration. See -[Current Web Settings Coverage](https://github.com/vxcontrol/pentagi#current-web-settings-coverage) -for the exact split. +After the server is running, several areas are managed in the web console under Settings (Providers, Prompts, PentAGI API tokens), while LLM and search credentials, Langfuse, Graphiti, and MCP remain server-side configuration. See [Current Web Settings Coverage](https://github.com/vxcontrol/pentagi#current-web-settings-coverage) for the exact split. ## First-run configuration checklist @@ -172,10 +108,6 @@ for the exact split. ## Next step -Continue with -[How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login) -to create your first flow, use prompt templates, and review results. +Continue with [How to Use PentAGI After Login](https://github.com/vxcontrol/pentagi#how-to-use-pentagi-after-login) to create your first flow, use prompt templates, and review results. -For hardened or fully local deployments, see the -[Worker Node Setup](worker_node.md) and -[vLLM + Qwen3.5-27B-FP8](vllm-qwen35-27b-fp8.md) guides. +For hardened or fully local deployments, see the [Worker Node Setup](worker_node.md) and [vLLM + Qwen3.5-27B-FP8](vllm-qwen35-27b-fp8.md) guides.