ef4d2c1072
- 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>
87 lines
3.4 KiB
Markdown
87 lines
3.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
### Custom Cloudron Build Service
|
|
```bash
|
|
cloudron build --set-build-service builder.docker.due.ren --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e --set-repository andreasdueren/matrix-whatsapp-bridge --tag [version]
|
|
```
|
|
|
|
### Remote Installation
|
|
```bash
|
|
cloudron install --location whatsapp.matrix.due.ren --image andreasdueren/matrix-whatsapp-bridge:1.1.0
|
|
```
|
|
|
|
### 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) |