Skip to content

installation-linux.md

Latest commit

 

History

History
138 lines (97 loc) · 4.67 KB

installation-linux.md

File metadata and controls

138 lines (97 loc) · 4.67 KB
Raw

Installation - Linux

Tested on Ubuntu 24.04 LTS with an NVIDIA RTX 4070. Should work identically on Debian 12, Fedora 40, and Arch.

Required software

Tool Version Purpose
Docker Engine ≥ 26.0 Runs the worker container
NVIDIA Container Toolkit latest Only if you want Ollama in Docker (we won't)
Ollama ≥ 0.5 Local LLM runtime
Foundry (cast) ≥ 1.7.1 EVM wallet ops, contract reads
Bash ≥ 4.0 Required for several scripts

Bash 4.0+ is required, but any mainstream distro from the last decade satisfies this (Ubuntu ≥ 10.04, RHEL ≥ 7, etc.). Run bash --version to confirm if unsure.

Install steps (Ubuntu / Debian)

# 1. Docker Engine (community edition, from the official repo)
sudo apt-get update
sudo apt-get install -y ca-certificates curl
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
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Optional but strongly recommended: avoid sudo for every docker command
sudo usermod -aG docker $USER
newgrp docker

# 2. Ollama (native install with auto-detected GPU acceleration)
curl -fsSL https://ollama.com/install.sh | sh

# 3. Foundry
curl -L https://foundry.paradigm.xyz | bash
~/.foundry/bin/foundryup

foundryup puts cast, forge, anvil, chisel in ~/.foundry/bin. Add it to your PATH if it isn't already:

echo 'export PATH="$HOME/.foundry/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

NVIDIA / CUDA

Ollama on Linux looks for NVIDIA via the standard driver stack. Verify:

nvidia-smi

Should show your GPU, total VRAM, driver version, and CUDA version. You need ≥ 8 GB VRAM for llama3-8b at Q4 quantization. See the Windows install guide for a list of cards that work.

If nvidia-smi doesn't exist, install the proprietary NVIDIA driver:

# Ubuntu - use ubuntu-drivers to pick the right version
sudo ubuntu-drivers autoinstall
sudo reboot

Reboot, then re-verify nvidia-smi.

Post-install verification

docker --version          # Docker version 26.x or newer
docker ps                  # should return an empty table
ollama --version
ollama list
cast --version

Linux-specific gotchas

Ollama systemd service

The official installer registers Ollama as a systemd service that starts at boot. Verify:

systemctl status ollama
# Active: active (running)

If it's not running:

sudo systemctl enable --now ollama

Reaching Ollama from the container

On Linux, host.docker.internal doesn't resolve out of the box (it's a Docker Desktop convention). The toolkit's 08-run-worker.sh adds --add-host=host.docker.internal:host-gateway which uses Docker's host-gateway feature to make it resolve to the host's gateway IP.

If you want a more explicit setup, use --network host and OLLAMA_URL=http://127.0.0.1:11434:

docker run -d --restart always --network host \
  --name lightchain-worker \
  -v ~/lightchain-worker/keys:/data \
  -e OLLAMA_URL=http://127.0.0.1:11434 \
  ... rest of env ... \
  $IMAGE

The trade-off: with --network host, the container shares the host's network namespace (so its 127.0.0.1 is yours). Slightly less isolated, slightly more straightforward.

Bind Ollama to all interfaces (if you need other machines to reach it)

By default Ollama binds to 127.0.0.1:11434. To expose it on the LAN (rarely needed - the worker container already reaches it via host-gateway):

sudo systemctl edit ollama

Add:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Then sudo systemctl restart ollama.

Run the worker as a systemd unit (for production)

See examples/systemd/lightchain-worker.service for a unit file that brings up Docker, waits for Ollama, then ensures the worker container is running.

Next steps

You're ready. Continue with docs/onboarding.md.