Skip to main content

​
Overview

This guide walks you through deploying Smallest Self-Host using Docker Compose. You’ll have a fully functional speech-to-text 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-self-host
cd ~/smallest-self-host

​
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

Best for: Fast inference, real-time applicationsCreate a docker-compose.yml file:
docker-compose.yml
version: "3.8"

services:
  lightning-asr:
    image: quay.io/smallestinc/lightning-asr:latest
    ports:
      - "2233:2233"
    environment:
      - MODEL_URL=${MODEL_URL}
      - LICENSE_KEY=${LICENSE_KEY}
      - REDIS_URL=redis://redis:6379
      - PORT=2233
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped
    networks:
      - smallest-network

  api-server:
    image: quay.io/smallestinc/self-hosted-api-server:latest
    container_name: api-server
    environment:
      - LICENSE_KEY=${LICENSE_KEY}
      - LIGHTNING_ASR_BASE_URL=http://lightning-asr:2233
      - API_BASE_URL=http://license-proxy:3369
    ports:
      - "7100:7100"
    networks:
      - smallest-network
    restart: unless-stopped
    depends_on:
      - lightning-asr
      - license-proxy

  license-proxy:
    image: quay.io/smallestinc/license-proxy:latest
    container_name: license-proxy
    environment:
      - LICENSE_KEY=${LICENSE_KEY}
    networks:
      - smallest-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    networks:
      - smallest-network
    restart: unless-stopped
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

networks:
  smallest-network:
    driver: bridge
    name: smallest-network

​
Step 5: Additional Configuration for Lightning ASR

Add the model URL to your .env file (required for Lightning ASR):
echo "MODEL_URL=your-model-url-here" >> .env
The MODEL_URL is provided by Smallest.ai support.

​
Step 6: Start Services

Launch all services with Docker Compose: 
docker compose up -d

​
Step 7: Monitor Startup

Watch the logs to monitor startup progress: 
docker compose logs -f
Look for these success indicators:
1

Redis Ready

redis-1  | Ready to accept connections
2

License Proxy Ready

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

Model Service Ready

Lightning ASR:
lightning-asr-1  | Model loaded successfully
lightning-asr-1  | Server ready on port 2233
4

API Server Ready

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

​
Common Startup Issues

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.
Error: License validation failedSolution:
  • Verify LICENSE_KEY in .env is correct
  • Check internet connectivity
  • Ensure firewall allows HTTPS to console-api.smallest.ai
Error: Failed to download modelSolution:
  • Verify MODEL_URL in .env is correct
  • Check disk space: df -h
  • Check internet connectivity
Error: port is already allocatedSolution: 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-asr

​
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 (including downloaded models): 
docker compose down -v
Using -v flag will delete all data including downloaded models. They will need to be re-downloaded on next startup.

​
What’s Next?

STT Configuration

Customize your deployment with advanced configuration options

STT Services Overview

Learn about each service component in detail

STT Troubleshooting

Debug common issues and optimize performance

API Reference

Integrate with your applications using the API