141 lines
5.0 KiB
Markdown
141 lines
5.0 KiB
Markdown
# 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`
|