Installation

System Packages

Install the required system packages for your distribution.

Debian / Ubuntu


sudo apt update
sudo apt install -y \
  python3 python3-venv python3-pip \
  python3-libvirt \
  nodejs npm \
  git \
  libvirt-daemon-system libvirt-clients \
  qemu-kvm qemu-utils \
  live-build \
  virtinst \
  screen \
  openssh-client

Fedora


sudo dnf install -y \
  python3 python3-pip python3-virtualenv \
  python3-libvirt \
  nodejs npm \
  git \
  libvirt libvirt-client \
  qemu-kvm qemu-img \
  virt-install \
  screen \
  openssh-clients

Fedora does not ship live-build. You will need Debian-based build capabilities — either run builds inside a Debian container or install live-build manually.

User Setup

Add your user to the required groups:


sudo usermod -aG kvm $USER
sudo usermod -aG libvirt $USER

Log out and back in for group membership to take effect.

Clone the Repository


git clone https://github.com/openfactory-tech/openfactory.git
cd openfactory

Install Claude Code CLI

The build system requires the Claude Code CLI on the host. Install it and authenticate:


npm install -g @anthropic-ai/claude-code

Set your API key in the environment (add to ~/.bashrc or similar):


export ANTHROPIC_API_KEY="sk-ant-..."

Backend Setup

elster-terminal-backend


cd elster-terminal-backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Create the data directory structure:


mkdir -p data/logs data/recipes data/schemas

cto-gui-libvirt-backend


cd ../cto-gui-libvirt-backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
mkdir -p data/logs data/benchmarks data/tests data/live-vms data/security_patches data/manifests

Note: The python3-libvirt system package must be accessible inside the venv. Either install the venv with --system-site-packages, or symlink the system libvirt module:


# Option A: Recreate venv with system packages
python3 -m venv --system-site-packages venv
 
# Option B: Symlink (if venv already created without system packages)
SITE=$(python3 -c "import site; print(site.getsitepackages()[0])")
ln -s /usr/lib/python3/dist-packages/libvirt* venv/lib/python3.*/site-packages/

web-terminal-backend


cd ../web-terminal-backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
mkdir -p data/keys

Frontend Setup


cd ../elster-terminal
npm install

Sudoers Rule

The build worker runs lb build as root. Create a sudoers rule to allow this without a password:


sudo tee /etc/sudoers.d/openfactory-buildworker << 'EOF'
# Allow the openfactory user to run the build worker as root
YOUR_USERNAME ALL=(root) NOPASSWD:SETENV: /path/to/elster-terminal-backend/venv/bin/python
EOF

Replace YOUR_USERNAME with your actual username and /path/to/ with the real path.


sudo chmod 440 /etc/sudoers.d/openfactory-buildworker
sudo visudo -c  # verify syntax

Clone Build-ISO Repositories

The build worker needs access to the build-iso repositories:


mkdir -p ~/elster-builds
cd ~/elster-builds
 
git clone git@github.com:openfactory-tech/build-iso-public.git
git clone git@github.com:openfactory-tech/build-iso-ubuntu.git

Ensure your SSH key has read access to these repositories.

Next Steps

Proceed to Configuration to set up environment variables.