homelab-optimized/docs/services/individual/beeper.md

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)

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

# 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
• Beeper: beeper.com (now merged with Texts.com/Automattic)

---

Last Updated: 2026-02-20 Configuration Source: homelab_vm/beeper.yaml