Shao

Environment Setup

This document records the recommended runtime environment for the current release and explains how to configure a clean NVIDIA NGC container into a working setup.

It corresponds to the current repository codebase and only covers the dependencies needed for frontend/backend inference and local development. It does not cover the training environment.

[!TIP] There are currently two supported environment setup paths:

  1. Build an environment image from the repository-level Dockerfile.
  2. Follow the steps in this document to manually install dependencies inside a clean NGC container.

The rest of this document describes the manual setup path.

1. Base Environment

The current recommended starting point is the NVIDIA NGC PyTorch container:

This base image already includes the core CUDA / PyTorch / Transformer Engine stack used by the project, so it is not recommended to reinstall torch or transformer_engine on top of it.

2. Project Directory

The project code can be placed anywhere. All paths below are described relative to the repository root.

For example:

git clone https://github.com/Shao-Music-AI/Shao.git

cd Shao

The rest of this document assumes repository-relative paths rather than any fixed host-machine directory.

3. Python Dependencies

The additional Python dependencies for the current project are listed in requirements.txt at the repository root.

Install them inside the NGC container with:

python3 -m pip install --break-system-packages -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

4. System Dependencies

4.1 ffmpeg

The backend calls ffmpeg to export MP3 files after generating WAV files, so it must be installed:

apt update
apt install -y ffmpeg

4.2 SSH (optional)

If you want to SSH directly into the container instead of first entering the host machine and then using docker exec, you can additionally install and start an SSH service.

For example:

apt update
apt install -y openssh-server
mkdir -p /var/run/sshd

This is not required to run the project. It is only a convenience for development and remote debugging.

5. Node.js

The frontend currently runs through the Vite development server, so Node.js is required.

The currently verified version is:

Install it with:

curl -fsSLO https://nodejs.org/dist/v24.15.0/node-v24.15.0-linux-x64.tar.xz
mkdir -p /usr/local/lib/nodejs
tar -xJf node-v24.15.0-linux-x64.tar.xz -C /usr/local/lib/nodejs
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/node /usr/local/bin/node
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/npm /usr/local/bin/npm
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/npx /usr/local/bin/npx
ln -sf /usr/local/lib/nodejs/node-v24.15.0-linux-x64/bin/corepack /usr/local/bin/corepack

Notes:

Verify the installation:

node -v
npm -v
npx -v

6. Frontend Dependencies

From the repository root, run:

cd frontend
npm install

The current frontend is intended to run in development mode:

npm run dev

7. Model File Layout

The current code resolves tokenizer files, decoder configuration, and checkpoints through repository-relative paths.

Make sure the directory structure looks like this:

Shao/
├── backend/
├── frontend/
├── core/
├── models/
│   ├── Decoder/
│   ├── Megatron/
│   └── Tokenizer/
└── checkpoints/
    ├── ...
    └── ...

Important notes:

8. Running the Project

8.1 Start the backend

cd backend
bash run_backend.sh

By default this starts:

Stop all backend processes with:

bash run_backend.sh stop

8.2 Start the frontend

cd frontend
npm run dev

By default:

9. Advanced Docker Run Example

If you want to mount a host-side project directory into the container, you can use a command like this:

docker run -d \
  --name shao_dev \
  --gpus all \
  -p 2222:22 \
  -p 30869:30869 \
  -p 8889:8889 \
  -v /path/to/your/workspace:/workspace \
  <your-image> \
  /usr/sbin/sshd -D

Adjust the following for your own environment: