Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Builds

The ShortMesh Builds repository provides Docker Compose orchestration for all ShortMesh services. It simplifies deployment by managing the entire stack with a single command, including RabbitMQ, Matrix Client, Interface API, and Authy API.

Prerequisites

Before setting up the Builds stack, ensure you have the required tools installed.

System requirements

The Builds stack requires:

  • Docker (v20.10+) - Container runtime
  • Docker Compose (v2.0+) - Multi-container orchestration (included with Docker Desktop)

Installing Docker

Debian/Ubuntu

# Update package index
sudo apt-get update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker compose version

macOS

Install Docker Desktop:

brew install --cask docker

Or download from Docker Desktop for Mac.

For detailed installation guides, see the Docker Installation Documentation.

External services

The Builds stack orchestrates all required ShortMesh services. However, you still need:

Matrix Homeserver

A running Matrix homeserver (e.g., Synapse) is required. See the Synapse setup guide for instructions on setting up a Matrix homeserver.

Matrix Authentication Service (MAS)

MAS provides OAuth2/OIDC authentication for Matrix. Configure and run MAS before starting the stack.

Matrix Bridges

Configure the bridges you want to support on your homeserver (WhatsApp, Telegram, Signal, etc.). See the Client setup guide for bridge configuration details.

Quick setup

The quickest way to get started is to use the automated setup script that configures all services at once.

Clone the repository

git clone https://github.com/shortmesh/Builds.git
cd Builds

Run complete setup

The setup script will interactively guide you through configuring all services:

make setup

This will:

  1. Create root .env file with Docker Compose settings
  2. Generate config/client/conf.yaml for Matrix Client
  3. Generate config/interface-api/.env with secure keys
  4. Generate config/authy-api/.env with secure keys
  5. Automatically fetch an Interface API token for Authy

Start all services

make up

This command starts:

  • RabbitMQ - Message broker (internal)
  • Matrix Client - Bridge service with Matrix homeserver (internal)
  • Interface API - Core messaging API (localhost:8082)
  • Authy API - OTP authentication service (localhost:8083)

View logs

# All services
make logs

# ShortMesh services only
make logs-shortmesh

# Specific service
make logs-interface
make logs-authy
make logs-client
make logs-rabbitmq

Verify installation

Once running, verify everything is working:

# Check service health
make health

# View resource usage
make stats

Access the services:

Manual setup

If you prefer manual configuration or need more control over the setup process, follow these steps.

Setup individual services

Configure each service separately:

# Setup environment variables
make setup-env

# Setup Matrix Client
make setup-client

# Setup Interface API
make setup-interface

# Setup Authy API
make setup-authy

Environment variables

The root .env file controls Docker Compose settings:

# RabbitMQ credentials
RABBITMQ_USER=guest
RABBITMQ_PASS=guest

# Database encryption (requires rebuild)
ENABLE_DB_ENCRYPTION=false

Service configurations

Matrix Client

Configuration location: config/client/conf.yaml

Key settings:

  • Matrix homeserver URL and domain
  • MAS client credentials
  • Database encryption key
  • RabbitMQ connection
  • Bridge configurations

See the Client setup guide for detailed configuration options.

Interface API

Configuration location: config/interface-api/.env

Key settings:

  • Server host and port
  • Database path and encryption
  • MAS and Matrix Client URLs
  • Client credentials
  • RabbitMQ connection

See the Interface API setup guide for detailed configuration options.

Authy API

Configuration location: config/authy-api/.env

Key settings:

  • Server host and port
  • Database path and encryption
  • Interface API URL and token

See the Authy setup guide for detailed configuration options.

Managing services

Use the Makefile commands to manage the stack lifecycle.

Starting and stopping

# Start all services
make up

# Stop all services
make down

# Restart all services
make restart

# Restart ShortMesh services only
make restart-shortmesh

Individual service control

# Restart specific service
docker compose restart matrix-client
docker compose restart interface-api
docker compose restart authy-api

# Stop specific service
docker compose stop interface-api

# Start specific service
docker compose start interface-api

Building and rebuilding

# Build all images
make build

# Rebuild and restart all services
make rebuild

# Rebuild ShortMesh services only
make rebuild-shortmesh

# Pull latest images from registry
make pull

Database migrations

Run migrations when updating services:

# Interface API migrations
make migrate-interface

# Authy API migrations
make migrate-authy

Debugging

Access shell in running containers:

# Shell access
make shell-client
make shell-interface
make shell-authy

# Or use docker compose directly
docker compose exec matrix-client sh
docker compose exec interface-api sh
docker compose exec authy-api sh

