{"id":50568212,"url":"https://github.com/spacecodee/acestep-compose-docker","last_synced_at":"2026-06-04T16:30:54.475Z","repository":{"id":348963660,"uuid":"1200512683","full_name":"spacecodee/acestep-compose-docker","owner":"spacecodee","description":"Docker Compose configuration to deploy ACE-Step 1.5 AI music generation model with GPU support, ready for AI Servers","archived":false,"fork":false,"pushed_at":"2026-04-03T16:20:18.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T18:34:16.006Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spacecodee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T13:58:21.000Z","updated_at":"2026-04-03T16:20:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spacecodee/acestep-compose-docker","commit_stats":null,"previous_names":["spacecodee/acestep-compose-docker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/spacecodee/acestep-compose-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacecodee%2Facestep-compose-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacecodee%2Facestep-compose-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacecodee%2Facestep-compose-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacecodee%2Facestep-compose-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spacecodee","download_url":"https://codeload.github.com/spacecodee/acestep-compose-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacecodee%2Facestep-compose-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33914543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T16:30:52.891Z","updated_at":"2026-06-04T16:30:54.467Z","avatar_url":"https://github.com/spacecodee.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# acestep-compose-docker\n\nDocker 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.\n\n## Overview\n\nThis repository provides a production-friendly container setup for ACE-Step 1.5 with:\n\n- NVIDIA GPU passthrough (CUDA 12.8 by default, switchable to CUDA 13)\n- Official ACE-Step dependency flow via `uv sync`\n- Gradio UI and REST API support\n- Persistent model cache and output storage through bind mounts\n- Run-mode switching via environment variables (`gradio`, `api`, `both`)\n\n## Requirements\n\n- Docker 24+\n- Docker Compose v2+\n- NVIDIA Container Toolkit installed and configured\n- NVIDIA driver compatible with your selected CUDA base (`CUDA_BASE_VERSION`, default `12.8.0`)\n\n## Quick Start\n\n1. Copy environment defaults:\n\n\t```bash\n\tcp .env.example .env\n\t```\n\n2. Build and start in detached mode:\n\n\t```bash\n\tdocker compose up --build -d\n\t```\n\n3. Open Gradio:\n\n\t- http://localhost:7860 (or your configured `PORT`)\n\nOn first run, model downloads can be large (roughly 10-20 GB). The `./models` volume avoids re-downloading across restarts.\n\n## Common Commands\n\nUse these commands in the project root (`acestep-compose-docker`):\n\n```bash\n# Rebuild image without cache (recommended after Dockerfile/build-arg changes)\ndocker compose build --no-cache acestep\n\n# Recreate and start service in background\ndocker compose up -d --force-recreate acestep\n\n# Full reset + rebuild + start\ndocker compose down\ndocker compose build --no-cache acestep\ndocker compose up -d acestep\n\n# Service status\ndocker compose ps\n\n# Follow service logs (compose service name)\ndocker compose logs -f acestep\n\n# Show only recent logs (last 10 minutes)\ndocker compose logs --since=10m acestep\n\n# Follow container logs (container name)\ndocker logs -f acestep_app\n\n# Enter container shell\ndocker compose exec acestep bash\n\n# Check mapped host port for Gradio/API\ndocker compose port acestep 7860\ndocker compose port acestep 8000\n\n# Quick health status\ndocker inspect -f '{{.State.Health.Status}}' acestep_app\n```\n\n## CPU-only Testing\n\nUse the CPU override file for environments without a GPU:\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.cpu.yml up --build\n```\n\n## Dependency Installation (Official ACE-Step Flow)\n\nThis wrapper now follows ACE-Step docs for Linux/macOS inside the container:\n\n- Install `uv`\n- Run `uv sync` to resolve and install dependencies\n- Start services with `uv run ...`\n\nBy 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.\n\nFor 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.\n\nAdditionally, 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-\u003etorchcodec` loader failures for MP3 export.\n\nYou can switch Docker base CUDA without changing files by setting `CUDA_BASE_VERSION` in `.env` (for example `12.8.0` or `13.0.0`).\n\nThis avoids duplicate/conflicting manual installs from custom `pip` steps and stays aligned with upstream.\n\n## Startup Model Pre-Download\n\nOn container startup, this wrapper can pre-download models before launching services.\n\nDefault behavior (equivalent commands):\n\n```bash\nuv run acestep-download --model acestep-v15-xl-base\nuv run acestep-download --model acestep-5Hz-lm-4B\n```\n\nConfigure in `.env`:\n\n- `ACESTEP_AUTO_DOWNLOAD_MODELS=true|false`\n- `ACESTEP_PRELOAD_MODELS=acestep-v15-xl-base,acestep-5Hz-lm-4B`\n- `ACESTEP_PRELOAD_BACKGROUND=true|false` (recommended `true` on Lightning so UI starts sooner)\n- `ACESTEP_PRELOAD_FATAL=true|false` (when `true`, startup fails if preload fails)\n- `ACESTEP_REPAIR_INVALID_MODELS=true|false` (force re-download if a model folder exists but is invalid/incomplete)\n\nDownloaded checkpoints are persisted in `./checkpoints`.\n\nAt runtime, Gradio starts with `ACESTEP_CONFIG_PATH` and `ACESTEP_LM_MODEL_PATH` as default selected models.\n\n## flash-attn\n\nNo OS change is required. You can keep Ubuntu 22.04 and choose one of these modes in `.env`:\n\n- Keep `ACESTEP_USE_FLASH_ATTENTION=true` in `.env` (enabled by default).\n- If your platform needs source compilation for GPU dependencies, set `CUDA_VARIANT=devel`.\n\nACE-Step auto-detects whether `flash_attn` is actually available and falls back safely when it is not.\n\n## Run Modes\n\nSet `RUN_MODE` in `.env`:\n\n| RUN_MODE | Behavior | Exposed Endpoint(s) |\n| --- | --- | --- |\n| `gradio` | Runs Gradio UI only | `http://localhost:${PORT}` |\n| `api` | Runs API service only | `http://localhost:${ACESTEP_API_PORT}` |\n| `both` | Runs API in background + Gradio in foreground | `http://localhost:${PORT}` and `http://localhost:${ACESTEP_API_PORT}` |\n\n## ACE-Step .env Compatibility\n\nACE-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:\n\n- 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.\n\n- `ACESTEP_CONFIG_PATH`\n- `ACESTEP_LM_MODEL_PATH`\n- `ACESTEP_INIT_LLM`\n- `ACESTEP_DOWNLOAD_SOURCE`\n- `ACESTEP_API_KEY`\n- `PORT`\n- `SERVER_NAME`\n- `LANGUAGE`\n- `ACESTEP_API_HOST`\n- `ACESTEP_API_PORT`\n\nThis keeps the Docker Compose setup aligned with ACE-Step documentation while still adding container-specific control via `RUN_MODE`.\n\n## Volumes\n\n- `./models:/root/.cache/huggingface`\n  - Persists HuggingFace model cache between container restarts/rebuilds.\n- `./checkpoints:/app/checkpoints`\n\t- Persists ACE-Step model checkpoints and avoids repeated startup downloads.\n- `./outputs:/app/outputs`\n  - Persists generated audio outputs.\n\n## Lightning.ai Notes\n\n- Open inbound ports `7860` (Gradio) and `8000` (API) in your Lightning.ai Studio.\n- If you override ports in `.env`, open `PORT` and `ACESTEP_API_PORT` values instead.\n- Keep `HOST_BIND_IP=0.0.0.0` so Docker publishes ports on all interfaces (required for public Cloudspaces URLs).\n- GPU is automatically consumed through the NVIDIA runtime in `docker-compose.yml`.\n- For CPU validation in Studio or local dev, use the override compose file described above.\n- 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.\n- Browser warning `Permissions-Policy: Unrecognized feature 'browsing-topics'` is proxy/browser related and can be ignored.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspacecodee%2Facestep-compose-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspacecodee%2Facestep-compose-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspacecodee%2Facestep-compose-docker/lists"}