Server Deployment Guide

Deploy and configure Taps.IM federation servers in production environments

Quick Start

🚀 Production-Ready Setup

Get a Taps.IM federation server running in production with TLS, monitoring, and automatic failover in under 30 minutes using our pre-built Windows executables and configuration templates.

⬇️

1. Download

Get the latest production builds with P9 observability features

⚙️

2. Configure

Set up TLS certificates, database, and federation peers

🚀

3. Deploy

Start the server with monitoring and health checks enabled

System Requirements

Hardware Specifications

💻 Minimum Requirements

  • • CPU: 2 cores, 2.0 GHz
  • • RAM: 4GB available memory
  • • Storage: 50GB SSD storage
  • • Network: 100 Mbps connection
  • • OS: Windows Server 2019+, Linux, macOS

🚀 Recommended (Production)

  • • CPU: 4+ cores, 3.0+ GHz
  • • RAM: 8GB+ available memory
  • • Storage: 200GB+ NVMe SSD
  • • Network: 1 Gbps+ connection
  • • OS: Windows Server 2022, Ubuntu 22.04 LTS

⚡ Performance Scaling

Small Organization
  • • Up to 100 users
  • • 10,000 messages/day
  • • 2 CPU cores, 4GB RAM
Medium Organization
  • • Up to 1,000 users
  • • 100,000 messages/day
  • • 4 CPU cores, 8GB RAM
Large Organization
  • • Up to 10,000 users
  • • 1,000,000+ messages/day
  • • 8+ CPU cores, 16GB+ RAM

Installation

Windows Installation

Invoke-WebRequest -Uri "https://releases.taps.im/latest/taps-server-windows.zip" -OutFile "taps-server.zip"
# Extract the server executable
Expand-Archive -Path "taps-server.zip" -DestinationPath "C:\TapsIM"
# Verify the installation
C:\TapsIM\taps-server.exe --version

📦 Package Contents

  • • taps-server.exe - Federation server (50MB, CGO-enabled)
  • • taps-client.exe - CLI client for testing (9.8MB)
  • • config.example.yaml - Configuration template
  • • install-service.ps1 - Windows Service installer

Linux Installation

wget https://releases.taps.im/latest/taps-server-linux.tar.gz
tar -xzf taps-server-linux.tar.gz
sudo mv taps-server /usr/local/bin/
sudo chmod +x /usr/local/bin/taps-server
# Verify installation
taps-server --version

🐧 Linux Distribution Support

  • • Ubuntu 20.04/22.04 LTS: Fully supported and tested
  • • RHEL/CentOS 8+: Supported with systemd service files
  • • Debian 11+: Supported with package manager integration
  • • Amazon Linux 2: AWS-optimized builds available

Configuration

Basic Configuration

server:
listen_addr: "0.0.0.0"
listen_port: 8443
server_id: "company.taps.im"
max_message_size: 1048576
tls:
cert_file: "/etc/taps/cert.pem"
key_file: "/etc/taps/key.pem"
min_version: "1.3"
database:
type: "sqlite"
path: "/var/lib/taps/database.db"
max_connections: 25
federation:
peers:
- "https://partner1.example.com:8443"
- "https://partner2.example.com:8443"
max_concurrent_streams: 100
keepalive_interval: "30s"

🔑 Required Settings

  • • server_id: Unique federation identifier
  • • TLS certificates: Valid SSL certificates
  • • database: Persistent storage configuration
  • • peers: Federation partner servers

⚙️ Advanced Options

  • • rate_limits: Configure per-peer limits
  • • logging: Structured logging configuration
  • • metrics: Prometheus metrics endpoint
  • • tracing: OpenTelemetry configuration

TLS Certificate Setup

🔒 Production Security

TLS certificates are required for production federation. Never run a production server without proper TLS encryption.

  • • Use certificates from a trusted CA (Let's Encrypt recommended)
  • • Configure automatic certificate renewal
  • • Enable only TLS 1.3 for maximum security
  • • Implement HSTS and certificate pinning where possible
# Install Certbot
sudo apt install certbot
# Obtain certificates
sudo certbot certonly --standalone -d your-domain.taps.im
# Configure auto-renewal
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer

Database Configuration

📁 SQLite (Default)

Recommended for small to medium deployments. Zero-configuration with excellent performance.

database:
type: "sqlite"
path: "/var/lib/taps/taps.db"
wal_mode: true
busy_timeout: "30s"

🐘 PostgreSQL

Recommended for large deployments requiring high concurrency and advanced features.

database:
type: "postgres"
host: "localhost"
port: 5432
database: "tapsim"
user: "taps"
password: "secure-password"

Production Deployment

Windows Service Installation

# Run as Administrator
.\install-service.ps1 -ServiceName "TapsIM-Federation" -ConfigPath "C:\TapsIM\config.yaml"
# Start the service
Start-Service -Name "TapsIM-Federation"
# Check service status
Get-Service -Name "TapsIM-Federation"

🔧 Service Configuration

  • • Automatic startup: Service starts automatically on boot
  • • Failure recovery: Automatic restart on failure
  • • Logging: Windows Event Log integration
  • • Security: Runs as dedicated service account

Linux systemd Service

[Unit]
Description=Taps.IM Federation Server
After=network.target
Wants=network.target
[Service]
Type=simple
User=taps
Group=taps
ExecStart=/usr/local/bin/taps-server -config /etc/taps/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
WorkingDirectory=/var/lib/taps
[Install]
WantedBy=multi-user.target
# Install and start the service
sudo systemctl daemon-reload
sudo systemctl enable taps-federation
sudo systemctl start taps-federation
# Check service status
sudo systemctl status taps-federation

Monitoring & Observability

Taps.IM servers include comprehensive P9 observability features with OpenTelemetry tracing, Prometheus metrics, and structured logging for production monitoring.

Metrics Collection

observability:
metrics:
enabled: true
listen_addr: "0.0.0.0:9090"
path: "/metrics"
tracing:
enabled: true
endpoint: "http://jaeger:14268/api/traces"
logging:
level: "info"
format: "json"
output: "/var/log/taps/federation.log"

📊 Metrics

  • • Federation throughput
  • • Credit utilization
  • • Event processing latency
  • • Connection health
  • • Database performance

🔍 Tracing

  • • End-to-end request tracing
  • • Federation span correlation
  • • Performance bottlenecks
  • • Error trace analysis
  • • Cross-server visibility

📝 Logging

  • • Structured JSON logs
  • • Federation events
  • • Security audit trails
  • • Error tracking
  • • Sensitive data redaction

Health Checks

🏥 Built-in Health Endpoints

Primary Endpoints
  • • /health - Basic health check
  • • /health/ready - Readiness probe
  • • /health/live - Liveness probe
  • • /metrics - Prometheus metrics
Federation Status
  • • /_taps/federation/caps - Capabilities
  • • /debug/stats - Detailed stats
  • • /debug/groups - Group info
  • • /api/v1/federation/info - P5 info

Maintenance & Operations

Regular Maintenance Tasks

📅 Daily Tasks

  • • Monitor health endpoints: Check /health and /metrics
  • • Review error logs: Check for authentication or federation failures
  • • Verify federation connections: Ensure all peers are connected
  • • Database performance: Monitor query performance and connection pool

📅 Weekly Tasks

  • • Certificate expiration: Check TLS certificate validity
  • • Database maintenance: Run VACUUM (SQLite) or VACUUM ANALYZE (PostgreSQL)
  • • Log rotation: Archive old logs and free disk space
  • • Backup verification: Test database backup integrity

📅 Monthly Tasks

  • • Security updates: Update server binaries and dependencies
  • • Configuration review: Review and optimize server settings
  • • Capacity planning: Analyze growth trends and resource usage
  • • Disaster recovery test: Test backup restoration procedures

Backup & Recovery

💾 Critical Data Protection

Federation servers contain critical encrypted messages and group state. Implement regular backups with encryption and test recovery procedures regularly.

#!/bin/bash
# Daily encrypted backup
BACKUP_DIR="/backups/taps"
DATE=$(date +%Y%m%d)
# Stop the service for consistent backup
sudo systemctl stop taps-federation
# Create encrypted backup
tar -czf - /var/lib/taps/ | gpg -c --cipher-algo AES256 > $BACKUP_DIR/taps-backup-$DATE.tar.gz.gpg
# Restart the service
sudo systemctl start taps-federation
# Clean old backups (keep 30 days)
find $BACKUP_DIR -name "taps-backup-*.tar.gz.gpg" -mtime +30 -delete

Troubleshooting

Common Issues

🚫 Federation Connection Failures

Symptoms: Peers not connecting, message relay failures

Common Causes:

  • • TLS certificate issues or expiration
  • • Firewall blocking federation ports
  • • DNS resolution problems
  • • Clock synchronization issues

Solution: Check logs, verify certificates, test network connectivity

⚠️ Database Performance Issues

Symptoms: Slow response times, high CPU usage

Common Causes:

  • • Database not properly indexed
  • • WAL mode not enabled (SQLite)
  • • Insufficient database connections
  • • Disk I/O bottlenecks

Solution: Enable WAL mode, increase connection pool, optimize queries

🔒 TLS/SSL Issues

Symptoms: Certificate validation failures, handshake errors

Common Causes:

  • • Expired or invalid certificates
  • • Certificate chain not complete
  • • TLS version mismatch
  • • SNI configuration issues

Solution: Verify certificate chain, update certificates, check TLS settings

Debug Commands

# Check federation capabilities
curl -s https://your-server:8443/_taps/federation/caps | jq
# Test peer connectivity
taps-client --server https://your-server:8443 health
# View detailed server stats
curl -s https://your-server:8443/debug/stats | jq
# Check federation streams
curl -s https://your-server:8443/api/v1/federation/info | jq
# Test certificate validity
openssl s_client -connect your-server:8443 -servername your-server

Security Considerations

🔒 Production Security Checklist

Network Security

  • • TLS 1.3 only: Disable older TLS versions
  • • Firewall rules: Restrict access to federation ports
  • • DDoS protection: Implement rate limiting
  • • Network isolation: Use VPCs or private networks

System Security

  • • Dedicated user: Run as non-privileged user
  • • File permissions: Restrict access to config/data
  • • Regular updates: Keep system and server updated
  • • Audit logging: Enable comprehensive logging

🛡️ Access Control

  • • Federation authentication: Mutual TLS for server verification
  • • Admin interfaces: Separate management network
  • • Certificate management: Automated rotation and renewal
  • • Monitoring access: Restrict metrics endpoints

📊 Security Monitoring

  • • Failed connections: Alert on repeated failures
  • • Certificate expiry: Monitor certificate validity
  • • Unusual traffic: Detect anomalous patterns
  • • Security updates: Subscribe to security advisories

Related Documentation

Federated Architecture

Understanding the federated network architecture and server communication protocols.

Federation Protocol

Technical specification of the TapsIM Federation Protocol and frame formats.

Zero-Knowledge Security

Details on the zero-knowledge encryption and server opacity implementation.

Compliance Documentation

Security audits, compliance reports, and certification documents.