homelab-optimized/docs/services/individual/signal-cli-rest-api.md

Signal Cli Rest Api

🟢 Communication Service

📋 Service Overview

Property	Value
Service Name	signal-cli-rest-api
Host	homelab_vm
Category	Communication
Difficulty	🟢
Docker Image	bbernhard/signal-cli-rest-api
Compose File	hosts/vms/homelab-vm/signal_api.yaml
Directory	hosts/vms/homelab-vm
API Version	0.97
Mode	native
Registered Number	REDACTED_PHONE_NUMBER

🎯 Purpose

Provides a REST API wrapper around signal-cli, enabling other homelab services to send and receive Signal messages programmatically. Used for alerting and notifications.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Basic understanding of REDACTED_APP_PASSWORD
• Access to the host system (homelab_vm)

Deployment

# Navigate to service directory
cd homelab_vm

# Start the service
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f signal-cli-rest-api

🔧 Configuration

Docker Compose Configuration

# signal-api (main REST API)
container_name: signal-api
image: bbernhard/signal-cli-rest-api
environment:
  - MODE=native
ports:
  - 8080:8080
restart: always
volumes:
  - /home/homelab/docker/signal:/home/.local/share/signal-cli

# signal-bridge (Python bridge, port 5000)
# Separate container — Python 3.11
container_name: signal-bridge
ports:
  - 5000:5000
restart: always

Environment Variables

Variable	Value	Description
MODE	native	Configuration variable

Port Mappings

Host Port	Container Port	Protocol	Purpose
8080	8080	TCP	Alternative HTTP port

Volume Mappings

Host Path	Container Path	Type	Purpose
/home/homelab/docker/signal	/home/.local/share/signal-cli	bind	Data storage

🌐 Access Information

Web Interface

• API: http://homelab.tail.vish.gg:8080 (Tailscale only)
• Swagger UI: http://homelab.tail.vish.gg:8080/v1/api-docs/
• Bridge: http://homelab.tail.vish.gg:5000

Registered Account

• Phone number: REDACTED_PHONE_NUMBER
• No API key required — unauthenticated REST API

🔒 Security Considerations

• ⚠️ Consider adding security options (no-new-privileges)
• ⚠️ Consider running as non-root user

📊 Resource Requirements

No resource limits configured

Recommended Resources

• Minimum RAM: 512MB
• Recommended RAM: 1GB+
• CPU: 1 core minimum
• Storage: Varies by usage

Resource Monitoring

Monitor resource usage with:

docker stats

🔍 Health Monitoring

Manual Health Checks

# Check container status (run on homelab VM)
ssh homelab  # password: "REDACTED_PASSWORD"
docker ps --filter name=signal

# Check API health endpoint
curl -s http://localhost:8080/v1/health
# Expected: {"status":"alive"}

# Check API version and registered accounts
curl -s http://localhost:8080/v1/about
# Returns: {"mode":"native","version":"0.97","build_nr":...}

# List registered accounts
curl -s http://localhost:8080/v1/accounts
# Should return: ["REDACTED_PHONE_NUMBER"]

# Send a test message
curl -s -X POST http://localhost:8080/v2/send \
  -H 'Content-Type: application/json' \
  -d '{"message":"test","number":"REDACTED_PHONE_NUMBER","recipients":["+1XXXXXXXXXX"]}'

Container Names

Container	Purpose	Port
signal-api	REST API wrapper for signal-cli	8080
signal-bridge	Python 3.11 bridge	5000

🚨 Troubleshooting

Common Issues

Service won't start

• Check Docker logs: docker-compose logs service-name
• Verify port availability: netstat -tulpn | grep PORT
• Check file permissions on mounted volumes

Can't access web interface

• Verify service is running: docker-compose ps
• Check firewall settings
• Confirm correct port mapping

Performance issues

• Monitor resource usage: docker stats
• Check available disk space: df -h
• Review service logs for errors

Useful Commands

# Check service status
docker-compose ps

# View real-time logs
docker-compose logs -f signal-cli-rest-api

# Restart service
docker-compose restart signal-cli-rest-api

# Update service
docker-compose pull signal-cli-rest-api
docker-compose up -d signal-cli-rest-api

# Access service shell
docker-compose exec signal-cli-rest-api /bin/bash
# or
docker-compose exec signal-cli-rest-api /bin/sh

📚 Additional Resources

• Official Documentation: Check the official docs for signal-cli-rest-api
• Docker Hub: bbernhard/signal-cli-rest-api
• Community Forums: Search for community discussions and solutions
• GitHub Issues: Check the project's GitHub for known issues

🔗 Related Services

Other services in the communication category on homelab_vm

---

This documentation is auto-generated from the Docker Compose configuration. For the most up-to-date information, refer to the official documentation and the actual compose file.

Last Updated: 2026-03-10 (verified healthy: v0.97 native, REDACTED_PHONE_NUMBER registered, bridge container documented) Configuration Source: hosts/vms/homelab-vm/signal_api.yaml