noema/UBUNTU_INSTALL.md

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

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:

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:

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/:

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:

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:

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.

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:

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:

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:

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:

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:

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:

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:

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:

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:

make tools

Then run the standard checks:

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:

NOEMA_TEST_DATABASE_URL="$NOEMA_DATABASE_URL" go test -race -count=1 ./...