Sanitized mirror from private repository - 2026-04-06 10:21:40 UTC
This commit is contained in:
Gitea Mirror Bot
271
docs/services/individual/signal-cli-rest-api.md
Normal file
271
docs/services/individual/signal-cli-rest-api.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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.98 |
|
||||
| **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
|
||||
```bash
|
||||
# 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
|
||||
```yaml
|
||||
# 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
|
||||
|
||||
## Arr Suite Integration
|
||||
|
||||
Signal notifications are configured in Lidarr, Sonarr, Radarr, Prowlarr, and Whisparr on Atlantis.
|
||||
|
||||
### Important: Use LAN IP, not Tailscale IP
|
||||
|
||||
Signal-api runs on **homelab-vm** (`192.168.0.210:8080`). All Atlantis arr services use the **LAN IP** to reach it.
|
||||
|
||||
**Why not the Tailscale IP?** Synology NAS devices (Atlantis, Calypso) run Tailscale in userspace networking mode — there is no `tailscale0` tun device, so the kernel cannot route TCP traffic to Tailscale IPs. While `tailscale configure-host` can enable kernel networking temporarily, it is unstable on Synology and causes tailscaled to crash repeatedly. The LAN path is reliable since both hosts are on the same 192.168.0.0/24 network.
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **Host** | `192.168.0.210` |
|
||||
| **Port** | `8080` |
|
||||
| **Use SSL** | No |
|
||||
| **Sender Number** | `REDACTED_PHONE_NUMBER` |
|
||||
| **Receiver** | `REDACTED_PHONE_NUMBER` |
|
||||
|
||||
### Configured Apps (Atlantis)
|
||||
|
||||
| App | Port | Notification ID |
|
||||
|-----|------|----------------|
|
||||
| Lidarr | 8686 | 3 |
|
||||
| Sonarr | 8989 | 2 |
|
||||
| Radarr | 7878 | 1 |
|
||||
| Prowlarr | 9696 | 1 |
|
||||
| Whisparr | 6969 | 1 |
|
||||
| Bazarr | 6767 | N/A (SQLite) |
|
||||
|
||||
### Updating the host via API (Lidarr/Sonarr/Radarr/Prowlarr/Whisparr)
|
||||
|
||||
If the host needs updating (e.g. after an IP change), use the arr API:
|
||||
|
||||
```bash
|
||||
# Get current notification config
|
||||
curl -s -H "X-Api-Key: <APIKEY>" http://100.83.230.112:<PORT>/api/v3/notification/<ID>
|
||||
|
||||
# Test notification
|
||||
curl -s -X POST -H "X-Api-Key: <APIKEY>" http://100.83.230.112:<PORT>/api/v3/notification/test/<ID>
|
||||
```
|
||||
|
||||
### Updating the host for Bazarr (SQLite direct edit)
|
||||
|
||||
Bazarr stores notifier config in its SQLite DB. The REST API does **not** persist notification changes — you must edit the DB directly.
|
||||
|
||||
```bash
|
||||
# 1. Copy DB out of container (via Portainer archive API or docker cp on Atlantis)
|
||||
docker cp bazarr:/config/db/bazarr.db /tmp/bazarr.db
|
||||
|
||||
# 2. Update the Signal API URL
|
||||
python3 -c "
|
||||
import sqlite3
|
||||
conn = sqlite3.connect('/tmp/bazarr.db')
|
||||
cur = conn.cursor()
|
||||
cur.execute(\"UPDATE table_settings_notifier SET url='signal://192.168.0.210:8080/%2B15103961064/%2B15103961064' WHERE name='Signal API'\")
|
||||
conn.commit()
|
||||
conn.close()
|
||||
"
|
||||
|
||||
# 3. Stop Bazarr, copy DB back, restart
|
||||
docker stop bazarr
|
||||
docker cp /tmp/bazarr.db bazarr:/config/db/bazarr.db
|
||||
docker restart bazarr
|
||||
```
|
||||
|
||||
## 🔒 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:
|
||||
```bash
|
||||
docker stats
|
||||
```
|
||||
|
||||
## 🔍 Health Monitoring
|
||||
|
||||
### Manual Health Checks
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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](https://hub.docker.com/r/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-29 (Switched all arr-stack Signal notifications from Tailscale IP to LAN IP 192.168.0.210 — Synology userspace networking cannot route TCP to Tailscale IPs reliably)
|
||||
**Configuration Source**: `hosts/vms/homelab-vm/signal_api.yaml`
|
||||
Reference in New Issue
Block a user