Initial commit

# 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

 No newline at end of file

# 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)

 No newline at end of file

{

  "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"

}

 No newline at end of file

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)

 No newline at end of file

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"]

 No newline at end of file