Skip to content

Installation

Jump to bottom
Lef edited this page Oct 4, 2026 · 3 revisions

Installation

This is the full fresh install, the same steps used for the 0.8.0 setup on a clean Linux machine. Expect about an hour, most of it downloads.

What you need

  • Linux with Docker and the Docker Compose v2 plugin (docker compose), and your user in the docker group
  • An NVIDIA GPU is strongly recommended (the app is tuned for 16 GB VRAM). It works on CPU, just slowly
  • LM Studio installed on the host, with its lms command line tool
  • Ollama installed on the host (on Arch: sudo pacman -S ollama-cuda)
  • Around 20 GB free disk for images and models, plus whatever your rule book PDFs take
  • Models: llama-krikri-8b-instruct (Storyteller, writes clean Greek) and text-embedding-bge-m3 (embeddings) in LM Studio; see AI Models

1. Clone

git clone https://github.com/Somnius/shadowrealms-ai.git
cd shadowrealms-ai

2. Create .env 

cp env.template .env
chmod 600 .env

Then fill in your own secrets. Never keep the template values:

python3 -c 'import secrets;print(secrets.token_hex(32))'   # FLASK_SECRET_KEY
python3 -c 'import secrets;print(secrets.token_hex(32))'   # JWT_SECRET_KEY
echo "sr_$(openssl rand -hex 4)"                            # POSTGRES_USER
python3 -c 'import secrets;print(secrets.token_urlsafe(24))' # POSTGRES_PASSWORD

Important: set DATABASE_HOST=localhost. The backend container uses the host network, so the compose service name postgresql doesn't resolve from inside it.

See Configuration for every setting.

3. Create invite codes

Registration needs an invite code. Copy the template and replace the example codes with your own random ones:

cp backend/invites.template.json backend/invites.json
chmod 600 backend/invites.json

Each code has a type (admin or player) and max_uses. Keep one admin code for your own account. More in Configuration.

4. Set up the models

lms server start
lms get gemma-4-e2b --gguf -y        # small English chat model (optional)
lms load llama-krikri-8b-instruct -y # Storyteller (English and Greek)
lms load text-embedding-bge-m3 -y    # multilingual embeddings
ollama pull llama3.2:3b              # used for dice/combat prompts and OOC moderation
sudo systemctl enable --now ollama

See AI Models for which model does what and how to fit them in VRAM.

5. GPU stats in Docker (optional)

The monitoring container reads GPU stats. It needs the NVIDIA container runtime:

sudo pacman -S nvidia-container-toolkit     # or your distro's package
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Note that restarting Docker stops every running container. Containers with restart policy no stay stopped.

6. Build and start

docker compose build monitoring
docker compose build backend
docker compose --profile dev build frontend   # the image is also used to build the production frontend
./scripts/build-frontend.sh                   # writes frontend/build/, which nginx serves
./docker-up.sh

The backend runs on gunicorn. Only nginx (:80) is reachable from the network; everything else listens on localhost.

On a first start PostgreSQL loads backend/init_postgresql_schema.sql (24 tables) automatically. That only happens when the volume is empty.

7. Check it

curl -s localhost:5000/health        # {"database":"connected", ..., "status":"healthy"}
docker compose ps                    # all 7 services up

Open http://localhost, register with your admin invite code (passwords need 12+ characters), create a chronicle (Classic or V5), and type /ai health in the chat. All three (LM Studio, Ollama, ChromaDB) should say OK.

8. Reaching it from other devices on your LAN

nginx listens on port 80 on all interfaces. If your machine runs a firewall, allow port 80 from your local network only, for example with ufw:

sudo ufw allow from 192.168.1.0/24 to any port 80 proto tcp comment 'ShadowRealms AI'

Use your own subnet. Then open http://<server-ip> from the other device. If you expose it to the internet, put HTTPS in front of it (a reverse proxy with a certificate); the app itself serves plain HTTP on port 80.

9. Rule books (optional)

See World of Darkness Books.

ShadowRealms AI

Clone this wiki locally