From 80ff34b4230db2804b0d4f0249773af84dfc7866 Mon Sep 17 00:00:00 2001 From: Javier Martinez Date: Wed, 3 Jun 2026 15:44:59 +0200 Subject: [PATCH] docs: add required libraries (#2256) * docs: add instructions to install deps * docs: update order --- .../docs/pages/getting-started/quickstart.mdx | 26 ++-- fern/docs/pages/tools/database-tools.mdx | 122 +++++++++++++++++- 2 files changed, 136 insertions(+), 12 deletions(-) diff --git a/fern/docs/pages/getting-started/quickstart.mdx b/fern/docs/pages/getting-started/quickstart.mdx index 8c836962..1d8ada25 100644 --- a/fern/docs/pages/getting-started/quickstart.mdx +++ b/fern/docs/pages/getting-started/quickstart.mdx @@ -12,17 +12,6 @@ PrivateGPT connects to any OpenAI-compatible LLM server and exposes a private, s - - ```powershell - # Install uv first - powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - - # Then install PrivateGPT - uv tool install --python 3.11 ` - --find-links https://wheels.privategpt.dev/packages/ ` - "private-gpt[core]" - ``` - ```bash # Install uv first @@ -40,6 +29,17 @@ PrivateGPT connects to any OpenAI-compatible LLM server and exposes a private, s brew install private-gpt ``` + + ```powershell + # Install uv first + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + + # Then install PrivateGPT + uv tool install --python 3.11 ` + --find-links https://wheels.privategpt.dev/packages/ ` + "private-gpt[core]" + ``` + @@ -144,6 +144,10 @@ PrivateGPT connects to any OpenAI-compatible LLM server and exposes a private, s ## What's next? + + If you plan to use database querying or web search tools, review the dependency guides in [Database Tools](/tools/database-tools) and [Web Tools](/tools/web-tools) to install the required drivers, OS libraries, and browser dependencies. + + Run PrivateGPT with Docker for a fully isolated, production-ready setup. diff --git a/fern/docs/pages/tools/database-tools.mdx b/fern/docs/pages/tools/database-tools.mdx index 92d33628..e934131a 100644 --- a/fern/docs/pages/tools/database-tools.mdx +++ b/fern/docs/pages/tools/database-tools.mdx @@ -22,6 +22,8 @@ Built-in database tools include: ## How to install +### Python extras + Choose the smallest extra that matches your database: | Database | Extra | Installs | @@ -36,7 +38,7 @@ Choose the smallest extra that matches your database: If you only want the database tool itself, `tool-database` is the simplest entry point. If you want a narrower install, use the driver-specific extra directly. - The `database-db2` extra is only published for non-`aarch64` platforms in the current package metadata. + DB2 support is only available on non-`aarch64` platforms in the current package metadata. On arm64 / Apple Silicon, the `database-db2` extra cannot be installed and DB2 is not supported. Examples: @@ -53,6 +55,124 @@ uv sync --extra tool-database --- +### OS libraries required + +The Python drivers above need database client libraries from the operating system. + +| Database | What the driver needs | Notes | +|---|---|---| +| PostgreSQL | No extra OS package in most cases | `psycopg2-binary` and `asyncpg` bundle their own client libraries on common platforms. | +| MySQL / MariaDB | MySQL/MariaDB client libraries | On Debian/Ubuntu the Dockerfile installs `libmariadb3`. On other distros install your MySQL/MariaDB client package. | +| SQL Server | Microsoft ODBC driver | The Docker image installs `msodbcsql18` from Microsoft’s APT repo. Use the matching ODBC driver for your OS. | +| DB2 | IBM DB2 client libraries | `ibm-db` uses IBM’s DB2 client; availability varies by platform and architecture. Not available on arm64 / Apple Silicon. | + +--- + +## Install by environment + + + + When you use the published Docker image (`zylonai/private-gpt:latest` and variants), there is nothing extra to install for database tools: the image already contains the Python drivers and required OS libraries for all supported databases. + + Only if you are **building your own image from source** do you need to think about extras: + + ```bash + docker build \ + --build-arg EXTRAS="core tool-database" \ + -t private-gpt-db . + ``` + + This mirrors the official image behavior by: + + - Installing the Python extras from the table above (`tool-database` → all `database-*` extras). + - Triggering the Dockerfile logic that installs OS-level libraries (`libmariadb3` for MySQL/MariaDB and `msodbcsql18` for SQL Server). + + After that, run the image as usual: + + ```bash + docker run -p 8080:8080 private-gpt-db + ``` + + You can still pass additional extras via `EXTRAS` if you also need ingestion, media, or other tools. + + + For local macOS installs, first install PrivateGPT with database support (via `uv` or the package): + + ```bash + # Example with uv source install + uv sync --frozen --extra core --extra tool-database + ``` + + Then ensure database client libraries are available: + + - **PostgreSQL**: Install Postgres (includes client libs), for example: + + ```bash + brew install postgresql + ``` + + - **MySQL / MariaDB** (matches the example setup script): + + ```bash + brew install mysql pkg-config + ``` + + - **SQL Server**: Install the Microsoft ODBC driver for SQL Server, for example: + + ```bash + brew install unixodbc freetds + brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release + brew update + HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18 + ``` + + - **DB2**: (non-arm64 only) Install IBM’s DB2 client for macOS and configure the environment according to IBM’s documentation; `ibm-db` will detect it. DB2 is not available on Apple Silicon. + + + On Linux, install PrivateGPT with database support (for example with uv): + + ```bash + uv sync --frozen --extra core --extra tool-database + ``` + + Then install the OS packages for your distribution. + + For Debian/Ubuntu-like systems: + + - **PostgreSQL**: + + ```bash + sudo apt update + sudo apt install postgresql-client + ``` + + - **MySQL / MariaDB** (matches the Dockerfile’s `libmariadb3`): + + ```bash + sudo apt update + sudo apt install libmariadb3 + ``` + + - **SQL Server** (same approach as the Dockerfile): + + ```bash + curl -sSL -O https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb + sudo dpkg -i packages-microsoft-prod.deb + rm packages-microsoft-prod.deb + sudo apt update + sudo ACCEPT_EULA=Y apt install msodbcsql18 + ``` + + - **DB2** (non-arm64 only): + + Install IBM’s DB2 client packages for your distribution and architecture, then configure as documented by IBM. The `database-db2` extra is only published for non-`aarch64` platforms and is not available on arm64. + + After installing both the Python extras and the OS libraries, restart the server and `database_query_v1` will be able to connect to your configured databases. + + + +--- + ## Settings reference Database query does not have a global `enabled` flag in `settings.yaml`. Instead, the server uses runtime limits from `database_query`, and each request provides the target database through a `sql_database` artifact.