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