homelab/cluster/applications/signal-cli/DEPLOYMENT.md

Signal CLI REST API Deployment

Overview

Signal CLI REST API deployed in the connections namespace, accessible at connections.local.mk-labs.cloud with automatic TLS certificate management.

Infrastructure Details

Namespace

• Name: connections
• Theme: EPCOT Connections (Communication & World Showcase)

Deployment

• Name: signal-cli-rest-api
• Image: bbernhard/signal-cli-rest-api:0.85
• Replicas: 1 (MUST be 1 - signal-cli state is not multi-instance safe)
• Strategy: Recreate (prevents dual mount of PVC)
• Mode: json-rpc

Service

• Name: connections
• Type: ClusterIP
• Port: 8080
• Selector: app.kubernetes.io/name: signal-cli-rest-api

Ingress

• Name: connections
• Class: nginx
• Hostname: connections.local.mk-labs.cloud
• TLS: Enabled with cert-manager
• Certificate: Auto-provisioned via Let's Encrypt (letsencrypt-prod ClusterIssuer)
• DNS Challenge: Cloudflare DNS-01

Storage

• PVC: signal-cli-data
• Mount Path: /home/.local/share/signal-cli

ArgoCD Deployment

Application

• Name: signal-cli
• Namespace: argocd
• Sync Wave: 8
• Source Path: cluster/applications/signal-cli/
• Auto Sync: Enabled
• Auto Prune: Enabled
• Self Heal: Enabled

SSL/TLS Status

External Access (Ingress)

✅ Working - TLS certificate successfully issued by Let's Encrypt

• Certificate CN: connections.local.mk-labs.cloud
• Issuer: Let's Encrypt (YR2)
• Valid until: September 10, 2026
• DNS-01 challenge completed successfully via Cloudflare

Signal Server Communication

✅ Working - No SSL errors detected

• Signal-cli uses Java's built-in truststore (OpenJDK 21)
• Java truststore includes Signal's CA certificates
• No custom CA injection needed

Note on curl SSL Errors

The initial SSL error encountered with curl was due to the system CA bundle being outdated in the container. This does NOT affect signal-cli functionality because:

1. Signal-cli uses Java's truststore, not the system CA bundle
2. Java's truststore is properly maintained and includes Signal's root CA
3. All signal-cli operations work correctly without SSL errors

Endpoints

Health Check

GET https://connections.local.mk-labs.cloud/v1/health

About/Version

GET https://connections.local.mk-labs.cloud/v1/about

Expected response:

{
  "versions": ["v1", "v2"],
  "build": 2,
  "mode": "json-rpc",
  "version": "0.85",
  "capabilities": {
    "v2/send": ["quotes", "mentions"]
  }
}

Migration from cluster/platform/connections

Files were moved from cluster/platform/connections/ to cluster/applications/signal-cli/:

• ✅ namespace.yaml
• ✅ deployment.yaml
• ✅ service.yaml
• ✅ persistentvolumeclaim.yaml
• ✅ application.yaml (updated source path)
• ✅ ingress.yaml (newly created)

Current Status

Production Gateway: astro-orbiter VM (10.1.71.130:8080)

• signal-cli 0.14.3 native daemon mode with HTTP JSON-RPC API
• Account +126****8840 registered and operational
• Hermes connected via SIGNAL_HTTP_URL=http://10.1.71.130:8080

K8s Deployment Status:

• ✅ Infrastructure deployed and ready (ingress, PVC, service)
• ✅ Native signal-cli daemon running in multi-account mode
• ✅ Ingress accessible at https://connections.local.mk-labs.cloud
• ❌ Cannot complete Signal registration from K8s network path
  • Linking fails with "Connection closed unexpectedly" during WebSocket handshake
  • Signal servers reject connections from K8s cluster (HTTP 499, same on all nodes)
  • Issue persists with hostNetwork=true
  • Likely NAT/firewall/IP reputation blocking Signal WebSocket connections

When Migrating from Astro-Orbiter:

1. Link account from a non-K8s VM (e.g., carousel-of-progress)
2. Copy working signal-cli data to K8s PVC
3. Update Hermes: SIGNAL_HTTP_URL=https://connections.local.mk-labs.cloud
4. Restart Hermes gateway

Next Steps

1. Investigate K8s egress networking - why Signal rejects WebSocket connections from cluster
2. Alternative: Keep Signal gateway on dedicated VM outside K8s

Monitoring

Check deployment status:

kubectl get all,ingress,certificate -n connections

Check ArgoCD sync status:

kubectl get application signal-cli -n argocd

View logs:

kubectl logs -n connections deployment/signal-cli-rest-api -f