6.7 KiB
6.7 KiB
Installation Guide
This guide provides detailed instructions for installing Debai on your GNU/Linux system.
Prerequisites
System Requirements
- Operating System: Debian 13 (Trixie) or newer, Ubuntu 24.04 or newer, or compatible
- Python: 3.10 or later
- RAM: 4GB minimum, 8GB recommended
- Disk: 10GB free space (more for AI models)
- Architecture: x86_64 (amd64)
Dependencies
Required
sudo apt update
sudo apt install -y \
python3 \
python3-pip \
python3-venv \
python3-gi \
gir1.2-gtk-4.0 \
gir1.2-adw-1
Recommended
Docker Engine from Official Repository:
# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Add the repository to Apt sources
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
# Install Docker Engine, containerd, and Docker Compose
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
For Ubuntu:
# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install 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
# Add the repository to Apt sources
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
# Install Docker Engine, containerd, and Docker Compose
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Other utilities:
sudo apt install -y \
qemu-utils \
genisoimage
Installation Methods
Method 1: Debian Package (Recommended)
Download and install the .deb package:
# Download the latest release
wget https://github.com/manalejandro/debai/releases/latest/download/debai_1.0.0-1_all.deb
# Install
sudo dpkg -i debai_1.0.0-1_all.deb
# Install missing dependencies
sudo apt-get install -f
Method 2: From PyPI
# Install from PyPI
pip install debai
# Or with GUI support
pip install debai[gui]
Method 3: From Source
# Clone the repository
git clone https://github.com/debai/debai.git
cd debai
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install in development mode
pip install -e .
# Or with all extras
pip install -e ".[gui,dev,docs]"
Note: Docker Engine must be installed separately from the official Docker repository. See the "Recommended" dependencies section above for installation instructions.
Method 4: Build Debian Package
# Clone the repository
git clone https://github.com/manalejandro/debai.git
cd debai
# Install build dependencies
sudo apt install -y \
build-essential \
debhelper \
dh-python \
python3-all \
python3-setuptools
# Build the package
dpkg-buildpackage -us -uc -b
# Install
sudo dpkg -i ../debai_1.0.0-1_all.deb
sudo apt-get install -f
Post-Installation
Initialize Debai
# Basic initialization
debai init
# Full initialization (includes pulling recommended model)
debai init --full
Configure Docker (Required for Models)
After installing Docker Engine from the official repository:
# Verify Docker installation
docker --version
# Add your user to docker group
sudo usermod -aG docker $USER
# Restart Docker service
sudo systemctl restart docker
# Enable Docker to start on boot
sudo systemctl enable docker
# You may need to log out and back in for group changes to take effect
# Or use: newgrp docker
Test Docker installation:
# Run test container
docker run hello-world
# Check if Docker daemon is running
sudo systemctl status docker
Verify Installation
# Check version
debai --version
# Show status
debai status
# List available models
debai model list
Enable System Service (Optional)
# Enable Debai service to start on boot
sudo systemctl enable debai
# Start the service
sudo systemctl start debai
# Check status
sudo systemctl status debai
Configuration
User Configuration
Create or edit ~/.config/debai/config.yaml:
general:
log_level: info
agents:
max_concurrent: 5
auto_start: true
models:
default: llama3.2:3b
System Configuration
Edit /etc/debai/config.yaml for system-wide settings (requires root).
Troubleshooting
Docker Permission Denied
If you get "Permission denied" errors with Docker:
sudo usermod -aG docker $USER
newgrp docker # Or log out and back in
GTK/GUI Not Working
Install additional GTK dependencies:
sudo apt install -y \
gir1.2-gtk-4.0 \
gir1.2-adw-1 \
python3-gi \
python3-gi-cairo
Models Not Pulling
Check Docker status:
# Check if Docker is running
sudo systemctl status docker
# Check Docker Model Runner
docker ps | grep model
Import Errors
Ensure all Python dependencies are installed:
pip install -r requirements.txt
Upgrading
Debian Package
# Download new version
wget https://github.com/manalejandro/debai/releases/latest/download/debai_1.0.0-1_all.deb
# Upgrade
sudo dpkg -i debai_1.0.0-1_all.deb
pip
pip install --upgrade debai
From Source
cd debai
git pull
pip install -e .
Uninstallation
Debian Package
# Remove package
sudo apt remove debai
# Remove package and configuration
sudo apt purge debai
pip
pip uninstall debai
Clean Up Data
# Remove user data (optional)
rm -rf ~/.config/debai
rm -rf ~/.local/share/debai
# Remove system data (requires root)
sudo rm -rf /var/lib/debai
sudo rm -rf /etc/debai
Next Steps
After installation:
- Pull a Model:
debai model pull llama3.2:3b - Create an Agent:
debai agent create --template package_updater - Launch GUI:
debai-gui - Read the User Guide