πŸ“₯ Installation Guide

Choose the installation method that works best for you!

🎯 Quick Comparison

Method Difficulty Requirements Best For
�� Pre-built Binary ⭐ Easy None! Linux users, quick setup
πŸ”§ From Source ⭐⭐ Medium Python 3.12+ Development, Windows/macOS
🐳 Docker ⭐⭐ Medium Docker Containerized deployments

Method 1: πŸ“¦ Pre-built Binary (Recommended)

βœ… Easiest option! No Python installation required. Fully static binaries with zero dependencies.

Why Pre-built Binaries?

  • πŸš€ Zero Dependencies - No glibc, OpenSSL, Python, or system libraries needed
  • πŸ”’ Maximum Portability - Works on any Linux distro (kernel 3.2+)
  • πŸ“¦ Self-Contained - Everything bundled in one file
  • ⚑ Fast - Optimized builds with musl libc

Download

Visit the Download Page to get the latest pre-built binaries for your platform.

Installation Steps 

# 1. Download (example for x86_64)
wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-linux-x86_64.dist.tar.gz

# 2. Extract
tar -xzf chatrixcd-linux-x86_64.dist.tar.gz
cd chatrixcd-linux-x86_64.dist

# 3. Run it!
./chatrixcd
πŸ’‘ Pro Tip: Move the binary to /usr/local/bin/chatrixcd to run it from anywhere!

Method 2: πŸ”§ From Source

Perfect for development, customization, or if binaries aren’t available for your platform.

Prerequisites

  • Python 3.12, 3.13, or 3.14
  • pip (Python package manager)
  • git
πŸ“‹ Platform-Specific Prerequisites (Click to expand) **Ubuntu/Debian:** ```bash sudo apt update sudo apt install python3 python3-pip python3-venv git ``` **macOS (with Homebrew):** ```bash brew install python@3.12 git ``` **Windows:** 1. Install [Python 3.12+](https://www.python.org/downloads/) 2. Install [Git for Windows](https://git-scm.com/download/win)

Installation Steps

1️⃣
Clone the Repository
git clone https://github.com/CJFWeatherhead/ChatrixCD.git
cd ChatrixCD
2️⃣
Create Virtual Environment
python -m venv .venv
3️⃣
Activate Virtual Environment
# Linux/macOS:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate
4️⃣
Install Dependencies
pip install -r requirements.txt
pip install -e .
5️⃣
Run ChatrixCD
chatrixcd

Method 3: 🐳 Docker

Perfect for containerized deployments and production environments.

Quick Start 

# Using Docker Compose (recommended)
docker compose up -d

# Or using docker run
docker run -d \
  --name chatrixcd \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/store:/app/store \
  ghcr.io/cjfweatherhead/chatrixcd:latest

Dockerfile 

FROM python:3.12-alpine

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .
RUN pip install -e .

# Run
CMD ["chatrixcd"]
⚠️ Remember: Mount your config.json and store/ directory as volumes!

πŸͺŸ Windows & 🍎 macOS Users

Pre-built binaries aren’t available yet for Windows and macOS. Choose one of these options:

βœ… From Source

Recommended

Native installation with full TUI support

See Method 2 β†’

🐳 Docker Desktop

Containerized

Works on both platforms

See Method 3 β†’

πŸͺŸ WSL2 (Windows Only)

Linux on Windows

Use Linux binaries on Windows

View instructions
# Install WSL2
wsl --install

# In WSL terminal:
wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-linux-x86_64.dist.tar.gz
tar -xzf chatrixcd-linux-x86_64.dist.tar.gz
cd chatrixcd-linux-x86_64.dist
./chatrixcd

βš™οΈ Post-Installation

After installing, you need to:

1️⃣ Create config.json

Configuration Guide β†’

2️⃣ Run ChatrixCD

Quick Start Guide β†’

3️⃣ Invite to Room

Invitation Steps β†’

πŸš€ Production Deployment

For production use, consider:

  • systemd Service: Auto-start on boot (Deployment Guide)
  • Docker: Containerized deployment (Method 3)
  • Monitoring: Set up health checks and logging
  • Security: Use OIDC/SSO, restrict allowed_rooms

πŸ“– Full Deployment Guide β†’

❓ Need Help?

πŸ› Issues?

Report on GitHub

πŸ“– Docs

Support Guide

πŸ’¬ Questions?

GitHub Discussions