docs: add Ubuntu installation guide

2026-07-14 23:05:39 +01:00
parent ac2a1a447f
commit a91b7ccea2
1 changed files with 241 additions and 0 deletions
@@ -0,0 +1,241 @@
+# Installing Noema on Ubuntu
+
+This guide installs the packages needed to build, test, and run Noema on a
+64-bit Ubuntu host. Noema requires Go 1.26 or newer and PostgreSQL. pgvector is
+optional for basic operation but required for semantic memory retrieval.
+
+The recommended development setup runs PostgreSQL and pgvector with Docker
+Compose. A native PostgreSQL installation is documented separately below. Do
+not install both unless you deliberately want two database servers.
+
+## Package summary
+
+| Purpose | Packages or software | Required when |
+|---|---|---|
+| Base tools | `ca-certificates curl git make openssl tzdata` | Always |
+| Local builds and race tests | Go 1.26+, `build-essential` | Building outside Docker |
+| Container database | `docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin` | Recommended Docker path |
+| Native database | `postgresql-16 postgresql-client-16 postgresql-16-pgvector` | Native PostgreSQL path only |
+| Development analyzers | `staticcheck gosec govulncheck` | Optional; needed by `make lint security` |
+
+Node.js and npm are not required. The web interface is built into the Go
+binaries and has no JavaScript package-manager step.
+
+## 1. Install the base packages
+
+```sh
+sudo apt update
+sudo apt install -y ca-certificates curl git make openssl tzdata build-essential
+```
+
+`build-essential` supplies the C compiler needed by Go's race detector. It may
+be omitted on a runtime-only host receiving prebuilt Noema binaries.
+
+## 2. Install Go
+
+The Ubuntu archive may not provide a recent enough Go release. Install the
+current Go 1.26 patch release from <https://go.dev/dl/> and follow the official
+Linux instructions at <https://go.dev/doc/install>.
+
+This repository's `go.mod` currently selects Go 1.26.1 and toolchain 1.26.8.
+For an amd64 Ubuntu host, for example:
+
+```sh
+curl -LO https://go.dev/dl/go1.26.8.linux-amd64.tar.gz
+sudo rm -rf /usr/local/go
+sudo tar -C /usr/local -xzf go1.26.8.linux-amd64.tar.gz
+```
+
+Add Go to the shell path:
+
+```sh
+echo 'export PATH=/usr/local/go/bin:$HOME/go/bin:$PATH' >> "$HOME/.profile"
+export PATH=/usr/local/go/bin:$HOME/go/bin:$PATH
+go version
+```
+
+For arm64, use the `linux-arm64` archive instead. Never extract a new Go
+release over an existing `/usr/local/go` tree.
+
+## 3. Choose a database installation
+
+### Option A: Docker Compose database (recommended)
+
+The repository's Compose configuration uses `pgvector/pgvector:pg16`, so a
+host PostgreSQL or pgvector package is not needed. Installing pgvector on the
+host does not make it available inside a PostgreSQL container; the extension
+must exist in the container image where the server runs.
+
+Install Docker Engine from Docker's official apt repository. These commands
+follow <https://docs.docker.com/engine/install/ubuntu/>:
+
+```sh
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+  -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
+Types: deb
+URIs: https://download.docker.com/linux/ubuntu
+Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
+Components: stable
+Architectures: $(dpkg --print-architecture)
+Signed-By: /etc/apt/keyrings/docker.asc
+EOF
+
+sudo apt update
+sudo apt install -y docker-ce docker-ce-cli containerd.io \
+  docker-buildx-plugin docker-compose-plugin
+sudo systemctl enable --now docker
+```
+
+Verify the installation:
+
+```sh
+sudo docker run --rm hello-world
+docker compose version
+```
+
+Noema's Makefile invokes Docker without `sudo`. To permit that, add your user
+to the `docker` group and then log out and back in:
+
+```sh
+sudo usermod -aG docker "$USER"
+```
+
+Membership in the `docker` group effectively grants root-level access to the
+host. Use `sudo docker ...` instead and adjust the Makefile commands if that is
+not acceptable for the machine.
+
+Continue at [Configure and start Noema](#4-configure-and-start-noema).
+
+### Option B: Native PostgreSQL 16 and pgvector
+
+Use this path when PostgreSQL itself will run on the Ubuntu host. The pgvector
+package major version must match the PostgreSQL server major version. Noema's
+development configuration targets PostgreSQL 16.
+
+The PostgreSQL Global Development Group apt repository provides both
+PostgreSQL 16 and pgvector. Configure it using the project's official helper:
+
+```sh
+sudo apt install -y postgresql-common
+sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
+sudo apt update
+sudo apt install -y postgresql-16 postgresql-client-16 \
+  postgresql-16-pgvector
+sudo systemctl enable --now postgresql
+```
+
+Repository documentation: <https://www.postgresql.org/download/linux/ubuntu/>
+and <https://github.com/pgvector/pgvector#apt>.
+
+Create the Noema role and database. Choose a strong password when prompted:
+
+```sh
+sudo -u postgres createuser --pwprompt noema
+sudo -u postgres createdb --owner=noema noema
+sudo -u postgres psql --dbname=noema \
+  --command='CREATE EXTENSION IF NOT EXISTS vector;'
+```
+
+`CREATE EXTENSION` is required once in each database that uses vectors. It
+does not require `shared_preload_libraries` or a PostgreSQL restart. Confirm
+that the server can load it:
+
+```sh
+sudo -u postgres psql --dbname=noema \
+  --command="SELECT extversion FROM pg_extension WHERE extname = 'vector';"
+```
+
+Enable the extension before running Noema migrations. Migration 0005 creates
+the `memory_embeddings` table only when pgvector is available at migration
+time.
+
+## 4. Configure and start Noema
+
+From the repository root:
+
+```sh
+cp .env.example .env
+openssl rand -base64 32
+```
+
+Put the generated value in `NOEMA_MASTER_KEY` in `.env`, and set a strong
+`NOEMA_BOOTSTRAP_ADMIN_PASSWORD`. Never commit `.env`.
+
+For the recommended Docker database, keep the example connection string on
+port 5433 and run:
+
+```sh
+make dev
+```
+
+This starts the pgvector database container, builds Noema, applies migrations,
+and serves Noema at <http://127.0.0.1:8080>.
+
+For native PostgreSQL, change `NOEMA_DATABASE_URL` in `.env` to use port 5432
+and the password selected above, then build and migrate explicitly:
+
+```sh
+make build
+set -a
+. ./.env
+set +a
+./bin/noemactl migrate up
+./bin/noemad
+```
+
+Avoid placing passwords containing URI-reserved characters directly in a
+PostgreSQL URL unless they are percent-encoded.
+
+## 5. Verify pgvector and Noema
+
+For the Docker database:
+
+```sh
+docker compose -f deploy/docker-compose.yml exec -T db \
+  psql -U noema -d noema \
+  -c "SELECT extversion FROM pg_extension WHERE extname = 'vector';"
+
+docker compose -f deploy/docker-compose.yml exec -T db \
+  psql -U noema -d noema \
+  -c "SELECT to_regclass('public.memory_embeddings');"
+```
+
+For native PostgreSQL, run the equivalent queries with `psql`:
+
+```sh
+psql "$NOEMA_DATABASE_URL" \
+  -c "SELECT extversion FROM pg_extension WHERE extname = 'vector';"
+psql "$NOEMA_DATABASE_URL" \
+  -c "SELECT to_regclass('public.memory_embeddings');"
+```
+
+The first query should return a version and the second should return
+`memory_embeddings`. If migration 0005 had already run before pgvector became
+available, enabling the extension afterward does not rerun that migration; use
+a new repair migration rather than editing an applied migration.
+
+## 6. Optional development tools
+
+Install the analyzers used by the Makefile:
+
+```sh
+make tools
+```
+
+Then run the standard checks:
+
+```sh
+make fmt lint test-race security
+make test-db
+```
+
+`make test-db` uses the Docker database on port 5433 by default. To test with
+native PostgreSQL instead, provide its connection string explicitly:
+
+```sh
+NOEMA_TEST_DATABASE_URL="$NOEMA_DATABASE_URL" go test -race -count=1 ./...
+```