Installation Guide

This guide covers all installation methods for ChatrixCD.

Prerequisites

Python 3.9 or higher
uv - Fast Python package installer (recommended)
Access to a Matrix homeserver
Access to a Semaphore UI instance with API access

Installation Methods

Install from Source (Recommended)

# Clone the repository
git clone https://github.com/CJFWeatherhead/ChatrixCD.git
cd ChatrixCD

# Create a virtual environment
uv venv

# Activate the virtual environment
# On Linux/macOS:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

# Install the application
uv pip install -e .

Install with pip

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install the application
pip install -e .

Docker Installation

Using Docker Compose (Debian-based)

# Clone the repository
git clone https://github.com/CJFWeatherhead/ChatrixCD.git
cd ChatrixCD

# Create configuration file
cp config.json.example config.json
# Edit config.json with your settings

# Start with Docker Compose
docker-compose up -d

Using Docker Compose (Alpine Linux)

For a minimal deployment:

docker-compose -f docker-compose.alpine.yml up -d

Building Docker Image Manually

Debian-based:

docker build -t chatrixcd:latest .
docker run -v $(pwd)/config.json:/app/config.json -v $(pwd)/store:/app/store chatrixcd:latest

Alpine Linux:

docker build -f Dockerfile.alpine -t chatrixcd:alpine .
docker run -v $(pwd)/config.json:/app/config.json -v $(pwd)/store:/app/store chatrixcd:alpine

Configuration

After installation, you need to configure ChatrixCD. See the Configuration Guide for details.

Verification

Verify the installation:

chatrixcd --version

Or if running from source:

python -m chatrixcd.main --version

Next Steps

Troubleshooting

If you encounter issues during installation:

Ensure Python 3.9+ is installed: python --version
Check that all dependencies are installed: pip list
Verify Matrix homeserver is accessible
Verify Semaphore UI API is accessible

For more help, see the Support Guide.