Docker Installation

Set up your private Matrix server in minutes

This guide will help you set up a complete Matrix server using Docker. You'll have your own private directory for Krill App.

Prerequisites

A server or computer that can run 24/7
Docker and Docker Compose installed
A domain name (optional, for federation)
Basic command line knowledge

1 Install Docker

macOS

Download Docker Desktop from docker.com or use Homebrew:

brew install --cask docker

Linux

Install Docker Engine using the official script:

curl -fsSL https://get.docker.com | sh

Verify installation:

docker --version && docker-compose --version

2 Set Up Matrix Server

We provide a script that configures everything:

Download our setup script:

git clone https://github.com/krillbot/matrix-docker-setup.git
cd matrix-docker-setup

Run the setup:

./setup.sh

Follow the prompts to configure your server.

3 Configure Gateway

Point your Gateway to your new Matrix server:

channels:
  matrix:
    enabled: true
    homeserver: "https://matrix.your-domain.com"
    userId: "@admin:your-domain.com"
    accessToken: "your_generated_token"
    roomId: "!room-id:your-domain.com"

4 Verify Setup

Test that everything is working:

Matrix server is running: visit https://your-domain/_matrix/client/versions
Gateway connects: run clawdbot gateway status
App can pair: scan QR code from Gateway

Troubleshooting

Container won't start? +

Check logs with: docker-compose logs -f

Can't connect from outside? +

Verify ports 443 and 8448 are open in your firewall.

Federation not working? +

Ensure your domain has correct SRV records.

All Done!

Your private Matrix server is ready. Download the Krill App and pair it with your Gateway.

Download Krill App

Need help?

Join our Discord