Configuration management

Fetching default configurations

Pull the latest default configurations from upstream repositories:

make fetch-defaults

Resetting configurations

Remove all generated configuration files:

# Remove all configs
make clean-config

# Remove specific service config
make clean-config-client
make clean-config-interface
make clean-config-authy
make clean-config-env

After cleaning, re-run setup:

make setup

Updating configurations

After modifying service configurations, restart the affected services:

# Matrix Client
make restart-client

# Interface API
make restart-interface

# Authy API  
make restart-authy

# All services
make restart

Network architecture

Services communicate via an internal Docker bridge network named shortmesh-network.

Internal services

These services are only accessible within the Docker network:

  • RabbitMQ: rabbitmq:5672 (AMQP), rabbitmq:15672 (Management)
  • Matrix Client: matrix-client:8080

External services

These services are exposed to localhost only:

  • Interface API: 127.0.0.1:8082
  • Authy API: 127.0.0.1:8083

Service URLs

When services communicate internally, they use internal hostnames:

# Interface API connects to Matrix Client
MATRIX_CLIENT_URL=http://matrix-client:8080

# Interface API connects to RabbitMQ
RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/

# Authy API connects to Interface API
INTERFACE_API_URL=http://interface-api:8080

Database encryption

Enable SQLCipher encryption for all services at build time.

Enabling encryption

Set in root .env file:

ENABLE_DB_ENCRYPTION=true

This build argument is passed to all services during the build process.

Rebuild after enabling

Encryption requires rebuilding all images:

make rebuild

Service configuration

After enabling encryption and rebuilding, ensure each service’s .env has:

DISABLE_DB_ENCRYPTION=false
DB_ENCRYPTION_KEY=<64-char-hex-key>

Keys are automatically generated by make setup.

Maintenance

Health checks

Check service status:

# Quick health check
make health

# Docker Compose status
docker compose ps

# Detailed service info
docker compose ps --format json

Resource monitoring

View resource usage:

# Resource stats
make stats

# Docker stats
docker stats

Backup

Backup service configurations:

make backup

This creates a timestamped backup of all configuration files.

Cleanup

Remove stopped containers and unused resources:

# Remove stopped containers
make clean

# Remove all containers and volumes (DESTRUCTIVE)
docker compose down -v

Validation

Validate the Docker Compose configuration:

make validate

Troubleshooting

Common issues

Service fails to start: Check logs for the specific service:

make logs-interface
docker compose logs interface-api

Database locked: Ensure only one instance of the service is running:

docker compose ps
docker compose down
make up

Port already in use: Check if another service is using the same port:

sudo lsof -i :8082
sudo lsof -i :8083

Migration failed: Run migrations manually:

make migrate-interface
make migrate-authy

Resetting everything

If you encounter persistent issues, reset the entire stack:

# Stop all services
make down

# Remove all configs
make clean-config

# Remove all volumes (DESTRUCTIVE - deletes all data)
docker compose down -v

# Re-setup
make setup
make up

Debug logging

Enable debug logging in service configurations:

Interface API (config/interface-api/.env):

LOG_LEVEL=debug

Authy API (config/authy-api/.env):

LOG_LEVEL=debug

Then restart the service:

make restart-interface
make restart-authy

Makefile reference

Complete list of available commands:

Setup commands

make setup               # Complete setup (all services)
make setup-env           # Setup environment variables
make setup-client        # Setup Matrix Client
make setup-interface     # Setup Interface API
make setup-authy         # Setup Authy API
make fetch-defaults      # Fetch fresh defaults from upstream

Control commands

make up                  # Start all services
make down                # Stop all services
make restart             # Restart all services
make restart-shortmesh   # Restart ShortMesh services only

Logging commands

make logs                # All services
make logs-shortmesh      # ShortMesh services
make logs-client         # Matrix Client
make logs-interface      # Interface API
make logs-authy          # Authy API
make logs-rabbitmq       # RabbitMQ

Database commands

make migrate-interface   # Run Interface migrations
make migrate-authy       # Run Authy migrations

Build commands

make build               # Build all images
make rebuild             # Rebuild and restart
make rebuild-shortmesh   # Rebuild ShortMesh only
make pull                # Pull latest images

Debug commands

make shell-client        # Shell access to client
make shell-interface     # Shell access to Interface API
make shell-authy         # Shell access to Authy API

Maintenance commands

make health              # Check service health
make stats               # View resource usage
make backup              # Backup configurations
make clean               # Remove stopped containers
make clean-config        # Remove all generated configs
make validate            # Validate docker-compose.yml

Help

make help                # Show all available commands

Additional resources