Sanitized mirror from private repository - 2026-04-19 08:46:29 UTC

docs/services/individual/beeper.md

@@ -0,0 +1,140 @@
+# Beeper
+
+**🟢 Communication Service**
+
+## 📋 Service Overview
+
+| Property | Value |
+|----------|-------|
+| **Service Name** | beeper |
+| **Host** | Homelab VM |
+| **Category** | Communication |
+| **Docker Image** | `ghcr.io/zachatrocity/docker-beeper:latest` |
+| **Compose File** | `homelab_vm/beeper.yaml` |
+| **Portainer Stack** | `beeper` (ID=536, homelab-vm endpoint, standalone) |
+
+## 🎯 Purpose
+
+Beeper is a universal chat client that bridges many messaging platforms (iMessage, WhatsApp, Telegram, Signal, Discord, etc.) into a single interface. This deployment uses a KasmVNC-based Docker image that runs the Beeper desktop app in a containerized browser session accessible via web browser.
+
+> **Note**: Beeper is no longer a standalone product — it merged with Automattic/Texts.com. This image (`docker-beeper`) provides the legacy Beeper Linux desktop client via KasmVNC.
+
+## 🚀 Access
+
+| Interface | URL | Notes |
+|-----------|-----|-------|
+| Web UI (HTTPS) | `https://<homelab-vm-ip>:3656` | Use this — accept self-signed cert |
+| Web UI (HTTP) | `http://<homelab-vm-ip>:3655` | Redirects to HTTPS, will show error |
+
+> **Important**: KasmVNC requires HTTPS. Always access via port **3656** with HTTPS. Accept the self-signed certificate warning in your browser.
+
+## 🔧 Configuration
+
+### Docker Compose (`homelab_vm/beeper.yaml`)
+
+```yaml
+services:
+  beeper:
+    image: ghcr.io/zachatrocity/docker-beeper:latest
+    container_name: Beeper
+    healthcheck:
+      test: ["CMD-SHELL", "nc -z 127.0.0.1 3000 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 90s
+    security_opt:
+      - seccomp:unconfined
+    environment:
+      PUID: 1029
+      PGID: 100
+      TZ: America/Los_Angeles
+    volumes:
+      - /home/homelab/docker/beeper:/config:rw
+    ports:
+      - 3655:3000   # HTTP (redirects to HTTPS — use port 3656)
+      - 3656:3001   # HTTPS (use this — accept self-signed cert in browser)
+    shm_size: "2gb"
+    restart: on-failure:5
+```
+
+### Environment Variables
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `PUID` | `1029` | User ID for file permissions |
+| `PGID` | `100` | Group ID for file permissions |
+| `TZ` | `America/Los_Angeles` | Timezone |
+
+### Port Mappings
+
+| Host Port | Container Port | Protocol | Purpose |
+|-----------|----------------|----------|---------|
+| 3655 | 3000 | TCP | HTTP (redirects to HTTPS — non-functional) |
+| 3656 | 3001 | TCP | HTTPS KasmVNC (use this) |
+
+### Volume Mappings
+
+| Host Path | Container Path | Type | Purpose |
+|-----------|----------------|------|---------|
+| `/home/homelab/docker/beeper` | `/config` | bind | App config, sessions, data |
+
+### Notable Settings
+
+- **`shm_size: "2gb"`** — Required for Chromium/Electron running inside KasmVNC; prevents crashes
+- **`seccomp:unconfined`** — Required for Electron sandbox inside container
+- **`restart: on-failure:5`** — Restart on crash up to 5 times (avoids restart loops)
+
+## 🔧 Portainer Deployment
+
+This service is managed as a **standalone Portainer stack** (ID=536) on the homelab-vm endpoint. The compose file is stored in the repo at `homelab_vm/beeper.yaml` for reference, but Portainer manages it with inline content rather than GitOps sync.
+
+> **Why not GitOps?** The homelab-vm Portainer Edge Agent deploys all YAML files in `hosts/vms/homelab-vm/` together as a combined compose project. The local monitoring stack (prometheus/grafana, started from `/home/homelab/docker/monitoring/`) conflicts with `monitoring.yaml` in that directory, blocking new GitOps stack creation. The monitoring-stack Portainer entry was removed to avoid the conflict — those containers continue running independently.
+
+To update beeper:
+1. Edit the stack via Portainer UI → Stacks → beeper → Editor
+2. Or use the Portainer API to update stack 536 with new compose content
+
+## 🚨 Troubleshooting
+
+**"This application requires a secure connection (HTTPS)"**
+- You accessed port 3655 (HTTP). Switch to `https://<ip>:3656`.
+- Accept the self-signed certificate warning.
+
+**Container keeps restarting**
+- Check logs: `docker logs Beeper`
+- The `shm_size: "2gb"` is critical — without it, Chromium OOM-crashes constantly.
+- Ensure `/home/homelab/docker/beeper` exists and is writable by PUID 1029.
+
+**Black screen or blank browser**
+- Give the container 90 seconds to start (see `start_period` in healthcheck).
+- Hard-refresh the browser page.
+
+**Session lost after restart**
+- Sessions are persisted to `/home/homelab/docker/beeper` — check that volume is mounted.
+
+### Useful Commands
+
+```bash
+# View logs
+docker logs -f Beeper
+
+# Restart container
+docker restart Beeper
+
+# Check health
+docker inspect --format='{{.State.Health.Status}}' Beeper
+
+# Verify data directory
+ls -la /home/homelab/docker/beeper/
+```
+
+## 📚 Additional Resources
+
+- **Image Source**: [zachatrocity/docker-beeper](https://github.com/zachatrocity/docker-beeper)
+- **Beeper**: [beeper.com](https://www.beeper.com) (now merged with Texts.com/Automattic)
+
+---
+
+*Last Updated*: 2026-02-20
+*Configuration Source*: `homelab_vm/beeper.yaml`