Documentation / Getting started

Installation

Install Rainy with Docker Compose, or run it directly with Python on Linux, macOS or Windows.

You can run Rainy in two ways. Docker Compose is the recommended path: the stack brings its own MySQL 8.4 database, ffmpeg, the fpcalc fingerprint tool and the Deno JavaScript runtime, so you install nothing else. The Python path needs Python 3.11 or newer and stores everything in a single SQLite file, which suits a personal machine.

Both paths start the server on port 6969 and need a music folder on the machine that runs Rainy.

Option A: Docker Compose

1. Clone the repository and enter the folder. Git and the Docker Compose plugin must be installed.

   git clone https://github.com/Rainer-Technologies/Rainy.git
   cd Rainy
   cp .env.example .env
   

2. Open .env and set these four values before you start:

   Setting	What to put there
   FLASK_SECRET_KEY	A random key of at least 32 characters. Rainy refuses to start without one.
   MYSQL_PASSWORD	A strong password for Rainy's database user.
   MYSQL_ROOT_PASSWORD	A different strong password for the MySQL root user.
   MUSIC_LIBRARY_PATH	An absolute path to your music folder, or ./music for an empty library.

   To generate a session key, run python3 -c "import secrets; print(secrets.token_hex(32))" and paste the output after FLASK_SECRET_KEY=.

3. If the host has no NVIDIA GPU, remove the whole deploy: block under the app service in compose.yaml. It requests NVIDIA devices by default, and Compose will not start without the NVIDIA Container Toolkit. Rainy analyses light shows on the CPU without it. For GPU setup, see GPU acceleration.

4. Build and start the stack:

   docker compose up --build -d
   

5. Open http://localhost:6969. If you changed RAINY_PORT, use that port instead. Complete the setup form to create the administrator account, and enter /music as the library path. This is where your MUSIC_LIBRARY_PATH folder appears inside the container.

6. Go to Settings > Maintenance and run Quick Scan to index the files already in the folder.

The app container waits for the database to be healthy, initialises the schema, and then starts Gunicorn. Your music stays in the folder on the host; the database lives in the mysql_data Docker volume.

Compose passes only the variables listed under app.environment into the container. To set any other RAINY_* option with Docker, add it to that list in compose.yaml and run docker compose up -d again. See configuration.

Option B: Python with SQLite

Install these first:

• Python 3.11 or newer.
• ffmpeg on your PATH. Rainy uses it to process audio.
• A JavaScript runtime for YouTube imports: Deno, Node.js or Bun. Without one, most YouTube formats fail with HTTP 403.
• fpcalc (Chromaprint), optional. Rainy uses it to recognise the same song from a different source. Put it on your PATH, or in the project's bin folder. Without it, only byte-identical files count as duplicates.

Linux and macOS

1. Clone the repository and enter the folder.

2. Create .env and set the database backend. Copy the template, then open .env:

   cp .env.example .env
   

   Uncomment RAINY_DB=sqlite. Without it, the active MYSQL_* lines in the template select MySQL instead, and Rainy tries to connect to a database server.

3. Start Rainy with the launcher. It creates .venv, installs the requirements, and writes a secure FLASK_SECRET_KEY into .env if the value is missing or weak:

   ./start.sh
   

   To use a specific interpreter, set PYTHON=python3.12 ./start.sh.

4. Open http://localhost:6969, create the administrator account, and enter the absolute path to your music folder. The folder must already exist. Then run Settings > Maintenance > Quick Scan.

For a persistent server, run ./start.sh --gunicorn instead. The --gunicorn option is supported by the Linux and macOS launcher only.

Windows

1. Clone the repository and open the folder in File Explorer.
2. Create .env by copying .env.example, then uncomment RAINY_DB=sqlite and set FLASK_SECRET_KEY yourself. Unlike start.sh, start.bat does not generate the key. Use a 32-character or longer random value.
3. Double-click start.bat, or run it from a Command Prompt. It creates .venv, installs the requirements and starts app.py.
4. Open http://localhost:6969, complete setup and run a Quick Scan as above.

Running from a virtual environment

If you prefer to manage the environment yourself, the launchers do the same steps:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python app.py

On Windows, use py -m venv .venv and .venv\Scripts\activate.

Using MySQL instead

If you already run MySQL 8, set RAINY_DB=mysql in .env and fill in MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE. The database user must be able to create and change tables in that database.

Updating

With Docker, back up the mysql_data volume, your .env and your music folder, then run:

git pull
docker compose up --build -d

Avoid docker compose down -v, which deletes the database volume. With the Python install, run git pull and then ./start.sh again. The launcher reinstalls any changed requirements.

Troubleshooting

For every setting Rainy reads, see configuration. Once the server responds, continue with first run.

Related

• Overview
• First run
• Configuration
• GPU acceleration