https://github.com/spacecodee/acestep-compose-docker
Docker Compose configuration to deploy ACE-Step 1.5 AI music generation model with GPU support, ready for AI Servers
https://github.com/spacecodee/acestep-compose-docker
Last synced: 16 days ago
JSON representation
Docker Compose configuration to deploy ACE-Step 1.5 AI music generation model with GPU support, ready for AI Servers
- Host: GitHub
- URL: https://github.com/spacecodee/acestep-compose-docker
- Owner: spacecodee
- Created: 2026-04-03T13:58:21.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T16:20:18.000Z (3 months ago)
- Last Synced: 2026-04-03T18:34:16.006Z (3 months ago)
- Language: Shell
- Size: 114 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# acestep-compose-docker
Docker Compose wrapper to deploy [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) for AI music generation on GPU-enabled environments like Lightning.ai Studios.
## Overview
This repository provides a production-friendly container setup for ACE-Step 1.5 with:
- NVIDIA GPU passthrough (CUDA 12.8 by default, switchable to CUDA 13)
- Official ACE-Step dependency flow via `uv sync`
- Gradio UI and REST API support
- Persistent model cache and output storage through bind mounts
- Run-mode switching via environment variables (`gradio`, `api`, `both`)
## Requirements
- Docker 24+
- Docker Compose v2+
- NVIDIA Container Toolkit installed and configured
- NVIDIA driver compatible with your selected CUDA base (`CUDA_BASE_VERSION`, default `12.8.0`)
## Quick Start
1. Copy environment defaults:
```bash
cp .env.example .env
```
2. Build and start in detached mode:
```bash
docker compose up --build -d
```
3. Open Gradio:
- http://localhost:7860 (or your configured `PORT`)
On first run, model downloads can be large (roughly 10-20 GB). The `./models` volume avoids re-downloading across restarts.
## Common Commands
Use these commands in the project root (`acestep-compose-docker`):
```bash
# Rebuild image without cache (recommended after Dockerfile/build-arg changes)
docker compose build --no-cache acestep
# Recreate and start service in background
docker compose up -d --force-recreate acestep
# Full reset + rebuild + start
docker compose down
docker compose build --no-cache acestep
docker compose up -d acestep
# Service status
docker compose ps
# Follow service logs (compose service name)
docker compose logs -f acestep
# Show only recent logs (last 10 minutes)
docker compose logs --since=10m acestep
# Follow container logs (container name)
docker logs -f acestep_app
# Enter container shell
docker compose exec acestep bash
# Check mapped host port for Gradio/API
docker compose port acestep 7860
docker compose port acestep 8000
# Quick health status
docker inspect -f '{{.State.Health.Status}}' acestep_app
```
## CPU-only Testing
Use the CPU override file for environments without a GPU:
```bash
docker compose -f docker-compose.yml -f docker-compose.cpu.yml up --build
```
## Dependency Installation (Official ACE-Step Flow)
This wrapper now follows ACE-Step docs for Linux/macOS inside the container:
- Install `uv`
- Run `uv sync` to resolve and install dependencies
- Start services with `uv run ...`
By default, the image also installs `bitsandbytes` (controlled by `INSTALL_BITSANDBYTES=true`) so training paths can use 8-bit optimizers instead of falling back to standard AdamW.
For MP3/Opus/AAC export reliability with `torchaudio + torchcodec`, the image can also install CUDA 13 user-space runtime libs (`nvidia-cuda-runtime`, `nvidia-cuda-nvrtc`, `nvidia-nvjitlink`) when `INSTALL_TORCHCODEC_CUDA13_RUNTIME=true`. This avoids runtime errors such as missing `libnvrtc.so.13` on CUDA 12 base images, and is skipped automatically when the Docker base is already CUDA 13.
Additionally, the build applies a small runtime compatibility patch to ACE-Step's MP3 save path so temporary WAV generation uses `soundfile` directly (then `ffmpeg` encodes MP3), avoiding `torchaudio->torchcodec` loader failures for MP3 export.
You can switch Docker base CUDA without changing files by setting `CUDA_BASE_VERSION` in `.env` (for example `12.8.0` or `13.0.0`).
This avoids duplicate/conflicting manual installs from custom `pip` steps and stays aligned with upstream.
## Startup Model Pre-Download
On container startup, this wrapper can pre-download models before launching services.
Default behavior (equivalent commands):
```bash
uv run acestep-download --model acestep-v15-xl-base
uv run acestep-download --model acestep-5Hz-lm-4B
```
Configure in `.env`:
- `ACESTEP_AUTO_DOWNLOAD_MODELS=true|false`
- `ACESTEP_PRELOAD_MODELS=acestep-v15-xl-base,acestep-5Hz-lm-4B`
- `ACESTEP_PRELOAD_BACKGROUND=true|false` (recommended `true` on Lightning so UI starts sooner)
- `ACESTEP_PRELOAD_FATAL=true|false` (when `true`, startup fails if preload fails)
- `ACESTEP_REPAIR_INVALID_MODELS=true|false` (force re-download if a model folder exists but is invalid/incomplete)
Downloaded checkpoints are persisted in `./checkpoints`.
At runtime, Gradio starts with `ACESTEP_CONFIG_PATH` and `ACESTEP_LM_MODEL_PATH` as default selected models.
## flash-attn
No OS change is required. You can keep Ubuntu 22.04 and choose one of these modes in `.env`:
- Keep `ACESTEP_USE_FLASH_ATTENTION=true` in `.env` (enabled by default).
- If your platform needs source compilation for GPU dependencies, set `CUDA_VARIANT=devel`.
ACE-Step auto-detects whether `flash_attn` is actually available and falls back safely when it is not.
## Run Modes
Set `RUN_MODE` in `.env`:
| RUN_MODE | Behavior | Exposed Endpoint(s) |
| --- | --- | --- |
| `gradio` | Runs Gradio UI only | `http://localhost:${PORT}` |
| `api` | Runs API service only | `http://localhost:${ACESTEP_API_PORT}` |
| `both` | Runs API in background + Gradio in foreground | `http://localhost:${PORT}` and `http://localhost:${ACESTEP_API_PORT}` |
## ACE-Step .env Compatibility
ACE-Step already supports a rich `.env` contract upstream (for Gradio, API, and model behavior). This wrapper passes your `.env` directly into the container, so you can use official variables such as:
- The global `.env` in this wrapper is also mounted as `/app/.env` inside the container, so ACE-Step's native `.env` loader reads the same values.
- `ACESTEP_CONFIG_PATH`
- `ACESTEP_LM_MODEL_PATH`
- `ACESTEP_INIT_LLM`
- `ACESTEP_DOWNLOAD_SOURCE`
- `ACESTEP_API_KEY`
- `PORT`
- `SERVER_NAME`
- `LANGUAGE`
- `ACESTEP_API_HOST`
- `ACESTEP_API_PORT`
This keeps the Docker Compose setup aligned with ACE-Step documentation while still adding container-specific control via `RUN_MODE`.
## Volumes
- `./models:/root/.cache/huggingface`
- Persists HuggingFace model cache between container restarts/rebuilds.
- `./checkpoints:/app/checkpoints`
- Persists ACE-Step model checkpoints and avoids repeated startup downloads.
- `./outputs:/app/outputs`
- Persists generated audio outputs.
## Lightning.ai Notes
- Open inbound ports `7860` (Gradio) and `8000` (API) in your Lightning.ai Studio.
- If you override ports in `.env`, open `PORT` and `ACESTEP_API_PORT` values instead.
- Keep `HOST_BIND_IP=0.0.0.0` so Docker publishes ports on all interfaces (required for public Cloudspaces URLs).
- GPU is automatically consumed through the NVIDIA runtime in `docker-compose.yml`.
- For CPU validation in Studio or local dev, use the override compose file described above.
- If you get an initial HTTP 502 on the public URL, check container logs and wait for startup downloads/model initialization to finish before retrying.
- Browser warning `Permissions-Policy: Unrecognized feature 'browsing-topics'` is proxy/browser related and can be ignored.