Files

Andreas Dueren ef4d2c1072 Fix domain configuration and database cleanup for production deployment

- Fixed domain extraction logic in start.sh for proper homeserver configuration
- Updated registration file regex patterns to use base domain
- Added comprehensive database cleanup procedures in CLAUDE.md
- Updated CloudronManifest.json for production settings
- Resolved crypto sync issues and user registration conflicts

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-06-16 20:03:01 -06:00

3.4 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Cloudron package for the mautrix-whatsapp Matrix-WhatsApp bridge. It wraps the Go implementation of mautrix-whatsapp into a Cloudron-compatible app with automatic configuration, database setup, and health monitoring.

Build and Development Commands

Build the Docker image

make build

Package for Cloudron

make package

Custom Cloudron Build Service

cloudron build --set-build-service builder.docker.due.ren --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e --set-repository andreasdueren/matrix-whatsapp-bridge --tag [version]

Remote Installation

cloudron install --location whatsapp.matrix.due.ren --image andreasdueren/matrix-whatsapp-bridge:1.1.0

Development deployment

make dev-install    # Install on test Cloudron
make dev-update     # Update existing installation

Clean build artifacts

make clean

Architecture

Core Components

Dockerfile.cloudron: Multi-stage build using Go compiler with Cloudron base image
start.sh: Bootstrap script handling configuration generation and WhatsApp authentication setup
CloudronManifest.json: Defines PostgreSQL and localstorage addons, health check endpoint on port 29318

Configuration Flow

The start.sh script implements a streamlined configuration process:

Initial Setup: Generates config.yaml and registration.yaml using built-in mautrix-whatsapp templates
Environment Integration: Configures PostgreSQL connection and Cloudron domain settings using yq
Authentication Ready: Sets up for WhatsApp QR code authentication workflow

Key Design Patterns

Uses Go binary compiled during Docker build for optimal performance
All data persisted to /app/data with proper cloudron user ownership
Configuration via yq YAML manipulation for cleaner updates
Health check implemented using netcat since bridge doesn't provide native endpoint
PostgreSQL connection string automatically injected from Cloudron addon

Environment Integration

CLOUDRON_POSTGRESQL_URL: Database connection from PostgreSQL addon
CLOUDRON_APP_DOMAIN: Used to derive Matrix homeserver domain and appservice URL
Automatic domain extraction for homeserver configuration
Port 29318 for appservice and health check endpoints

Development Notes

Go Binary Management

The bridge binary is built during Docker image creation from the official mautrix-whatsapp repository. Version updates require updating the git clone in Dockerfile.cloudron.

Database Schema

Uses PostgreSQL addon for persistence. The bridge handles its own schema migrations via the mautrix-whatsapp package.

WhatsApp Authentication

Unlike Telegram bridges, WhatsApp authentication requires QR code scanning or pairing codes. The bridge provides interactive authentication commands after startup.

Health Monitoring

Custom health check endpoint created using netcat on port 29318 since the bridge doesn't provide native health endpoints.

Configuration Differences from Telegram Bridge

Go-based instead of Python (single binary deployment)
Simpler configuration workflow (no complex token synchronization)
WhatsApp Web protocol authentication instead of API tokens
Different port allocation (29318 vs 29317)

3.4 KiB Raw Blame History