Can VoiceStudio Be Run Using Docker? Complete Setup and Deployment Guide

Yes, VoiceStudio can be run using Docker via the official container image ghcr.io/debpalash/omnivoice-studio, which packages the Python backend, compiled frontend assets, and serves the web interface on port 3900 without requiring host-side dependencies.

VoiceStudio by debpalash is an open-source voice processing toolkit that provides first-class Docker support for streamlined deployment. Whether you need a quick CPU-based installation or a GPU-accelerated production setup, running VoiceStudio using Docker eliminates manual dependency management and ensures consistent environments across development and production systems.

VoiceStudio Docker Architecture Overview

Multi-Stage Build Configuration (deploy/Dockerfile)

The container definition resides in deploy/Dockerfile and implements a multi-stage build strategy to minimize image size. This configuration sets the PYTHONPATH environment variable, defines HF_HOME=/app/omnivoice_data/huggingface for model persistence, and exposes port 3900 for HTTP traffic. The build process copies the Python backend and compiled frontend assets into a minimal runtime image optimized for production use.

Docker Compose Orchestration (deploy/docker-compose.yml)

For complex deployments requiring GPU support, the repository provides deploy/docker-compose.yml. This file orchestrates the VoiceStudio service with configurable profiles, including a gpu profile that automatically configures NVIDIA or ROCm runtime support when invoked with --profile gpu.

Step-by-Step VoiceStudio Docker Setup

1. Pull the Official Image

The VoiceStudio image is published on both Docker Hub (palashdeb/omnivoice-studio) and GitHub Container Registry. Pull the latest version from GHCR:

docker pull ghcr.io/debpalash/omnivoice-studio:latest

2. Run VoiceStudio Without GPU

For standard CPU-only operation, start the container in detached mode with port mapping:

docker run -d --name omnivoice -p 3900:3900 ghcr.io/debpalash/omnivoice-studio:latest

Once initialized, open http://localhost:3900 in your browser to access the VoiceStudio web interface.

3. Enable GPU Support (NVIDIA/ROCm)

To run VoiceStudio using Docker with GPU acceleration for faster inference, pass the --gpus all runtime flag:

docker run -d --name omnivoice --gpus all -p 3900:3900 ghcr.io/debpalash/omnivoice-studio:latest

The image contains a torch-constraints.txt file that ensures the correct PyTorch CUDA/ROCm build is used inside the container. Alternatively, use Docker Compose with the GPU profile:

docker compose --profile gpu up -d

4. Persist Model Data with Volumes

Model weights are downloaded to /app/omnivoice_data/huggingface inside the container as defined by the HF_HOME environment variable. Mount a host volume to prevent re-downloading models after container restarts:

docker run -d --name omnivoice \
    -p 3900:3900 \
    -v $(pwd)/omnivoice_data:/app/omnivoice_data \
    ghcr.io/debpalash/omnivoice-studio:latest

Configuration and Maintenance

VoiceStudio exposes a health check endpoint at /health that reports the running version and service status. Monitor container logs in real-time:

docker logs -f omnivoice

To update your deployment, pull the latest image and recreate the container:

docker pull ghcr.io/debpalash/omnivoice-studio:latest
docker stop omnivoice && docker rm omnivoice

# Re-run your preferred docker run command

Or using Docker Compose:

docker compose pull
docker compose up -d

Complete configuration details are documented in the repository at docs/install/docker.md.

Summary

• Docker Support: VoiceStudio provides official Docker images at ghcr.io/debpalash/omnivoice-studio built from the multi-stage deploy/Dockerfile
• Default Port: The web UI is exposed on port 3900 and accessible at http://localhost:3900
• GPU Acceleration: Enable NVIDIA or ROCm support using --gpus all or the gpu Docker Compose profile
• Data Persistence: Mount host volumes to /app/omnivoice_data to retain HuggingFace model caches across container restarts
• Health Monitoring: Use the /health endpoint and docker logs to monitor application status

Frequently Asked Questions

Can VoiceStudio be run using Docker without installing Python locally?

Yes, the official Docker image bundles all Python dependencies, the backend runtime, and compiled frontend assets. You only need Docker installed on your host system; no local Python or Node.js installation is required to run VoiceStudio using Docker.

What is the default port for VoiceStudio Docker deployments?

The container exposes port 3900 as defined in deploy/Dockerfile and mapped in deploy/docker-compose.yml. Access the web interface at http://localhost:3900 after starting the container, or map a different host port using -p [host-port]:3900.

How do I enable GPU support when running VoiceStudio with Docker?

Pass the --gpus all runtime flag to docker run, or use docker compose --profile gpu up if using the provided compose file. The image contains specific PyTorch configurations via torch-constraints.txt to ensure compatibility with NVIDIA CUDA and AMD ROCm hardware.

Where are model weights stored in the VoiceStudio container?

The HF_HOME environment variable is set to /app/omnivoice_data/huggingface in the Dockerfile. Mount a host volume to /app/omnivoice_data to persist downloaded HuggingFace models across container restarts and avoid re-downloading on every start.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}