From 7a004f1d518a4f067f5f84c50646a7acc642cb71 Mon Sep 17 00:00:00 2001 From: Promise Fru Date: Thu, 21 May 2026 16:36:57 +0100 Subject: [PATCH 1/2] feat(docs): add setup guides and deployment configs --- .github/workflows/deploy.preview.yml | 57 ++ book.toml | 21 +- src/SUMMARY.md | 11 +- src/assets/css/base.css | 7 + src/chapter_1.md | 1 - src/img/architecture.png | Bin 0 -> 20312 bytes src/introduction/overview.md | 29 + src/setup/authy.md | 696 ++++++++++++++++++++++ src/setup/builds.md | 630 ++++++++++++++++++++ src/setup/client.md | 696 ++++++++++++++++++++++ src/setup/interface-api.md | 830 +++++++++++++++++++++++++++ 11 files changed, 2973 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/deploy.preview.yml create mode 100644 src/assets/css/base.css delete mode 100644 src/chapter_1.md create mode 100644 src/img/architecture.png create mode 100644 src/introduction/overview.md create mode 100644 src/setup/authy.md create mode 100644 src/setup/builds.md create mode 100644 src/setup/client.md create mode 100644 src/setup/interface-api.md diff --git a/.github/workflows/deploy.preview.yml b/.github/workflows/deploy.preview.yml new file mode 100644 index 0000000..a3cdb80 --- /dev/null +++ b/.github/workflows/deploy.preview.yml @@ -0,0 +1,57 @@ +name: Preview Deployment Pipeline + +on: + push: + branches: + - preview + +jobs: + build: + name: Build Application + runs-on: ubuntu-latest + environment: + name: preview + url: https://preview-3.relaysms.afkanerd.de + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v2 + with: + mdbook-version: "latest" + + - name: Build project + run: | + mdbook build + + - name: Securely Copy Artifacts to Server + uses: appleboy/scp-action@master + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USER }} + key: ${{ secrets.SSH_KEY }} + source: "book/*" + target: ${{ secrets.BUILD_PATH }} + strip_components: 1 + rm: false + + - name: Execute Remote SSH Commands + uses: appleboy/ssh-action@master + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USER }} + key: ${{ secrets.SSH_KEY }} + script: | + set -e + + echo "============================" + echo "🚀 Deploy Project ..." + echo "============================" + if ! ${{secrets.BUILD_CMD}}; then + echo "❌ Error deploying project!" + exit 1 + fi + echo "===============================" + echo "✅ Deployment complete" + echo "===============================" diff --git a/book.toml b/book.toml index 0fc964b..898b03d 100644 --- a/book.toml +++ b/book.toml @@ -1,6 +1,21 @@ +# Documentation for possible options in this file is at +# https://rust-lang.github.io/mdBook/format/config.html [book] -authors = ["Vanessa Christopher"] +title = "ShortMesh Documentation" +authors = ["ShortMesh Team"] language = "en" -multilingual = false + +# The directory that documentation files are stored in src = "src" -title = "ShortMesh Documentation" + +[output.html] +# The source code URL of the repository +git-repository-url = "https://github.com/shortmesh/documentation" + +# Remove the numbers that appear before each item in the sidebar, as they can +# get quite messy as we nest deeper +no-section-label = true + +# Additional HTML, JS, CSS that's injected into each page of the book. +# More information available in docs/website_files/README.md +additional-css = ["src/assets/css/base.css"] diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7390c82..b469787 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,3 +1,12 @@ # Summary -- [Chapter 1](./chapter_1.md) +# Introduction + +- [Overview](./introduction/overview.md) + +# Setup + +- [Client](./setup/client.md) +- [Interface API](./setup/interface-api.md) +- [Authy](./setup/authy.md) +- [Builds](./setup/builds.md) diff --git a/src/assets/css/base.css b/src/assets/css/base.css new file mode 100644 index 0000000..4d10653 --- /dev/null +++ b/src/assets/css/base.css @@ -0,0 +1,7 @@ +/* + * Indents each chapter title in the left sidebar so that they aren't + * at the same level as the section headers. + */ +.chapter-item { + margin-left: 1em; +} diff --git a/src/chapter_1.md b/src/chapter_1.md deleted file mode 100644 index b743fda..0000000 --- a/src/chapter_1.md +++ /dev/null @@ -1 +0,0 @@ -# Chapter 1 diff --git a/src/img/architecture.png b/src/img/architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..5440a2d02beae6a7e621f7af4e8c8fca195147ce GIT binary patch literal 20312 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 API + +The Interface API is the public-facing REST API that enables third-party integrations with ShortMesh. It is designed with security, authentication, and session management as first-class concerns. + +This layer serves two key purposes: it shields Matrix credentials from external exposure, and it abstracts away the location of the underlying Matrix Homeserver. This address would otherwise be visible if integrations were built directly into the [client](#a-hrefhttpsgithubcomshortmeshclientshortmesh-client-targetblank-relnoopener-noreferrerclienta). + +### Client + +The Client is a Matrix client built in Go using the Mautrix SDK, an implementation of the Matrix protocol specification. It provides the core protocol integration layer that powers ShortMesh's messaging capabilities. + +## Integrations + +### Authy API + +Authy is an integration built on top of ShortMesh's Interface API. Its primary purpose is delivering authentication codes to users on demand, as an alternative to traditional SMS-based OTP delivery. By leveraging Matrix bridges, these codes can instead be sent to any supported third-party platform. + +Authy handles the full authentication lifecycle: cryptographic code generation, session management, and code validation. + +Developers integrate Authy into their applications through an embeddable JavaScript widget (demo), similar in concept to Google OAuth buttons. When a user selects their preferred platform for receiving a one-time password (OTP), the widget triggers the Interface API, which instructs the Client to deliver the code through the appropriate channel. diff --git a/src/setup/authy.md b/src/setup/authy.md new file mode 100644 index 0000000..9525c39 --- /dev/null +++ b/src/setup/authy.md @@ -0,0 +1,696 @@ +# Authy + +Authy is an open-source OTP (One-Time Password) service that generates, delivers, and verifies one-time passwords. + +## Prerequisites + +Before installing Authy, you'll need to ensure you have the required dependencies and external services. + +### System requirements + +Authy requires: + +- **Go 1.25.0 or higher** - The Go programming language runtime and compiler +- **SQLite** - Lightweight database (usually pre-installed on most systems) + +Optional but recommended: + +- **SQLCipher** - For encrypted database support + +### Installing dependencies + +#### Debian/Ubuntu + +Install the required system dependencies: + +```bash +sudo apt-get update +sudo apt-get install -y \ + golang-1.25 \ + libsqlite3-dev \ + build-essential +``` + +For SQLCipher support (encrypted database): + +```bash +sudo apt-get install -y libsqlcipher-dev +``` + +If your distribution doesn't have Go 1.25 in the default repositories, download it from [go.dev/dl](https://go.dev/dl/): + +```bash +wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz +sudo rm -rf /usr/local/go +sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz +export PATH=$PATH:/usr/local/go/bin +``` + +### External services + +Authy requires the Interface API service to be running: + +#### Interface API + +The Interface API service **must** be set up and running before starting Authy. The Interface API provides the core messaging infrastructure that Authy uses to deliver OTPs across different platforms. + +See the [Interface API setup guide](./interface-api.md) for detailed installation instructions. + +You will need: + +- Interface API URL (e.g., `http://localhost:8082`) +- Interface API authentication token + +## Quick setup + +The quickest way to get started is to use the automated setup script. This method is ideal for development and testing. + +### Clone the repository + +```bash +git clone https://github.com/shortmesh/Authy-API.git +cd Authy-API +``` + +### Generate configuration + +The setup script automatically creates a `.env` file with cryptographically secure keys: + +```bash +make setup +``` + +This creates a `.env` file with auto-generated values for `DB_ENCRYPTION_KEY`. + +Alternatively, create the file manually: + +```bash +cp example.env .env +``` + +Then edit `.env` and generate the required keys: + +```bash +# Generate DB_ENCRYPTION_KEY (32 bytes hex, needed if encryption enabled) +openssl rand -hex 32 +``` + +### Configure environment variables + +Edit your `.env` file with the required settings: + +```bash +# Application mode: development or production +APP_MODE=development + +# Server settings +HOST=127.0.0.1 +PORT=8080 + +# Database configuration +SQLITE_DB_PATH=./data/authy.db +DISABLE_DB_ENCRYPTION=false +DB_ENCRYPTION_KEY= + +# Auto-run migrations (disable in production) +AUTO_MIGRATE=true + +# Interface API configuration +INTERFACE_API_URL=http://localhost:8082 +INTERFACE_API_TOKEN=mt_xxxxx +``` + +For a complete reference of all configuration options, see [Configuration reference](#configuration-reference). + +### Initialize the database + +Run migrations to set up the database schema: + +```bash +make migrate-up +``` + +Check the migration status: + +```bash +make migrate-status +``` + +### Start the server + +```bash +make run +``` + +The server will start and listen on `http://localhost:8080`. + +### Verify the installation + +Once running, verify everything is working: + +```bash +# View Swagger documentation in browser +open http://localhost:8080/docs/index.html + +# Access demo UI +open http://localhost:8080/demo +``` + +The server provides: + +- **API**: +- **Swagger docs**: +- **Demo UI**: + +## Docker + +Docker provides an isolated environment and simplifies dependency management. This is suitable for both development and production deployments. + +### Prerequisites + +Ensure you have Docker installed: + +```bash +# Verify Docker installation +docker --version +``` + +> [!IMPORTANT] +> The Interface API service must be set up and running before starting Authy. See [Interface API setup](./interface-api.md) for instructions. + +### Create configuration + +Before building the Docker image, you need a `.env` file. You can create it locally: + +```bash +cp example.env .env +# Edit .env with your configuration +``` + +Or use the setup script: + +```bash +make setup +``` + +Update the `.env` file with your Interface API connection details: + +```bash +INTERFACE_API_URL=http://localhost:8082 +INTERFACE_API_TOKEN=mt_xxxxx +``` + +### Build the image + +Build the Docker image: + +```bash +docker build -t authy-api . +``` + +For encrypted database support with SQLCipher: + +```bash +docker build --build-arg ENABLE_DB_ENCRYPTION=true -t authy-api . +``` + +Then ensure your `.env` has: + +```bash +DISABLE_DB_ENCRYPTION=false +DB_ENCRYPTION_KEY= +``` + +### Run migrations + +If you've disabled automatic migrations (`AUTO_MIGRATE=false`), run them manually: + +```bash +docker run --rm \ + -v $(pwd)/data:/app/data \ + -v $(pwd)/.env:/app/.env \ + authy-api \ + ./migrate -action=up +``` + +### Run the container + +Start the API server: + +```bash +docker run -d \ + --name authy-api \ + -p 8080:8080 \ + -v $(pwd)/data:/app/data \ + -v $(pwd)/.env:/app/.env \ + authy-api +``` + +### View logs + +```bash +docker logs -f authy-api +``` + +### Stop the container + +```bash +docker stop authy-api +docker rm authy-api +``` + +## Docker Compose + +Docker Compose provides a simple way to run Authy alongside its dependencies. + +> [!NOTE] +> This configuration assumes Interface API is running separately. Update `INTERFACE_API_URL` in your `.env` to point to the Interface API service. + +### Create docker-compose.yml + +Create a `docker-compose.yml` file in your project directory: + +```yaml +version: '3.8' + +services: + migrate: + build: . + container_name: authy-migrate + command: ./migrate -action=up + volumes: + - ./data:/app/data + - ./.env:/app/.env + + api: + build: . + container_name: authy-api + ports: + - "8080:8080" + volumes: + - ./data:/app/data + - ./.env:/app/.env + environment: + - HOST=0.0.0.0 + - PORT=8080 + depends_on: + - migrate + restart: unless-stopped +``` + +### Start all services + +```bash +docker compose up -d +``` + +This will start: + +- Database migrations +- API server + +### View logs + +```bash +# All services +docker compose logs -f + +# API server logs +docker compose logs -f api +``` + +### Access services + +- **API**: +- **Swagger docs**: +- **Demo UI**: + +### Stop services + +```bash +# Stop all services +docker compose down + +# Stop and remove volumes +docker compose down -v +``` + +### Rebuild after changes + +```bash +docker compose up -d --build +``` + +## Systemd service + +For production Linux deployments, running Authy as a systemd service provides automatic startup, restart on failure, and integration with system logging. + +### Manual setup + +#### 1. Build the binary + +```bash +make build +``` + +The `make build` command automatically detects the `DISABLE_DB_ENCRYPTION` setting in `.env` and uses the appropriate SQLite driver (SQLCipher or standard SQLite). + +#### 2. Create installation directory + +```bash +sudo mkdir -p /opt/authy-api +sudo cp -r bin migrations default.env .env /opt/authy-api/ +sudo mkdir -p /opt/authy-api/data +``` + +#### 3. Create dedicated user + +```bash +sudo useradd --system --user-group shortmesh +sudo chown -R shortmesh:shortmesh /opt/authy-api +``` + +#### 4. Install systemd service + +Create `/etc/systemd/system/authy-api.service` or copy from repository: + +```bash +sudo cp authy-api.service /etc/systemd/system/ +sudo systemctl daemon-reload +``` + +The service file should contain: + +```ini +[Unit] +Description=ShortMesh Authy API +After=network.target + +[Service] +Type=simple +User=shortmesh +Group=shortmesh +WorkingDirectory=/opt/authy-api +ExecStart=/opt/authy-api/bin/authy-api +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +#### 5. Enable and start + +```bash +sudo systemctl enable authy-api +sudo systemctl start authy-api +``` + +### Managing the service + +Once installed, manage the service with standard systemd commands: + +```bash +# Start the service +sudo systemctl start authy-api + +# Stop the service +sudo systemctl stop authy-api + +# Restart the service +sudo systemctl restart authy-api + +# View status +sudo systemctl status authy-api + +# View logs +sudo journalctl -u authy-api -f + +# View logs since last boot +sudo journalctl -u authy-api -b + +# Enable auto-start on boot +sudo systemctl enable authy-api + +# Disable auto-start +sudo systemctl disable authy-api +``` + +## Configuration reference + +This section provides a complete reference for all configuration options available in the `.env` file. + +### Server configuration + +```bash +# Application mode: development or production +# Production mode enforces HTTPS and stricter security +APP_MODE=development + +# Host address to bind to +# Use 127.0.0.1 for localhost only, 0.0.0.0 for all interfaces +HOST=127.0.0.1 + +# Port to listen on +PORT=8080 + +# Logging level: debug, info, warn, error +LOG_LEVEL=info +``` + +### TLS/HTTPS configuration + +When running in production mode (`APP_MODE=production`), HTTPS is enforced. Configure TLS certificates: + +```bash +# Path to TLS certificate file (PEM format) +TLS_CERT_FILE=/path/to/cert.pem + +# Path to TLS private key file (PEM format) +TLS_KEY_FILE=/path/to/key.pem +``` + +To generate self-signed certificates for testing: + +```bash +openssl req -x509 -newkey rsa:4096 \ + -keyout key.pem -out cert.pem \ + -days 365 -nodes +``` + +### Security overrides + +These options allow you to relax security constraints. Use with caution in production: + +```bash +# Allow HTTP in production (for use behind a reverse proxy with TLS termination) +ALLOW_INSECURE_SERVER=false + +# Allow HTTP for external services in production +ALLOW_INSECURE_EXTERNAL=false +``` + +### Database configuration + +```bash +# Path to SQLite database file +SQLITE_DB_PATH=./data/authy.db + +# Database encryption with SQLCipher +# Set to false to enable encryption (requires SQLCipher) +DISABLE_DB_ENCRYPTION=true + +# Encryption key (64-character hexadecimal string) +# Required when DISABLE_DB_ENCRYPTION=false +# Generate with: openssl rand -hex 32 +DB_ENCRYPTION_KEY= + +# Automatically run migrations on startup +# IMPORTANT: Set to false in production and run migrations manually +AUTO_MIGRATE=true +``` + +### Cryptographic keys + +> [!WARNING] +> Never change these keys after initial setup. Changing them will invalidate all existing data. These are automatically generated by `make setup`. + +```bash +# Database encryption key (hexadecimal, 32 bytes) +# Generate with: openssl rand -hex 32 +DB_ENCRYPTION_KEY= +``` + +### Interface API configuration + +Configuration for connecting to the Interface API service: + +```bash +# Interface API service URL +INTERFACE_API_URL=http://localhost:8082 + +# Token for authenticating with Interface API +# Obtain from Interface API after creating a token +INTERFACE_API_TOKEN=mt_xxxxx +``` + +To obtain an Interface API token, see the [Interface API documentation](./interface-api.md#creating-your-first-token). + +## Database migrations + +Authy uses migrations to manage database schema changes. Migrations ensure your database structure is up to date with the codebase. + +### Running migrations + +For development with automatic migrations enabled (`AUTO_MIGRATE=true`), migrations run automatically when the server starts. For production or manual control, use these commands: + +```bash +# Apply all pending migrations +make migrate-up + +# Check migration status +make migrate-status + +# Rollback the last migration +make migrate-down +``` + +### Manual migration commands + +You can also run the migration tool directly: + +```bash +# Apply all pending migrations +go run cmd/migrate/main.go -action=up + +# Rollback last migration +go run cmd/migrate/main.go -action=down -steps=1 + +# Show migration status +go run cmd/migrate/main.go -action=status +``` + +### Production migration workflow + +**For production environments:** + +1. Always set `AUTO_MIGRATE=false` in your `.env` file +2. Back up your database before running migrations +3. Run migrations during scheduled maintenance windows +4. Test migrations on a staging environment first +5. Verify migration success before restarting services + +Example workflow: + +```bash +# 1. Backup the database +cp data/authy.db data/authy.db.$(date +%Y%m%d_%H%M%S).backup + +# 2. Check what migrations will be applied +make migrate-status + +# 3. Run migrations +make migrate-up + +# 4. Verify success +make migrate-status + +# 5. If successful, restart the API server +sudo systemctl restart authy-api +``` + +For more details, see the [Migration Guide](https://github.com/shortmesh/Authy-API/blob/main/docs/MIGRATIONS.md). + +## Using the API + +Once Authy is running, you can interact with it using HTTP requests. See the [API Usage Guide](https://github.com/shortmesh/Authy-API/blob/main/docs/USAGE.md) + +### API documentation + +The Authy API provides interactive API documentation through Swagger UI. Access it at: + +``` +http://localhost:8080/docs/index.html +``` + +The Swagger UI allows you to: + +- Browse all available endpoints +- View request and response schemas +- Test API calls directly from your browser +- See example payloads + +To regenerate the Swagger documentation after code changes: + +```bash +make docs +``` + +## Demo UI + +Authy includes a live demo UI that lets visitors test the complete OTP flow interactively. + +### Accessing the demo + +The demo UI is available at: + +``` +http://localhost:8080/demo +``` + +### Building the demo + +The demo UI is a Vite-based React application located in `pkg/web/`. To build and serve it: + +```bash +# Build the demo UI +cd pkg/web +make build + +# Build the API server (embeds the UI) +cd ../.. +make build +``` + +The demo UI is automatically embedded into the API binary and served at `/demo`. + +## Security considerations + +### Key management + +**Never** share or commit these sensitive values to version control: + +- `DB_ENCRYPTION_KEY` +- `INTERFACE_API_TOKEN` + +**Never** change the `DB_ENCRYPTION_KEY` after initial deployment as it will make the database unreadable. + +### Reverse proxy configuration + +Example Nginx configuration with TLS: + +```nginx +server { + listen 443 ssl http2; + server_name authy.example.com; + + ssl_certificate /etc/letsencrypt/live/authy.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/authy.example.com/privkey.pem; + + location / { + proxy_pass http://127.0.0.1:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +For more security guidance, see the [Security Documentation](https://github.com/shortmesh/Authy-API/blob/main/docs/SECURITY.md). + +## Additional resources + +- [API Usage Guide](https://github.com/shortmesh/Authy-API/blob/main/docs/USAGE.md) - Comprehensive API reference with examples +- [Security & Configuration](https://github.com/shortmesh/Authy-API/blob/main/docs/SECURITY.md) - Security best practices +- [Migration Guide](https://github.com/shortmesh/Authy-API/blob/main/docs/MIGRATIONS.md) - Database migration details diff --git a/src/setup/builds.md b/src/setup/builds.md new file mode 100644 index 0000000..cca59c5 --- /dev/null +++ b/src/setup/builds.md @@ -0,0 +1,630 @@ +# 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 + +```bash +# 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: + +```bash +brew install --cask docker +``` + +Or download from [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/). + +For detailed installation guides, see the [Docker Installation Documentation](https://docs.docker.com/engine/install/). + +### 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](https://element-hq.github.io/synapse/latest/index.html) 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](./client.md#matrix-bridges) 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 + +```bash +git clone https://github.com/shortmesh/Builds.git +cd Builds +``` + +### Run complete setup + +The setup script will interactively guide you through configuring all services: + +```bash +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 + +```bash +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 + +```bash +# 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: + +```bash +# Check service health +make health + +# View resource usage +make stats +``` + +Access the services: + +- **Interface API**: +- **Interface API Admin**: +- **Interface API Docs**: +- **Authy API**: +- **Authy API Docs**: +- **Authy Demo**: + +## 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: + +```bash +# 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: + +```bash +# 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](./client.md) 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](./interface-api.md) 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](./authy.md) for detailed configuration options. + +## Managing services + +Use the Makefile commands to manage the stack lifecycle. + +### Starting and stopping + +```bash +# 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 + +```bash +# 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 + +```bash +# 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: + +```bash +# Interface API migrations +make migrate-interface + +# Authy API migrations +make migrate-authy +``` + +### Debugging + +Access shell in running containers: + +```bash +# 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: + +```bash +make fetch-defaults +``` + +### Resetting configurations + +Remove all generated configuration files: + +```bash +# 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: + +```bash +make setup +``` + +### Updating configurations + +After modifying service configurations, restart the affected services: + +```bash +# 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: + +```bash +# 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: + +```bash +ENABLE_DB_ENCRYPTION=true +``` + +This build argument is passed to all services during the build process. + +### Rebuild after enabling + +Encryption requires rebuilding all images: + +```bash +make rebuild +``` + +### Service configuration + +After enabling encryption and rebuilding, ensure each service's `.env` has: + +```bash +DISABLE_DB_ENCRYPTION=false +DB_ENCRYPTION_KEY=<64-char-hex-key> +``` + +Keys are automatically generated by `make setup`. + +## Maintenance + +### Health checks + +Check service status: + +```bash +# Quick health check +make health + +# Docker Compose status +docker compose ps + +# Detailed service info +docker compose ps --format json +``` + +### Resource monitoring + +View resource usage: + +```bash +# Resource stats +make stats + +# Docker stats +docker stats +``` + +### Backup + +Backup service configurations: + +```bash +make backup +``` + +This creates a timestamped backup of all configuration files. + +### Cleanup + +Remove stopped containers and unused resources: + +```bash +# Remove stopped containers +make clean + +# Remove all containers and volumes (DESTRUCTIVE) +docker compose down -v +``` + +### Validation + +Validate the Docker Compose configuration: + +```bash +make validate +``` + +## Troubleshooting + +### Common issues + +**Service fails to start**: Check logs for the specific service: + +```bash +make logs-interface +docker compose logs interface-api +``` + +**Database locked**: Ensure only one instance of the service is running: + +```bash +docker compose ps +docker compose down +make up +``` + +**Port already in use**: Check if another service is using the same port: + +```bash +sudo lsof -i :8082 +sudo lsof -i :8083 +``` + +**Migration failed**: Run migrations manually: + +```bash +make migrate-interface +make migrate-authy +``` + +### Resetting everything + +If you encounter persistent issues, reset the entire stack: + +```bash +# 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`): + +```bash +LOG_LEVEL=debug +``` + +**Authy API** (`config/authy-api/.env`): + +```bash +LOG_LEVEL=debug +``` + +Then restart the service: + +```bash +make restart-interface +make restart-authy +``` + +## Makefile reference + +Complete list of available commands: + +### Setup commands + +```bash +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 + +```bash +make up # Start all services +make down # Stop all services +make restart # Restart all services +make restart-shortmesh # Restart ShortMesh services only +``` + +### Logging commands + +```bash +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 + +```bash +make migrate-interface # Run Interface migrations +make migrate-authy # Run Authy migrations +``` + +### Build commands + +```bash +make build # Build all images +make rebuild # Rebuild and restart +make rebuild-shortmesh # Rebuild ShortMesh only +make pull # Pull latest images +``` + +### Debug commands + +```bash +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 + +```bash +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 + +```bash +make help # Show all available commands +``` + +## Additional resources + +- [Configuration Guide](https://github.com/shortmesh/Builds/blob/main/CONFIGURATION.md) - Detailed configuration reference +- [Client Setup](./client.md) - Matrix Client setup guide +- [Interface API Setup](./interface-api.md) - Interface API setup guide +- [Authy Setup](./authy.md) - Authy API setup guide +- [Docker Documentation](https://docs.docker.com/) - Official Docker documentation +- [Docker Compose Documentation](https://docs.docker.com/compose/) - Docker Compose reference diff --git a/src/setup/client.md b/src/setup/client.md new file mode 100644 index 0000000..a4fcb61 --- /dev/null +++ b/src/setup/client.md @@ -0,0 +1,696 @@ +# Client + +The Matrix Client is a bridge service that provides messaging capabilities across multiple Matrix bridges (WhatsApp, Telegram, Signal, etc.). It acts as a bridge between the Interface API and the Matrix homeserver. + +## Prerequisites + +Before installing the Client, you'll need to ensure you have the required dependencies and external services. + +### System requirements + +The Client requires: + +- **Go 1.24.0 or higher** - The Go programming language runtime and compiler +- **libolm** - Cryptographic library for Matrix end-to-end encryption +- **RabbitMQ** - Message broker for background workers +- **Swagger** - API documentation tool + +### Installing dependencies + +#### Debian/Ubuntu + +Install the required system dependencies: + +```bash +sudo apt-get update +sudo apt-get install -y \ + golang-1.24 \ + libolm-dev \ + build-essential +``` + +If your distribution doesn't have Go 1.24 in the default repositories, download it from [go.dev/dl](https://go.dev/dl/): + +```bash +wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz +sudo rm -rf /usr/local/go +sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz +export PATH=$PATH:/usr/local/go/bin +``` + +Install Swagger: + +```bash +go install github.com/swaggo/swag/cmd/swag@latest +go get github.com/swaggo/http-swagger +go get github.com/swaggo/files +export PATH=$PATH:$(go env GOPATH)/bin +``` + +#### macOS + +For macOS (especially M-series): + +```bash +brew install libolm +export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH" +export CPATH="/opt/homebrew/include:$CPATH" +export CGO_CFLAGS="-I/opt/homebrew/include" +export CGO_LDFLAGS="-L/opt/homebrew/lib" +``` + +Install RabbitMQ: + +- For detailed RabbitMQ installation instructions, see the [RabbitMQ Installation Guide](https://www.rabbitmq.com/download.html). + +### External services + +The Client requires the following external services to be running: + +#### Matrix Homeserver + +A running Matrix homeserver (e.g., Synapse) is required. See the [Synapse setup guide](https://element-hq.github.io/synapse/latest/index.html) for instructions on setting up a Matrix homeserver. + +#### Matrix Authentication Service (MAS) + +MAS provides OAuth2/OIDC authentication for Matrix. You must configure and run MAS before starting the Client. See the [Matrix Client MAS setup guide](https://github.com/shortmesh/Client#mas) for detailed instructions. + +#### Matrix Bridges + +Configure the bridges you want to support on your homeserver. Supported bridges include: + +- WhatsApp (mautrix-whatsapp) +- Telegram (mautrix-telegram) +- Signal (mautrix-signal) +- Instagram (mautrix-instagram) +- iMessage (mautrix-imessage) +- Facebook (mautrix-facebook) + +> [!IMPORTANT] +> Configure self-signing in each bridge to avoid encryption errors: +> +>```yaml +> # bridge.conf file +> encryption: +> self_sign: true +> ``` +> +> For Signal bridge, ensure your homeserver is configured to put phone numbers in topic: +> +> ```yaml +> network: +> in_topics: true +> ``` + +## Quick setup + +The quickest way to get started is to clone the repository and configure the service manually. + +### Clone the repository + +```bash +git clone https://github.com/shortmesh/Client.git +cd Client +``` + +### Create configuration + +Create your configuration file from the example: + +```bash +cp conf.yaml.example conf.yaml +``` + +### Configure settings + +Edit `conf.yaml` with your Matrix homeserver and MAS credentials: + +```yaml +# Matrix homeserver URL +homeserver: https://matrix.example.com + +# Matrix homeserver domain +homeserver_domain: example.com + +# MAS OAuth credentials +mas_client_id: your-mas-client-id +mas_client_secret: your-mas-client-secret + +# Database encryption key (high entropy string) +# Generate with: openssl rand -hex 32 +db_key: your-64-char-hex-key + +# RabbitMQ connection +rabbitmq_url: amqp://guest:guest@localhost:5672/ + +# API configuration +api: + host: 0.0.0.0 + port: 8080 +``` + +The client will create rooms and synchronize for your users for every bridge configured in `conf.yaml`. + +### Generate Swagger documentation + +```bash +swag init +``` + +### Install Go dependencies + +```bash +go mod tidy +``` + +### Start the server + +```bash +go run . +``` + +The server will start and listen on `http://localhost:8080`. + +### Verify the installation + +Once running, verify everything is working: + +```bash +# View Swagger documentation in browser +open http://localhost:8080/docs/index.html +``` + +## Docker + +Docker provides an isolated environment and simplifies dependency management. + +### Prerequisites + +Ensure you have Docker installed: + +```bash +# Verify Docker installation +docker --version +``` + +### Create configuration + +Before building the Docker image, you need a `conf.yaml` file: + +```bash +cp conf.yaml.example conf.yaml +# Edit conf.yaml with your configuration +``` + +### Build the image + +Build the Docker image: + +```bash +docker build -t matrix-client . +``` + +### Run the container + +Start the client service: + +```bash +docker run -d \ + --name matrix-client \ + -p 8080:8080 \ + -v $(pwd)/db:/app/db \ + -v $(pwd)/downloads:/app/downloads \ + -v $(pwd)/conf.yaml:/app/conf.yaml \ + matrix-client +``` + +### View logs + +```bash +docker logs -f matrix-client +``` + +### Stop the container + +```bash +docker stop matrix-client +docker rm matrix-client +``` + +## Docker Compose + +Docker Compose orchestrates the Client with RabbitMQ. This is the recommended approach for production deployments. + +### Create docker-compose.yml + +Create a `docker-compose.yml` file in your project directory: + +```yaml +version: '3.8' + +services: + rabbitmq: + image: rabbitmq:3-management-alpine + container_name: matrix-rabbitmq + ports: + - "5672:5672" + - "15672:15672" + environment: + RABBITMQ_DEFAULT_USER: guest + RABBITMQ_DEFAULT_PASS: guest + volumes: + - rabbitmq_data:/var/lib/rabbitmq + restart: unless-stopped + + matrix-client: + build: . + container_name: matrix-client + ports: + - "8080:8080" + volumes: + - ./db:/app/db + - ./downloads:/app/downloads + - ./conf.yaml:/app/conf.yaml + environment: + - HOST=0.0.0.0 + - PORT=8080 + depends_on: + - rabbitmq + restart: unless-stopped + +volumes: + rabbitmq_data: +``` + +### Start all services + +```bash +docker compose up -d +``` + +This will start: + +- RabbitMQ message broker with management UI +- Matrix Client service + +### View logs + +```bash +# All services +docker compose logs -f + +# Client logs only +docker compose logs -f matrix-client +``` + +### Access services + +- **Client API**: +- **Swagger docs**: +- **RabbitMQ Management**: (guest/guest) + +### Stop services + +```bash +# Stop all services +docker compose down + +# Stop and remove volumes +docker compose down -v +``` + +### Rebuild after changes + +```bash +docker compose up -d --build +``` + +## Systemd service + +For production Linux deployments, running the Client as a systemd service provides automatic startup, restart on failure, and integration with system logging. + +### Create service file + +Create `/etc/systemd/system/matrix-client.service`: + +```ini +[Unit] +Description=ShortMesh Matrix Client +After=network.target rabbitmq-server.service +Wants=rabbitmq-server.service + +[Service] +Type=simple +User=shortmesh +Group=shortmesh +WorkingDirectory=/opt/matrix-client +ExecStart=/opt/matrix-client/matrix-client +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +### Manual setup + +#### 1. Build the binary + +```bash +go build -o matrix-client . +``` + +#### 2. Create installation directory + +```bash +sudo mkdir -p /opt/matrix-client +sudo cp matrix-client conf.yaml /opt/matrix-client/ +sudo mkdir -p /opt/matrix-client/db +sudo mkdir -p /opt/matrix-client/downloads +``` + +#### 3. Create dedicated user + +```bash +sudo useradd --system --user-group shortmesh +sudo chown -R shortmesh:shortmesh /opt/matrix-client +``` + +#### 4. Install systemd service + +```bash +sudo cp matrix-client.service /etc/systemd/system/ +sudo systemctl daemon-reload +``` + +#### 5. Enable and start + +```bash +sudo systemctl enable matrix-client +sudo systemctl start matrix-client +``` + +### Managing the service + +Once installed, manage the service with standard systemd commands: + +```bash +# Start the service +sudo systemctl start matrix-client + +# Stop the service +sudo systemctl stop matrix-client + +# Restart the service +sudo systemctl restart matrix-client + +# View status +sudo systemctl status matrix-client + +# View logs +sudo journalctl -u matrix-client -f + +# View logs since last boot +sudo journalctl -u matrix-client -b + +# Enable auto-start on boot +sudo systemctl enable matrix-client + +# Disable auto-start +sudo systemctl disable matrix-client +``` + +## Configuration reference + +This section provides a complete reference for all configuration options available in the `conf.yaml` file. + +### Server configuration + +```yaml +# Matrix homeserver URL +homeserver: https://matrix.example.com + +# Matrix homeserver domain +homeserver_domain: example.com + +# API server configuration +api: + host: 0.0.0.0 + port: 8080 +``` + +### Authentication + +```yaml +# MAS OAuth credentials +mas_client_id: your-mas-client-id +mas_client_secret: your-mas-client-secret +``` + +### Database + +```yaml +# Database encryption key (high entropy string) +# Generate with: openssl rand -hex 32 +# IMPORTANT: Never change this key after initial setup +db_key: your-64-char-hex-key +``` + +### RabbitMQ + +```yaml +# RabbitMQ connection URL +rabbitmq_url: amqp://guest:guest@localhost:5672/ +``` + +For production, use authenticated connections: + +```yaml +rabbitmq_url: amqp://username:password@rabbitmq-host:5672/ +``` + +### Bridges + +Configure the bridges supported by your homeserver: + +## Message queues + +The Client uses RabbitMQ for message routing and device management. + +### Adding devices queue + +Incoming requests for adding devices are routed to: + +```yaml +exchange: "bridges.topic" +binding_key: "bridges.topic.add_new_device" +queue_name: {username}_add_new_device +``` + +### Incoming messages queue + +Incoming messages from bridges are routed to: + +```yaml +exchange: "contacts.topic" +binding_key: "contacts.topic.incoming_messages" +queue_name: {username}_incoming_messages +``` + +### Message payload structure + +Text and media messages follow this structure: + +```json +{ + "IsContact": true, + "Type": "text", + "From": "+1234567890", + "To": "+0987654321", + "Text": "Message content", + "Media": { + "Content": "base64_encoded_bytes", + "Info": { + "Size": 1024.5, + "MimeType": "image/jpeg", + "Width": 1920, + "Height": 1080, + "BlurHash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH" + } + } +} +``` + +## API documentation + +The Client provides interactive API documentation through Swagger UI. Access it at: + +``` +http://localhost:8080/docs/index.html +``` + +The Swagger UI allows you to: + +- Browse all available endpoints +- View request and response schemas +- Test API calls directly from your browser +- See example payloads + +To regenerate the Swagger documentation after code changes: + +```bash +swag init +``` + +## Reverse proxy configuration + +For production deployments, use a reverse proxy like Nginx to handle TLS termination and route requests. + +### Nginx configuration with MAS + +Example Nginx configuration that routes both MAS and Synapse: + +```nginx +server { + listen 443 ssl http2; + server_name matrix.example.com; + + ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem; + + client_max_body_size 50M; + + # IMPORTANT: MAS SHOULD COME BEFORE SYNAPSE FOR REGEX NGINX REASONS + + # MAS-backed client auth routes + location ~ ^/_matrix/client/(v3|v1)/(login|logout|refresh|auth_metadata|capabilities) { + proxy_pass http://127.0.0.1:8080; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + } + + # Synapse endpoints + location ~ ^(/_matrix|/_synapse/client|/_synapse/mas) { + proxy_pass http://127.0.0.1:8008; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + } + + # .well-known + location /.well-known/matrix/ { + alias /var/www/matrix/.well-known/matrix/; + default_type application/json; + add_header Access-Control-Allow-Origin *; + } +} +``` + +### .well-known/matrix/client + +```json +{ + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "org.matrix.msc2965.authentication": { + "issuer": "https://auth.example.com/", + "account": "https://auth.example.com/account/" + } +} +``` + +## Matrix Authentication Service (MAS) + +MAS is required for OAuth2/OIDC authentication with Matrix. + +### Docker setup + +Example Docker Compose configuration for MAS: + +```yaml +services: + matrix-auth-service: + image: ghcr.io/element-hq/matrix-authentication-service:latest + container_name: matrix-auth-service + environment: + - MAS_CONFIG=/app/config/config.yaml + ports: + - "8080:8080" + - "8081:8081" # health endpoint + volumes: + - ./config.yaml:/app/config/config.yaml:ro + restart: unless-stopped + network_mode: "host" +``` + +### MAS configuration + +Example `config.yaml` for MAS: + +```yaml +http: + listeners: + - name: web + resources: + - name: discovery + - name: human + - name: oauth + - name: compat + - name: graphql + - name: assets + binds: + - host: 0.0.0.0 + port: 8080 + proxy_protocol: false + - name: internal + resources: + - name: health + binds: + - host: localhost + port: 8081 + proxy_protocol: false + trusted_proxies: + - 192.168.0.0/16 + - 172.16.0.0/12 + - 10.0.0.0/10 + - 127.0.0.1/8 + - fd00::/8 + - ::1/128 + public_base: https://auth.example.com/ + issuer: https://auth.example.com/ + +matrix: + kind: synapse + homeserver: matrix.example.com + endpoint: https://matrix.example.com/ + secret: your-shared-secret-from-synapse-config + +account: + password_registration_enabled: true + password_recovery_enabled: true + account_deactivation_allowed: true + login_with_email_allowed: true +``` + +For detailed MAS setup instructions, see [this guide](https://willlewis.co.uk/blog/posts/stronger-matrix-auth-mas-synapse-docker-compose/). + +## Security considerations + +### Key management + +**Never** share or commit these sensitive values to version control: + +- `db_key` +- `mas_client_secret` + +**Never** change the `db_key` after initial deployment as it will make the database unreadable. + +## Additional resources + +- [Client GitHub Repository](https://github.com/shortmesh/Client) +- [MAS Setup Guide](https://willlewis.co.uk/blog/posts/stronger-matrix-auth-mas-synapse-docker-compose/) +- [Matrix Bridges](https://docs.mau.fi/bridges/) diff --git a/src/setup/interface-api.md b/src/setup/interface-api.md new file mode 100644 index 0000000..f344f8b --- /dev/null +++ b/src/setup/interface-api.md @@ -0,0 +1,830 @@ +# Interface API + +The Interface API is the primary service for user interaction in the Shortmesh ecosystem. It provides a RESTful interface for managing authentication tokens, devices, messaging, and webhooks. + +## Prerequisites + +Before installing the Interface API, you'll need to ensure you have the required dependencies and external services. + +### System requirements + +The Interface API requires: + +- **Go 1.24.0 or higher** - The Go programming language runtime and compiler +- **SQLite** - Lightweight database (usually pre-installed on most systems) +- **RabbitMQ** - Message broker for background workers + +Optional but recommended: + +- **SQLCipher** - For encrypted database support + +### Installing dependencies + +#### Debian/Ubuntu + +Install the required system dependencies: + +```bash +sudo apt-get update +sudo apt-get install -y \ + golang-1.24 \ + libsqlite3-dev \ + libsqlcipher-dev \ + build-essential +``` + +If your distribution doesn't have Go 1.24 in the default repositories, download it from [go.dev/dl](https://go.dev/dl/): + +```bash +wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz +sudo rm -rf /usr/local/go +sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz +export PATH=$PATH:/usr/local/go/bin +``` + +Install RabbitMQ: + +- For detailed RabbitMQ installation instructions, see the [RabbitMQ Installation Guide](https://www.rabbitmq.com/download.html). + +### External services + +The Interface API requires two external Shortmesh services to be running: + +#### Matrix Authentication Service (MAS) + +MAS provides OAuth2/OIDC authentication for Matrix. You must configure and run MAS before starting the Interface API. See the [Matrix Client MAS setup guide](https://github.com/shortmesh/Client#mas) for detailed instructions. + +#### Matrix Client + +The Matrix Client service acts as a bridge between the Interface API and the Matrix homeserver. It handles device management, message sending, and webhook delivery. Refer to the [Matrix Client documentation](https://github.com/shortmesh/Client#requirements) for setup instructions. + +## Quick setup + +The quickest way to get started is to use the automated setup script. This method is ideal for development and testing. + +### Clone the repository + +```bash +git clone https://github.com/shortmesh/Interface-API.git +cd Interface-API +``` + +### Generate configuration + +The setup script automatically creates a `.env` file with cryptographically secure keys: + +```bash +make setup +``` + +This creates a `.env` file with auto-generated values for `HASH_KEY`, `DB_ENCRYPTION_KEY`, `CLIENT_ID`, and `CLIENT_SECRET`. + +Alternatively, create the file manually: + +```bash +cp example.env .env +``` + +Then edit `.env` and generate the required keys: + +```bash +# Generate HASH_KEY (32 bytes base64) +openssl rand -base64 32 + +# Generate DB_ENCRYPTION_KEY (32 bytes hex, needed if encryption enabled) +openssl rand -hex 32 + +# Generate CLIENT_ID +openssl rand -hex 16 + +# Generate CLIENT_SECRET +openssl rand -hex 32 +``` + +### Configure environment variables + +Edit your `.env` file with the required settings: + +```bash +# Application mode: development or production +APP_MODE=development + +# Server settings +HOST=127.0.0.1 +PORT=8080 + +# Database configuration +SQLITE_DB_PATH=./data/shortmesh.db +DISABLE_DB_ENCRYPTION=false +DB_ENCRYPTION_KEY= + +# Auto-run migrations (disable in production) +AUTO_MIGRATE=true + +# External services (update with your values) +MAS_URL=https://mas.example.com +MAS_ADMIN_URL=https://mas.example.com/admin +ADMIN_CLIENT_ID=your-mas-admin-client-id +ADMIN_CLIENT_SECRET=your-mas-admin-client-secret +MATRIX_CLIENT_URL=http://localhost:3000 + +# RabbitMQ +RABBITMQ_URL=amqp://guest:guest@localhost:5672/ +``` + +For a complete reference of all configuration options, see [Configuration reference](#configuration-reference). + +### Initialize the database + +Run migrations to set up the database schema: + +```bash +make migrate-up +``` + +Check the migration status: + +```bash +make migrate-status +``` + +### Start the server + +```bash +make run +``` + +The server will start and listen on `http://localhost:8080`. The API server includes embedded background workers for message processing. + +### Verify the installation + +Once running, verify everything is working: + +```bash +# View Swagger documentation in browser +open http://localhost:8080/docs/index.html + +# Access admin dashboard +open http://localhost:8080/admin +``` + +The server provides: + +- **API**: +- **Swagger docs**: +- **Admin dashboard**: + +## Docker + +Docker provides an isolated environment and simplifies dependency management. This is suitable for both development and production deployments. + +### Prerequisites + +Ensure you have Docker installed: + +```bash +# Verify Docker installation +docker --version +``` + +### Create configuration + +Before building the Docker image, you need a `.env` file. You can create it locally: + +```bash +cp example.env .env +# Edit .env with your configuration +``` + +Or use the setup script: + +```bash +make setup +``` + +### Build the image + +Build the Docker image: + +```bash +docker build -t interface-api . +``` + +For encrypted database support with SQLCipher: + +```bash +docker build --build-arg ENABLE_DB_ENCRYPTION=true -t interface-api . +``` + +Then ensure your `.env` has: + +```bash +DISABLE_DB_ENCRYPTION=false +DB_ENCRYPTION_KEY= +``` + +### Run migrations + +If you've disabled automatic migrations (`AUTO_MIGRATE=false`), run them manually: + +```bash +docker run --rm \ + -v $(pwd)/data:/app/data \ + -v $(pwd)/.env:/app/.env \ + interface-api \ + ./migrate -action=up +``` + +### Run the container + +Start the API server: + +```bash +docker run -d \ + --name interface-api \ + -p 8080:8080 \ + -v $(pwd)/data:/app/data \ + -v $(pwd)/.env:/app/.env \ + interface-api +``` + +### View logs + +```bash +docker logs -f interface-api +``` + +### Stop the container + +```bash +docker stop interface-api +docker rm interface-api +``` + +## Docker Compose + +Docker Compose orchestrates all required services including RabbitMQ, and migrations. This is the recommended approach for production deployments. + +### Create docker-compose.yml + +Create a `docker-compose.yml` file in your project directory: + +```yaml +version: '3.8' + +services: + rabbitmq: + image: rabbitmq:3-management-alpine + container_name: shortmesh-rabbitmq + ports: + - "5672:5672" + - "15672:15672" + environment: + RABBITMQ_DEFAULT_USER: guest + RABBITMQ_DEFAULT_PASS: guest + volumes: + - rabbitmq_data:/var/lib/rabbitmq + restart: unless-stopped + + migrate: + build: . + container_name: shortmesh-migrate + command: ./migrate -action=up + volumes: + - ./data:/app/data + - ./.env:/app/.env + depends_on: + - rabbitmq + + api: + build: . + container_name: shortmesh-api + ports: + - "8080:8080" + volumes: + - ./data:/app/data + - ./.env:/app/.env + environment: + - HOST=0.0.0.0 + - PORT=8080 + - RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/ + depends_on: + - rabbitmq + - migrate + restart: unless-stopped + +volumes: + rabbitmq_data: +``` + +### Start all services + +```bash +docker compose up -d +``` + +This will start: + +- RabbitMQ message broker with management UI +- Database migrations +- API server (with embedded background workers) + +### View logs + +```bash +# All services +docker compose logs -f + +# API server logs +docker compose logs -f api +``` + +### Access services + +- **API**: +- **Swagger docs**: +- **Admin dashboard**: +- **RabbitMQ Management**: (guest/guest) + +### Stop services + +```bash +# Stop all services +docker compose down + +# Stop and remove volumes +docker compose down -v +``` + +### Rebuild after changes + +```bash +docker compose up -d --build +``` + +## Systemd service + +For production Linux deployments, running the Interface API as a systemd service provides automatic startup, restart on failure, and integration with system logging. + +### Automated setup + +The repository includes a setup script that handles the installation: + +```bash +sudo make setup-systemd +``` + +This script will: + +1. Create the `/opt/interface-api` directory +2. Build the binaries +3. Copy files to the installation directory +4. Install the systemd service unit + +### Manual setup + +If you prefer manual setup or need more control, follow these steps: + +#### 1. Build the binaries + +```bash +make build +``` + +#### 2. Create installation directory + +```bash +sudo mkdir -p /opt/interface-api +sudo cp -r bin migrations default.env .env /opt/interface-api/ +sudo mkdir -p /opt/interface-api/data +``` + +#### 3. Create dedicated user + +```bash +sudo useradd --system --user-group shortmesh +sudo chown -R shortmesh:shortmesh /opt/interface-api +``` + +#### 4. Install systemd service + +```bash +sudo cp interface-api.service /etc/systemd/system/ +sudo systemctl daemon-reload +``` + +#### 5. Enable and start + +```bash +sudo systemctl enable interface-api +sudo systemctl start interface-api +``` + +### Managing the service + +Once installed, manage the service with standard systemd commands: + +```bash +# Start the service +sudo systemctl start interface-api + +# Stop the service +sudo systemctl stop interface-api + +# Restart the service +sudo systemctl restart interface-api + +# View status +sudo systemctl status interface-api + +# View logs +sudo journalctl -u interface-api -f + +# View logs since last boot +sudo journalctl -u interface-api -b + +# Enable auto-start on boot +sudo systemctl enable interface-api + +# Disable auto-start +sudo systemctl disable interface-api +``` + +## Configuration reference + +This section provides a complete reference for all configuration options available in the `.env` file. + +### Server configuration + +```bash +# Application mode: development or production +# Production mode enforces HTTPS and stricter security +APP_MODE=development + +# Host address to bind to +# Use 127.0.0.1 for localhost only, 0.0.0.0 for all interfaces +HOST=127.0.0.1 + +# Port to listen on +PORT=8080 + +# Logging level: debug, info, warn, error +LOG_LEVEL=info +``` + +### TLS/HTTPS configuration + +When running in production mode (`APP_MODE=production`), HTTPS is enforced. Configure TLS certificates: + +```bash +# Path to TLS certificate file (PEM format) +TLS_CERT_FILE=/path/to/cert.pem + +# Path to TLS private key file (PEM format) +TLS_KEY_FILE=/path/to/key.pem +``` + +To generate self-signed certificates for testing: + +```bash +openssl req -x509 -newkey rsa:4096 \ + -keyout key.pem -out cert.pem \ + -days 365 -nodes +``` + +### Security overrides + +These options allow you to relax security constraints. Use with caution in production: + +```bash +# Allow HTTP in production (for use behind a reverse proxy with TLS termination) +ALLOW_INSECURE_SERVER=false + +# Allow HTTP/WebSocket for external services in production +ALLOW_INSECURE_EXTERNAL=false +``` + +### Database configuration + +```bash +# Path to SQLite database file +SQLITE_DB_PATH=./data/shortmesh.db + +# Database encryption with SQLCipher +# Set to false to enable encryption (requires SQLCipher) +DISABLE_DB_ENCRYPTION=true + +# Encryption key (64-character hexadecimal string) +# Required when DISABLE_DB_ENCRYPTION=false +# Generate with: openssl rand -hex 32 +DB_ENCRYPTION_KEY= + +# Automatically run migrations on startup +# IMPORTANT: Set to false in production and run migrations manually +AUTO_MIGRATE=true +``` + +### Cryptographic keys + +> [!WARNING] +> Never change these keys after initial setup. Changing them will invalidate all existing tokens and encrypted data. These are automatically generated by `make setup`. + +```bash +# HMAC key for signing tokens (base64 encoded, 32 bytes) +# Generate with: openssl rand -base64 32 +HASH_KEY= + +# Database encryption key (hexadecimal, 32 bytes) +# Generate with: openssl rand -hex 32 +DB_ENCRYPTION_KEY= +``` + +### API authentication + +Credentials for clients to authenticate with the API: + +```bash +# Client ID (hexadecimal string) +# Generate with: openssl rand -hex 16 +CLIENT_ID= + +# Client secret (hexadecimal string) +# Generate with: openssl rand -hex 32 +CLIENT_SECRET= +``` + +### External services + +Configuration for Matrix services: + +```bash +# Matrix Authentication Service public URL +MAS_URL=https://mas.example.com + +# Matrix Authentication Service admin API URL +MAS_ADMIN_URL=https://mas.example.com/admin + +# Admin credentials for MAS +ADMIN_CLIENT_ID=your-mas-admin-client-id +ADMIN_CLIENT_SECRET=your-mas-admin-client-secret + +# Matrix Client service URL +MATRIX_CLIENT_URL=http://localhost:3000 +``` + +### RabbitMQ configuration + +```bash +# RabbitMQ connection URL +RABBITMQ_URL=amqp://guest:guest@localhost:5672/ +``` + +For production, use authenticated connections: + +```bash +RABBITMQ_URL=amqp://username:password@rabbitmq-host:5672/ +``` + +### Worker configuration + +The `default.env` file contains worker and queue settings. These typically don't need modification: + +```bash +# Enable/disable message workers +WORKER_ENABLED=true +WORKER_COUNT=2 + +# Enable/disable webhook workers +WEBHOOK_WORKER_ENABLED=true +WEBHOOK_REFRESH_INTERVAL_SECONDS=30 + +# Enable/disable cleanup worker +CLEANUP_ENABLED=true +MATRIX_TOKEN_CLEANUP_INTERVAL_MINUTES=60 +``` + +## Database migrations + +The Interface API uses migrations to manage database schema changes. Migrations ensure your database structure is up to date with the codebase. + +### Running migrations + +For development with automatic migrations enabled (`AUTO_MIGRATE=true`), migrations run automatically when the server starts. For production or manual control, use these commands: + +```bash +# Apply all pending migrations +make migrate-up + +# Check migration status +make migrate-status + +# Rollback the last migration +make migrate-down +``` + +### Manual migration commands + +You can also run the migration tool directly: + +```bash +# Apply all pending migrations +go run cmd/migrate/main.go -action=up + +# Rollback last migration +go run cmd/migrate/main.go -action=down -steps=1 + +# Show migration status +go run cmd/migrate/main.go -action=status +``` + +### Production migration workflow + +**For production environments:** + +1. Always set `AUTO_MIGRATE=false` in your `.env` file +2. Back up your database before running migrations +3. Run migrations during scheduled maintenance windows +4. Test migrations on a staging environment first +5. Verify migration success before restarting services + +Example workflow: + +```bash +# 1. Backup the database +cp data/shortmesh.db data/shortmesh.db.$(date +%Y%m%d_%H%M%S).backup + +# 2. Check what migrations will be applied +make migrate-status + +# 3. Run migrations +make migrate-up + +# 4. Verify success +make migrate-status + +# 5. If successful, restart the API server +sudo systemctl restart interface-api +``` + +For more details, see the [Migration Guide](https://github.com/shortmesh/Interface-API/blob/main/docs/MIGRATIONS.md). + +## Using the API + +Once the Interface API is running, you can interact with it using HTTP requests. The API uses two authentication methods depending on the operation. + +### Authentication methods + +**Basic Authentication** is used for managing credentials and tokens: + +```bash +curl -u CLIENT_ID:CLIENT_SECRET http://localhost:8080/api/v1/tokens +``` + +**Bearer Authentication** is used for device and message operations: + +```bash +curl -H "Authorization: Bearer mt_xxxxx" http://localhost:8080/api/v1/devices +``` + +### Creating your first token + +The first token you create is automatically marked as an admin token and creates the host Matrix identity: + +```bash +# Extract credentials from .env +CLIENT_ID=$(grep '^CLIENT_ID=' .env | cut -d'=' -f2) +CLIENT_SECRET=$(grep '^CLIENT_SECRET=' .env | cut -d'=' -f2) + +# Create admin token +curl -X POST http://localhost:8080/api/v1/tokens \ + -u "$CLIENT_ID:$CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{"use_host": false}' +``` + +Response: + +```json +{ + "message": "Matrix token created successfully", + "token": "mt_abc123..." +} +``` + +Save the token value for subsequent requests. + +### Managing devices + +List available devices: + +```bash +curl http://localhost:8080/api/v1/devices \ + -H "Authorization: Bearer mt_xxxxx" +``` + +### API documentation + +The Interface API provides interactive API documentation through Swagger UI. Access it at: + +``` +http://localhost:8080/docs/index.html +``` + +The Swagger UI allows you to: + +- Browse all available endpoints +- View request and response schemas +- Test API calls directly from your browser +- See example payloads + +To regenerate the Swagger documentation after code changes: + +```bash +# Install swag tool (first time only) +go install github.com/swaggo/swag/cmd/swag@latest + +# Generate docs +make docs +``` + +For detailed API usage examples and workflows, see the [API Usage Guide](https://github.com/shortmesh/Interface-API/blob/main/docs/USAGE.md). + +## Admin dashboard + +The Interface API includes a web-based admin dashboard for managing tokens and devices through a graphical interface. + +Access the dashboard at: + +``` +http://localhost:8080/admin +``` + +Features include: + +- Token management (create, view, delete) +- Device monitoring and status +- Permission management + +For detailed admin UI documentation, see the [Admin UI Guide](https://github.com/shortmesh/Interface-API/blob/main/docs/ADMIN_UI.md). + +## Troubleshooting + +### Debug logging + +Enable debug logging for troubleshooting: + +```bash +# Set in .env +LOG_LEVEL=debug + +# Or run with debug logging +LOG_LEVEL=debug make run +``` + +## Security considerations + +### Key management + +**Never** share or commit these sensitive values to version control: + +- `HASH_KEY` +- `DB_ENCRYPTION_KEY` +- `CLIENT_SECRET` +- `ADMIN_CLIENT_SECRET` + +**Never** change these keys after initial deployment: + +- `HASH_KEY` - Will invalidate all existing tokens +- `DB_ENCRYPTION_KEY` - Will make the database unreadable + +### Reverse proxy configuration + +Example Nginx configuration with TLS: + +```nginx +server { + listen 443 ssl http2; + server_name api.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://127.0.0.1:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +For more security guidance, see the [Security Documentation](https://github.com/shortmesh/Interface-API/blob/main/docs/SECURITY.md). + +## Additional resources + +- [API Usage Guide](https://github.com/shortmesh/Interface-API/blob/main/docs/USAGE.md) - Comprehensive API reference with examples +- [Admin UI Management](https://github.com/shortmesh/Interface-API/blob/main/docs/ADMIN_UI.md) - Web dashboard documentation +- [Security & Configuration](https://github.com/shortmesh/Interface-API/blob/main/docs/SECURITY.md) - Security best practices +- [Migration Guide](https://github.com/shortmesh/Interface-API/blob/main/docs/MIGRATIONS.md) - Database migration details +- [Throttler Documentation](https://github.com/shortmesh/Interface-API/blob/main/docs/THROTTLER.md) - Rate limiting system From 255ab015eb7389272e66dee456a2827cad25bb55 Mon Sep 17 00:00:00 2001 From: Promise Fru Date: Fri, 22 May 2026 11:47:11 +0100 Subject: [PATCH 2/2] feat(ci): add live deployment workflow for main branch --- .github/workflows/deploy.live.yml | 57 +++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/deploy.live.yml diff --git a/.github/workflows/deploy.live.yml b/.github/workflows/deploy.live.yml new file mode 100644 index 0000000..4d0e821 --- /dev/null +++ b/.github/workflows/deploy.live.yml @@ -0,0 +1,57 @@ +name: Live Deployment Pipeline + +on: + push: + branches: + - main + +jobs: + build: + name: Build Application + runs-on: ubuntu-latest + environment: + name: live + url: https://docs.shortmesh.com + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v2 + with: + mdbook-version: "latest" + + - name: Build project + run: | + mdbook build + + - name: Securely Copy Artifacts to Server + uses: appleboy/scp-action@master + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USER }} + key: ${{ secrets.SSH_KEY }} + source: "book/*" + target: ${{ secrets.BUILD_PATH }} + strip_components: 1 + rm: false + + - name: Execute Remote SSH Commands + uses: appleboy/ssh-action@master + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USER }} + key: ${{ secrets.SSH_KEY }} + script: | + set -e + + echo "============================" + echo "🚀 Deploy Project ..." + echo "============================" + if ! ${{secrets.BUILD_CMD}}; then + echo "❌ Error deploying project!" + exit 1 + fi + echo "===============================" + echo "✅ Deployment complete" + echo "==============================="