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

> Learn how to run VoiceStudio using Docker. This guide provides a complete setup and deployment process for the official VoiceStudio container image, simplifying your workflow.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/debpalash/VoiceStudio/blob/main/deploy/docker-compose.yml))

For complex deployments requiring GPU support, the repository provides [`deploy/docker-compose.yml`](https://github.com/debpalash/VoiceStudio/blob/main/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:

```bash
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:

```bash
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:

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

```

The image contains a [`torch-constraints.txt`](https://github.com/debpalash/VoiceStudio/blob/main/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:

```bash
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:

```bash
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:

```bash
docker logs -f omnivoice

```

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

```bash
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:

```bash
docker compose pull
docker compose up -d

```

Complete configuration details are documented in the repository at [`docs/install/docker.md`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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.