Single-Node Deployment

The simplest deployment model: one binary, one server, local models. Ideal for development, testing, pilot deployments, and small-scale production use (up to ~10 concurrent calls on a modern server).

Requirements

Resource	Minimum	Recommended
CPU	4 cores	8 cores
RAM	4 GB	8 GB
Disk	10 GB	20 GB
GPU	None	NVIDIA T4 or better
OS	Ubuntu 22.04+ / RHEL 8+	Ubuntu 24.04 LTS
Network	1 Gbps	1 Gbps

Port Requirements

Port	Protocol	Service
5060	UDP/TCP	SIP signaling
10000–20000	UDP	RTP audio
8080	TCP	REST API
8080	TCP	HTTP API
9100	TCP	Prometheus metrics

Installation

# Download and install
curl -sSL https://get.voicetyped.com/install | sh

# Download ASR model
voice-gateway model download whisper-medium

# Generate default configuration
voice-gateway config init > /etc/voice-gateway/config.yaml

systemd Service

Create a systemd unit file:

# /etc/systemd/system/voice-gateway.service

[Unit]
Description=voicetyped
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=voicegateway
Group=voicegateway
ExecStart=/usr/local/bin/voice-gateway start \
  --config /etc/voice-gateway/config.yaml
Restart=always
RestartSec=5
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/voice-gateway /var/log/voice-gateway
PrivateTmp=true

# Environment
Environment=VG_LOG_LEVEL=info
EnvironmentFile=-/etc/voice-gateway/env

[Install]
WantedBy=multi-user.target

Enable and Start

# Create service user
sudo useradd -r -s /bin/false voicegateway

# Create directories
sudo mkdir -p /etc/voice-gateway /var/lib/voice-gateway /var/log/voice-gateway
sudo chown voicegateway:voicegateway /var/lib/voice-gateway /var/log/voice-gateway

# Reload systemd and enable
sudo systemctl daemon-reload
sudo systemctl enable voice-gateway
sudo systemctl start voice-gateway

# Check status
sudo systemctl status voice-gateway

Configuration

# /etc/voice-gateway/config.yaml

media:
  sip_port: 5060
  rtp_port_range: "10000-20000"
  codecs:
    - g711-ulaw
    - g711-alaw
    - opus

speech:
  engine: whisper
  model: whisper-medium
  model_dir: /var/lib/voice-gateway/models/
  language: en
  gpu: auto
  max_workers: 2

runtime:
  dialog_dir: /etc/voice-gateway/dialogs/
  default_timeout: 10s
  max_concurrent_calls: 10
  state_store: memory

integration:
  api_port: 8080

observability:
  metrics_port: 9100
  log_level: info
  log_file: /var/log/voice-gateway/vg.log

security:
  mtls: false

Environment Variables

Sensitive values should be set via environment variables in /etc/voice-gateway/env:

# /etc/voice-gateway/env
SIP_PASSWORD=your-sip-registration-password
WEBHOOK_TOKEN=your-webhook-auth-token
REDIS_PASSWORD=your-redis-password

Set restrictive permissions:

sudo chmod 600 /etc/voice-gateway/env
sudo chown voicegateway:voicegateway /etc/voice-gateway/env

Firewall Configuration

# UFW
sudo ufw allow 5060/udp    # SIP
sudo ufw allow 10000:20000/udp  # RTP
sudo ufw allow 8080/tcp    # REST API
sudo ufw allow 9100/tcp    # Metrics

# firewalld
sudo firewall-cmd --permanent --add-port=5060/udp
sudo firewall-cmd --permanent --add-port=10000-20000/udp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=9100/tcp
sudo firewall-cmd --reload

Log Management

journald

# View logs
sudo journalctl -u voice-gateway -f

# View last 100 lines
sudo journalctl -u voice-gateway -n 100

# View errors only
sudo journalctl -u voice-gateway -p err

Log Rotation

If logging to file, configure logrotate:

# /etc/logrotate.d/voice-gateway
/var/log/voice-gateway/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        systemctl reload voice-gateway 2>/dev/null || true
    endscript
}

Upgrading

# Stop the service
sudo systemctl stop voice-gateway

# Download new version
curl -sSL https://get.voicetyped.com/install | sh

# Start the service
sudo systemctl start voice-gateway

# Verify
voice-gateway version

Monitoring

Health Check

# Quick status
voice-gateway status

# Detailed health check
curl -s http://localhost:9100/health | jq

Prometheus

Add to your Prometheus configuration:

# prometheus.yml
scrape_configs:
  - job_name: 'voice-gateway'
    static_configs:
      - targets: ['localhost:9100']

Next Steps

Kubernetes Deployment — scale to multi-node
Air-Gapped Deployment — deploy without internet
Security — enable mTLS and audit logging
Observability — full monitoring setup