From 5b957bde258f5ea5613728c57acdf9ffad734a4d Mon Sep 17 00:00:00 2001 From: mason5052 Date: Wed, 3 Jun 2026 22:49:52 -0400 Subject: [PATCH 1/2] docs: add installing and configuring guide for first deployment 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, but the maintainer kept the issue open until an article about installing and configuring the product is published. Add examples/guides/installation_configuration.md, a concise ordered walkthrough that connects the existing detailed README sections into a single path: choose installer vs manual Docker Compose, set core server variables (PUBLIC_URL, CORS_ORIGINS, security vars), configure and test an LLM provider with ctester, configure and test the embedding provider with etester, optionally add search providers and the Graphiti/Langfuse/ observability stacks, then start and verify the stack and change the default admin password. It ends with a quick checklist and links forward to the existing post-login usage guide. The guide links to the relevant README reference sections rather than duplicating them. A single pointer link is added at the top of the README Quick Start section for discoverability. Docs only. No installer behavior, runtime code, env vars, or schema changes. Every environment variable named in the guide already exists in .env.example and backend/pkg/config/config.go. --- README.md | 2 + examples/guides/installation_configuration.md | 181 ++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 examples/guides/installation_configuration.md diff --git a/README.md b/README.md index fc5ca587..f09d1de9 100644 --- a/README.md +++ b/README.md @@ -569,6 +569,8 @@ 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. + ### System Requirements - Docker and Docker Compose (or Podman - see [Podman configuration](#running-pentagi-with-podman)) diff --git a/examples/guides/installation_configuration.md b/examples/guides/installation_configuration.md new file mode 100644 index 00000000..8257ca91 --- /dev/null +++ b/examples/guides/installation_configuration.md @@ -0,0 +1,181 @@ +# 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. + +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. + +## 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. + +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). + +## Step 2 - Set the core server variables + +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. + +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: + +- [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`: + +```bash +# From a local Go environment (run inside the backend directory) +go run cmd/ctester/*.go -verbose + +# Or from the running container +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. + +## 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`. + +Verify embeddings with `etester`: + +```bash +# Local Go environment +go run cmd/etester/main.go test -verbose + +# Running container +docker exec -it pentagi /opt/pentagi/bin/etester test +``` + +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. + +## 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`. +- 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. + +## 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. + +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 + +- [ ] Docker/Podman, CPU, RAM, and disk meet the minimums +- [ ] Installation method chosen (installer or manual Compose) +- [ ] `PUBLIC_URL` and `CORS_ORIGINS` set to the real hostname/IP (not `0.0.0.0`) +- [ ] `COOKIE_SIGNING_SALT` and database passwords changed from defaults +- [ ] At least one LLM provider configured and passing `ctester` +- [ ] Embedding provider configured and passing `etester` +- [ ] Search providers configured (optional) +- [ ] Graphiti / Langfuse / observability enabled if needed (optional) +- [ ] Stack started, logs healthy, default admin password changed + +## 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. + +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. From 620e699e714354b1e1b297f52632607b5cb57127 Mon Sep 17 00:00:00 2001 From: mason5052 Date: Wed, 3 Jun 2026 23:06:11 -0400 Subject: [PATCH 2/2] docs: address review feedback on install/config guide - Use the package-path form for the tester utilities (go run ./cmd/ctester, go run ./cmd/etester test) instead of shell glob / single-file invocations, which are more portable and avoid the multi-file compile pitfall. - Add -verbose to the container etester example so it matches the local example. - Wrap the new README Quick Start pointer across multiple lines; rendered Markdown is unchanged. --- README.md | 5 ++++- examples/guides/installation_configuration.md | 6 +++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f09d1de9..1d83c16e 100644 --- a/README.md +++ b/README.md @@ -569,7 +569,10 @@ 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 diff --git a/examples/guides/installation_configuration.md b/examples/guides/installation_configuration.md index 8257ca91..314cfbea 100644 --- a/examples/guides/installation_configuration.md +++ b/examples/guides/installation_configuration.md @@ -83,7 +83,7 @@ the agent behaviors PentAGI needs by running `ctester`: ```bash # From a local Go environment (run inside the backend directory) -go run cmd/ctester/*.go -verbose +go run ./cmd/ctester -verbose # Or from the running container docker exec -it pentagi /opt/pentagi/bin/ctester -verbose @@ -108,10 +108,10 @@ Verify embeddings with `etester`: ```bash # Local Go environment -go run cmd/etester/main.go test -verbose +go run ./cmd/etester test -verbose # Running container -docker exec -it pentagi /opt/pentagi/bin/etester test +docker exec -it pentagi /opt/pentagi/bin/etester test -verbose ``` If you later change the embedding provider or model, flush and reindex the