Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tudoumono/Sherpa/llms.txt

Use this file to discover all available pages before exploring further.

Sherpa ships as a single release tarball containing the application core, scripts, and configuration templates. The stores (PostgreSQL, Neo4j, Elasticsearch) are managed by Docker Compose, while the app process runs directly on the host under systemd. This page covers both the one-command local-development startup and the full production deployment workflow.

​
Local development

For a cloned repository, one command handles everything — venv creation, dependency installation, store startup, and FastAPI launch: 
./scripts/start.sh
# or equivalently:
make start
The server starts on http://127.0.0.1:8000. Open http://127.0.0.1:8000/ui/chat.html in a browser. Stop the app with Ctrl+C; stop the Docker stores with make stop.
make start and ./scripts/start.sh use make serve (i.e. run-api.sh serve) internally, which sets SHERPA_ENV=production and clears SHERPA_USE_FIXTURES. Use make api (which calls run-api.sh dev) only when you need fixture data during development — fixture mode is never appropriate for real document corpora.

​
Production deployment

Production layout uses three separate trees to cleanly separate code, configuration, and data:
PurposePath
Application code/opt/sherpa/current
Environment config/etc/sherpa/sherpa.env
Runtime data/srv/sherpa
1

Build the release tarball

Run make dist from the repository root. It creates a versioned tarball and a matching SHA-256 checksum in dist/. The tarball excludes fixtures/, tests/, and mockups/.
make dist
# produces: dist/sherpa-<version>.tar.gz
#           dist/sherpa-<version>.tar.gz.sha256
2

Create the directory layout on the server

sudo install -d /opt/sherpa/current /etc/sherpa /srv/sherpa
3

Extract the tarball

sudo tar -xzf dist/sherpa-dist.tar.gz -C /opt/sherpa/current
4

Copy and edit the production environment file

sudo cp /opt/sherpa/current/.env.production.example /etc/sherpa/sherpa.env
sudo editor /etc/sherpa/sherpa.env
At minimum, replace every CHANGE_ME_… placeholder. Key variables to set:
  • POSTGRES_PASSWORD / DATABASE_URL — PostgreSQL credentials
  • NEO4J_PASSWORD — Neo4j password
  • SHERPA_ADMIN_PASSWORD — initial admin password for bootstrap
  • SHERPA_AUDIT_IP_SALT — random salt for IP-address hashing in audit logs
  • SHERPA_DERIVED_DIR and SHERPA_USERS_DIR — must be absolute paths, not relative
See the Configuration reference for the full variable list.
5

Create runtime users and directory ownership

sudo /opt/sherpa/current/scripts/setup-runtime-users.sh
This creates the sherpa-ingest, sherpa-agent, sherpa-api, and sherpa-workspace users and sets ownership and permissions on /srv/sherpa/kb, /srv/sherpa/users, and /srv/sherpa/derived. The script is idempotent; re-running it is safe. Use --dry-run to preview changes or --verify to inspect the current state without modifying anything.
6

Install Python dependencies

Create a dedicated virtualenv and install from requirements.txt:
cd /opt/sherpa/current
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
The systemd unit references this venv via PYTHON_BIN=/opt/sherpa/current/.venv/bin/python.
7

Run the production preflight check

SHERPA_ENV_FILE=/etc/sherpa/sherpa.env \
  /opt/sherpa/current/scripts/check-production.sh
The check verifies that:
  • The env file is present and loadable
  • Python and required packages (fastapi, uvicorn, psycopg, neo4j) can be imported
  • SHERPA_USE_FIXTURES is not set
  • SHERPA_AUTH_ENABLED=1 is set
  • A PostgreSQL connection variable is present
  • SHERPA_USERS_DIR and SHERPA_DERIVED_DIR are absolute paths that do not point into fixtures/
Fix any NG: lines before proceeding. WARN: lines are advisory.
8

Install and enable the systemd unit

sudo cp /opt/sherpa/current/deploy/systemd/sherpa-api.service \
        /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sherpa-api.service
sudo systemctl status sherpa-api.service
The unit file runs as sherpa-api:sherpa-workspace, reads the env file from /etc/sherpa/sherpa.env, and enforces ProtectSystem=strict, ReadOnlyPaths=/srv/sherpa/kb, and ReadWritePaths=/srv/sherpa/users /srv/sherpa/derived.
9

Verify the service is healthy

curl -fsS http://127.0.0.1:8000/healthz
A successful response confirms the API is up. Open the admin UI to complete user setup and register your first world.

​
Systemd unit reference

The bundled unit file at deploy/systemd/sherpa-api.service is reproduced here for reference: 
[Unit]
Description=Sherpa FastAPI
Wants=network-online.target
After=network-online.target docker.service

[Service]
Type=simple
User=sherpa-api
Group=sherpa-workspace
WorkingDirectory=/opt/sherpa/current
Environment=SHERPA_ENV_FILE=/etc/sherpa/sherpa.env
Environment=PYTHON_BIN=/opt/sherpa/current/.venv/bin/python
Environment=PYTHONUNBUFFERED=1
Environment=PYTHONDONTWRITEBYTECODE=1
UMask=0007
ExecStart=/opt/sherpa/current/scripts/run-api.sh serve
Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadOnlyPaths=/srv/sherpa/kb
ReadWritePaths=/srv/sherpa/users /srv/sherpa/derived

[Install]
WantedBy=multi-user.target

​
Make command reference

CommandDescription
make upStart PostgreSQL, Neo4j, and Elasticsearch via Docker Compose
make bootstrapPrepare .env, create local data directories, and wait for stores to be ready
make serveStart FastAPI in production mode (SHERPA_ENV=production, fixtures disabled). Use this for real document corpora.
make stopStop all Docker Compose stores
make statusShow Docker Compose container status
make logsTail Docker Compose store logs (--tail=100 -f)
make prod-checkRun the production preflight script (reads SHERPA_ENV_FILE)
make distBuild a versioned release tarball in dist/ (excludes fixtures, tests, mockups)
make nukeStop stores and delete all Docker volumes (all database data is destroyed)
make nuke runs docker compose down -v, which permanently deletes the Docker volumes for PostgreSQL, Neo4j, and Elasticsearch. All conversation history, user accounts, the world registry, and all indexed graph and search data will be lost. There is no undo. Back up the PostgreSQL database (pg_dump) before running this command if any data needs to be preserved.

​
Port and bind address

By default, FastAPI binds to 127.0.0.1:8000. To change either value, set the corresponding environment variable in your env file before starting the service: 
SHERPA_HOST=127.0.0.1   # bind address (keep localhost unless behind a reverse proxy)
SHERPA_PORT=8000         # TCP port
For multi-worker deployments, increase the Uvicorn worker count: 
SHERPA_UVICORN_WORKERS=4

​
Production / test separation (fail-closed)

Sherpa enforces a hard boundary between production and test data at startup:
  • make serve sets SHERPA_ENV=production and clears SHERPA_USE_FIXTURES unconditionally.
  • If SHERPA_ENV=production is set and any fixture path is configured in the same environment, the process refuses to start.
  • The make dist tarball never includes the fixtures/ directory.
Never set SHERPA_USE_FIXTURES=1 in a production environment file. If Sherpa detects both SHERPA_ENV=production and an active fixtures setting, it will refuse to start. This fail-closed behaviour is intentional: fixture data must never silently pollute a production corpus.

Build docs developers (and LLMs) love

Get started for freeTalk to us