For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI ReferenceSelf HostModel CardsClient LibrariesIntegrationsDeveloper ToolsChangelog
DocumentationAPI ReferenceSelf HostModel CardsClient LibrariesIntegrationsDeveloper ToolsChangelog
  • Getting Started
    • Introduction
    • Prerequisites
    • Why Self-Host?
    • Architecture
  • Docker Setup
      • Quick Start
      • Services Overview
      • Configuration
      • Troubleshooting
  • Kubernetes Setup
    • Quick Start
    • Troubleshooting
  • Troubleshooting
    • Common Issues
    • Debugging Guide
    • Logs Analysis
  • API Reference
    • Authentication
    • Examples
LogoLogo
Voice AgentsModels
Voice AgentsModels
On this page
  • Overview
  • Step 1: Create Project Directory
  • Step 2: Login to Container Registry
  • Step 3: Create Environment File
  • Step 4: Create Docker Compose File
  • Step 5: Start Services
  • Step 6: Monitor Startup
  • Step 7: Verify Installation
  • Step 8: Test API
  • Common Startup Issues
  • Managing Your Deployment
  • Stop Services
  • Restart Services
  • View Logs
  • Update Images
  • Remove Deployment
  • What’s Next?
Docker SetupTTS Deployment

Quick Start

||View as Markdown|
Was this page helpful?
Previous

Verification Checklist

Next

Services Overview

Built with

Overview

This guide walks you through deploying Smallest Self-Host Text-to-Speech (TTS) using Docker Compose. You’ll have a fully functional text-to-speech service running in under 15 minutes.

Ensure you’ve completed all prerequisites before starting this guide.

Step 1: Create Project Directory

Create a directory for your deployment:

$mkdir -p ~/smallest-tts
$cd ~/smallest-tts

Step 2: Login to Container Registry

Authenticate with the Smallest container registry using credentials provided by support:

$docker login quay.io

Enter your username and password when prompted.

Save your credentials securely. You’ll need them if you restart or redeploy the containers.

Step 3: Create Environment File

Create a .env file with your license key:

$cat > .env << 'EOF'
$LICENSE_KEY=your-license-key-here
$EOF

Replace your-license-key-here with the actual license key provided by Smallest.ai.

Never commit your .env file to version control. Add it to .gitignore if using git.

Step 4: Create Docker Compose File

Create a docker-compose.yml file for TTS deployment:

docker-compose.yml
1version: "3.8"
2
3services:
4  lightning-tts:
5    image: quay.io/smallestinc/lightning-tts:latest
6    ports:
7      - "8876:8876"
8    environment:
9      - LICENSE_KEY=${LICENSE_KEY}
10      - REDIS_HOST=redis
11      - REDIS_PORT=6379
12      - PORT=8876
13    deploy:
14      resources:
15        reservations:
16          devices:
17            - driver: nvidia
18              count: 1
19              capabilities: [gpu]
20    restart: unless-stopped
21    networks:
22      - smallest-network
23
24  api-server:
25    image: quay.io/smallestinc/self-hosted-api-server:latest
26    container_name: api-server
27    environment:
28      - LICENSE_KEY=${LICENSE_KEY}
29      - LIGHTNING_TTS_BASE_URL=http://lightning-tts:8876
30      - API_BASE_URL=http://license-proxy:3369
31      - REDIS_HOST=redis
32      - REDIS_PORT=6379
33    ports:
34      - "7100:7100"
35    networks:
36      - smallest-network
37    restart: unless-stopped
38    depends_on:
39      - lightning-tts
40      - license-proxy
41
42  license-proxy:
43    image: quay.io/smallestinc/license-proxy:latest
44    container_name: license-proxy
45    environment:
46      - LICENSE_KEY=${LICENSE_KEY}
47      - PORT=3369
48    networks:
49      - smallest-network
50    restart: unless-stopped
51
52  redis:
53    image: redis:7-alpine
54    container_name: redis-server
55    ports:
56      - "6379:6379"
57    networks:
58      - smallest-network
59    restart: unless-stopped
60    command: redis-server --appendonly yes
61    healthcheck:
62      test: ["CMD", "redis-cli", "ping"]
63      interval: 5s
64      timeout: 3s
65      retries: 5
66
67networks:
68  smallest-network:
69    driver: bridge
70    name: smallest-network

Step 5: Start Services

Launch all services with Docker Compose:

$docker compose up -d
First Time Startup
Subsequent Startups

First startup will take 3-5 minutes as the system:

  1. Pulls container images (~15-25 GB, includes TTS models)
  2. Initializes GPU and loads models

Models are embedded in the container - no separate download needed.

Step 6: Monitor Startup

Watch the logs to monitor startup progress:

$docker compose logs -f

Look for these success indicators:

1

Redis Ready

redis-server  | Ready to accept connections
2

License Proxy Ready

license-proxy  | License validated successfully
license-proxy  | Server listening on port 3369
3

Lightning TTS Ready

lightning-tts  | Model loaded successfully
lightning-tts  | Server ready on port 8876
4

API Server Ready

api-server  | Connected to Lightning TTS
api-server  | API server listening on port 7100

Press Ctrl+C to stop following logs.

Step 7: Verify Installation

Check that all containers are running:

$docker compose ps

Expected output:

NAME                IMAGE                                         STATUS
api-server          quay.io/smallestinc/self-hosted-api-server    Up
license-proxy       quay.io/smallestinc/license-proxy             Up
lightning-tts        quay.io/smallestinc/lightning-tts             Up
redis-server        redis:7-alpine                                Up (healthy)

Step 8: Test API

Test the API with a sample request:

$curl -X POST http://localhost:7100/v1/speak \
>  -H "Authorization: Token ${LICENSE_KEY}" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "text": "Hello, this is a test of the text-to-speech service.",
>    "voice": "default"
>  }'

Or use the health check endpoint first:

$curl http://localhost:7100/health

Expected response: {"status": "healthy"}

Common Startup Issues

GPU Not Found

Error: could not select device driver "nvidia"

Solution:

$sudo systemctl restart docker
$docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

If this fails, reinstall NVIDIA Container Toolkit.

License Validation Failed

Error: License validation failed

Solution:

  • Verify LICENSE_KEY in .env is correct
  • Check internet connectivity
  • Ensure firewall allows HTTPS to api.smallest.ai
Port Already in Use

Error: port is already allocated

Solution: Check what’s using the port:

$sudo lsof -i :7100

Either stop the conflicting service or change the port in docker-compose.yml

Managing Your Deployment

Stop Services

$docker compose stop

Restart Services

$docker compose restart

View Logs

$docker compose logs -f [service-name]

Examples:

$docker compose logs -f api-server
$docker compose logs -f lightning-tts

Update Images

Pull latest images and restart:

$docker compose pull
$docker compose up -d

Remove Deployment

Stop and remove all containers:

$docker compose down

Remove containers and volumes:

$docker compose down -v

Using -v flag will delete all data. Models will need to be re-downloaded on next startup.

What’s Next?

TTS Configuration

Customize your TTS deployment with advanced configuration options

TTS Services Overview

Learn about each TTS service component in detail

TTS Troubleshooting

Debug common issues and optimize performance

API Reference

Integrate with your applications using the API