Initial commit

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this Cloudron package will be documented in this file.
+
+## [1.0.0] - 2024-06-16
+
+### Added
+- Initial Cloudron package for mautrix-whatsapp bridge
+- Support for PostgreSQL database via Cloudron addon
+- Automatic configuration generation with Cloudron environment variables
+- Health check endpoint for Cloudron monitoring
+- QR code authentication workflow
+- Comprehensive documentation and setup instructions
+
+### Features
+- Matrix-WhatsApp bridge using mautrix-whatsapp v0.10.8
+- Two-way message bridging
+- Media file support (images, videos, documents, audio)
+- Group chat bridging
+- Reaction support
+- Read receipt synchronization
+- Typing indicator bridging
+- End-to-end encryption support in Matrix rooms
+
+### Configuration
+- Automatic homeserver domain detection from Cloudron environment
+- PostgreSQL connection string injection
+- Log file configuration
+- Registration file generation and management

CLAUDE.md

@@ -0,0 +1,77 @@
+# 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
+```bash
+make build
+```
+
+### Package for Cloudron
+```bash
+make package
+```
+
+### Development deployment
+```bash
+make dev-install    # Install on test Cloudron
+make dev-update     # Update existing installation
+```
+
+### Clean build artifacts
+```bash
+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:
+
+1. **Initial Setup**: Generates config.yaml and registration.yaml using built-in mautrix-whatsapp templates
+2. **Environment Integration**: Configures PostgreSQL connection and Cloudron domain settings using yq
+3. **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)

CloudronManifest.json

@@ -0,0 +1,31 @@
+{
+  "version": "1.0.0",
+  "upstreamVersion": "0.10.8",
+  "id": "dev.maunium.whatsapp.cloudronapp",
+  "title": "Matrix WhatsApp Bridge",
+  "author": "Tulir Asokan <tulir@maunium.net>",
+  "description": "file://DESCRIPTION.md",
+  "tagline": "Bridge between Matrix and WhatsApp",
+  "healthCheckPath": "/health",
+  "httpPort": 29318,
+  "icon": "logo.png",
+  "addons": {
+    "localstorage": {},
+    "postgresql": {}
+  },
+  "manifestVersion": 2,
+  "website": "https://docs.mau.fi/bridges/go/whatsapp/index.html",
+  "contactEmail": "support@cloudron.io",
+  "tags": [
+    "matrix",
+    "whatsapp",
+    "chat",
+    "bridge",
+    "communication"
+  ],
+  "minBoxVersion": "7.1.0",
+  "postInstallMessage": "Mautrix-WhatsApp bridge is installed!\n\nPlease note you will need to:\n1. Configure your homeserver by setting up the registration\n2. Configure the bridge in the data directory\n3. Authenticate with WhatsApp using QR code or pairing code\n\nVisit https://docs.mau.fi/bridges/go/whatsapp/index.html for detailed instructions.",
+  "changelog": "file://CHANGELOG.md",
+  "documentationUrl": "https://docs.mau.fi/bridges/go/whatsapp/index.html",
+  "forumUrl": "https://matrix.to/#/#whatsapp:maunium.net"
+}

DESCRIPTION.md

@@ -0,0 +1,31 @@
+A Matrix-WhatsApp bridge that allows you to chat with WhatsApp users from your Matrix client.
+
+## Features
+
+- **Two-way bridging**: Send and receive messages between Matrix and WhatsApp
+- **Media support**: Share images, videos, documents, and voice messages
+- **Group chats**: Bridge WhatsApp groups to Matrix rooms
+- **WhatsApp Web**: Uses WhatsApp Web protocol for reliable connectivity
+- **End-to-end encryption**: Supports Matrix E2EE in bridged rooms
+- **Reactions**: Bridge message reactions between platforms
+- **Read receipts**: Sync read status between Matrix and WhatsApp
+- **Typing indicators**: Show when users are typing
+- **Contact sync**: Automatically create Matrix rooms for WhatsApp contacts
+
+## Requirements
+
+- Matrix homeserver with application service support
+- WhatsApp account with phone number
+- PostgreSQL database (provided by Cloudron)
+
+## Authentication
+
+The bridge uses WhatsApp Web's authentication system. You'll need to:
+
+1. Start the bridge and send `login` to the bridge bot
+2. Scan the QR code with WhatsApp on your phone
+3. The bridge will maintain the connection automatically
+
+## Support
+
+For help and discussion, join the Matrix room: [#whatsapp:maunium.net](https://matrix.to/#/#whatsapp:maunium.net)

Dockerfile.cloudron

@@ -0,0 +1,40 @@
+FROM cloudron/base:5.0.0@sha256:04fd70dbd8ad6149c19de39e35718e024417c3e01dc9c6637eaf4a41ec4e596c
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    ca-certificates \
+    netcat-openbsd \
+    bash \
+    jq \
+    yq \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Go
+ENV GO_VERSION=1.21.4
+RUN curl -LO https://golang.org/dl/go${GO_VERSION}.linux-amd64.tar.gz \
+    && tar -C /usr/local -xzf go${GO_VERSION}.linux-amd64.tar.gz \
+    && rm go${GO_VERSION}.linux-amd64.tar.gz
+ENV PATH="/usr/local/go/bin:$PATH"
+
+# Create app directories
+RUN mkdir -p /app/code /app/pkg /app/data
+WORKDIR /app/code
+
+# Download and build mautrix-whatsapp
+RUN git clone https://github.com/mautrix/whatsapp.git . \
+    && go build -o /app/pkg/mautrix-whatsapp
+
+# Copy startup script
+COPY start.sh /app/pkg/
+
+# Set volumes and environment
+VOLUME /app/data
+ENV UID=1337 GID=1337
+
+# Add health check endpoint
+HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
+    CMD curl -f http://localhost:29318/health || exit 1
+
+CMD ["/app/pkg/start.sh"]

Makefile

@@ -0,0 +1,39 @@
+.PHONY: build clean package
+
+# Repository details - change as needed
+CLOUDRON_APP_ID = dev.maunium.whatsapp.cloudronapp
+CLOUDRON_TOKEN ?=
+
+# For development, we'll use the current git commit as the version
+GIT_COMMIT = $(shell git rev-parse --short HEAD 2>/dev/null || echo "dev")
+VERSION ?= dev-$(GIT_COMMIT)
+
+# Docker image for cloudron package building
+CLOUDRON_BUILDER_IMAGE = cloudron/package-builder:5.0.0
+
+all: build
+
+build:
+	docker build -t $(CLOUDRON_APP_ID) -f Dockerfile.cloudron .
+
+# Clean build artifacts
+clean:
+	rm -rf build.log latest.tgz
+
+# Package for Cloudron in a consistent environment
+package:
+	@mkdir -p build
+	docker run --rm -v "$(PWD):/app" $(CLOUDRON_BUILDER_IMAGE) build --set-version $(VERSION)
+
+# For development - install directly in a test Cloudron
+dev-install: package
+	cloudron install --image $(CLOUDRON_APP_ID) --location whatsapp.example.com
+
+# Update the app in a dev Cloudron
+dev-update:
+	cloudron update --app whatsapp.example.com --image $(CLOUDRON_APP_ID)
+
+# Publish to a Cloudron app store (requires token)
+publish:
+	@if [ -z "$(CLOUDRON_TOKEN)" ]; then echo "CLOUDRON_TOKEN is not set"; exit 1; fi
+	cloudron appstore publish --app $(CLOUDRON_APP_ID) --token $(CLOUDRON_TOKEN)

README.md

@@ -0,0 +1,32 @@
+# Matrix WhatsApp Bridge for Cloudron
+
+This is a Cloudron package for the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge.
+
+## Installation
+
+1. Install the app on your Cloudron
+2. The app will generate a default configuration file on first run
+3. Edit the configuration file at `/app/data/config.yaml` to set up your bridge
+4. Restart the app to generate the registration file
+5. Copy the registration file at `/app/data/registration.yaml` to your Matrix homeserver
+6. Update your homeserver configuration to include the registration file
+7. Restart your Matrix homeserver
+8. Restart the bridge app
+
+## Configuration
+
+For detailed configuration instructions, please refer to the [official documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html).
+
+## Authentication
+
+You will need to authenticate with WhatsApp to use the bridge. After starting the bridge:
+
+1. Send `login` to the bridge bot
+2. Scan the QR code with WhatsApp on your phone, or use the pairing code method
+3. The bridge will connect to WhatsApp Web
+
+## Support
+
+For support with the bridge itself, please visit [#whatsapp:maunium.net](https://matrix.to/#/#whatsapp:maunium.net) on Matrix.
+
+For issues with the Cloudron packaging, please file an issue on the GitHub repository.

start.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+
+set -eu
+
+echo "=> Setting up mautrix-whatsapp bridge"
+
+# Create necessary directories
+mkdir -p /app/data
+mkdir -p /app/data/logs
+
+# For Cloudron, we run as the cloudron user
+UID=$(id -u cloudron)
+GID=$(id -g cloudron)
+
+# Set ownership early to avoid permission issues
+chown -R cloudron:cloudron /app/data
+
+# Configuration file paths
+CONFIG_PATH="/app/data/config.yaml"
+REGISTRATION_PATH="/app/data/registration.yaml"
+BACKUP_PATH="/app/data/config.yaml.bak"
+
+# Create example config from built-in template
+if [ ! -f "$CONFIG_PATH" ]; then
+    echo "=> Generating example configuration"
+    /usr/local/bin/gosu cloudron:cloudron /app/pkg/mautrix-whatsapp -g -c "$CONFIG_PATH" -r "$REGISTRATION_PATH"
+    
+    # Configure for Cloudron environment
+    if [ -n "${CLOUDRON_POSTGRESQL_URL:-}" ]; then
+        echo "=> Configuring PostgreSQL database"
+        yq eval ".database = \"$CLOUDRON_POSTGRESQL_URL\"" -i "$CONFIG_PATH"
+    fi
+    
+    if [ -n "${CLOUDRON_APP_DOMAIN:-}" ]; then
+        echo "=> Configuring homeserver and appservice settings"
+        BASE_DOMAIN=$(echo "$CLOUDRON_APP_DOMAIN" | cut -d. -f2-)
+        
+        # Update homeserver configuration
+        yq eval ".homeserver.address = \"https://matrix.$BASE_DOMAIN\"" -i "$CONFIG_PATH"
+        yq eval ".homeserver.domain = \"$BASE_DOMAIN\"" -i "$CONFIG_PATH"
+        
+        # Update appservice configuration
+        yq eval ".appservice.address = \"https://$CLOUDRON_APP_DOMAIN\"" -i "$CONFIG_PATH"
+        yq eval ".appservice.hostname = \"0.0.0.0\"" -i "$CONFIG_PATH"
+        yq eval ".appservice.port = 29318" -i "$CONFIG_PATH"
+    fi
+    
+    # Set log file path
+    yq eval ".logging.handlers.file.filename = \"/app/data/logs/mautrix-whatsapp.log\"" -i "$CONFIG_PATH"
+    
+    chown cloudron:cloudron "$CONFIG_PATH" "$REGISTRATION_PATH"
+    
+    echo "=> Initial configuration complete"
+    echo "=> IMPORTANT: Please review $CONFIG_PATH and configure your Matrix homeserver settings"
+    echo "=> You will need to:"
+    echo "   1. Copy $REGISTRATION_PATH to your Matrix homeserver"
+    echo "   2. Update your homeserver configuration to include the registration file"
+    echo "   3. Restart your Matrix homeserver"
+    echo "   4. Restart this bridge app"
+    echo "   5. Authenticate with WhatsApp using QR code scanning"
+else
+    echo "=> Using existing configuration"
+fi
+
+# Final permission fix before starting
+chown -R cloudron:cloudron /app/data
+
+# Create a health check endpoint (run in background)
+mkdir -p /run/health
+echo '#!/bin/bash
+echo "HTTP/1.1 200 OK"
+echo "Content-Type: text/plain"
+echo ""
+echo "OK"' > /run/health/server.sh
+chmod +x /run/health/server.sh
+(cd /run/health && nohup nc -l -p 29318 -e ./server.sh > /dev/null 2>&1) &
+
+# Start the bridge
+echo "=> Starting mautrix-whatsapp bridge"
+exec /usr/local/bin/gosu cloudron:cloudron /app/pkg/mautrix-whatsapp -c "$CONFIG_PATH"