Rainy
5
EN
Docs Download
All pages Configuration

Documentation Getting started

Configuration

Every environment variable Rainy reads, with its default and what it changes.

Rainy reads its settings from environment variables. On a Python install, the values in .env are loaded when the server starts. With Docker Compose, Compose reads .env for substitution and passes only the variables listed under app.environment into the container. Restart Rainy after you change a value. With Docker, run docker compose up -d so the container is recreated with the new environment.

Start from .env.example, which lists the settings most people change. The tables below cover everything the application code reads. A default shown as "unset" means that Rainy works without the variable and turns the related feature on or off accordingly.

Settings read only by the launcher scripts (start.sh, start.bat) or the Docker entrypoint are set in your shell. Values that only Compose uses, such as RAINY_PORT and MUSIC_LIBRARY_PATH, go in .env, because Compose reads that file for substitution. They are listed separately at the end.

Core and security

Variable Default What it does
FLASK_SECRET_KEY Empty Signs session cookies. Rainy refuses to start unless it is at least 32 characters and not a placeholder, unless RAINY_DEV is set. Generate one with python -c "import secrets; print(secrets.token_hex(32))".
RAINY_DEV Off Development mode. Accepts 1, true or yes. It allows a temporary random key that resets on every restart, and turns on the Werkzeug debugger when you run app.py. Do not use it on a server you expose.
SESSION_LIFETIME_DAYS 30 How long a sign-in lasts. The session extends each time it is used.

Database

Variable Default What it does
RAINY_DB Auto mysql or sqlite. When unset, Rainy uses MySQL if any MYSQL_* variable is set, and SQLite otherwise. Any other value stops startup with an error.
SQLITE_PATH data/rainy.db SQLite file path, relative to the project folder unless you give an absolute path.
MYSQL_HOST localhost MySQL host. You can add a port, as in 127.0.0.1:3306.
MYSQL_PORT 3306 MySQL port. If unset, a port written into MYSQL_HOST is used instead.
MYSQL_USER root MySQL user. Create a dedicated user rather than using root.
MYSQL_PASSWORD Empty MySQL password.
MYSQL_DATABASE rainy MySQL database name.
If MYSQL_USER is not set, Rainy connects as root. Set it to the dedicated account you created for Rainy.

Network and proxies

Variable Default What it does
RAINY_HTTP_PORT 6969 Port Rainy listens on when you run python app.py.
RAINY_COOKIE_SECURE Off Adds the Secure flag to session cookies, so browsers send them only over HTTPS. Turn it on when you serve Rainy over HTTPS.
RAINY_TRUST_PROXY Off Trusts the X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers. Turn it on only behind a reverse proxy you control, so per-IP limits see the real client. Never enable it when Rainy is reachable directly.
RAINY_CORS_ORIGINS Empty Comma-separated list of other origins allowed to call the API with credentials. API requests that change data from any other origin are rejected.

Media and import tools

Variable Default What it does
RAINY_YTDLP_AUTO_UPDATE On Keeps yt-dlp up to date. Rainy checks about every 12 hours while it runs. Set it to 0 to pin the installed version.
LASTFM_API_KEY Empty A free Last.fm API key for tags, similar artists and bios. Without it, Last.fm enrichment is skipped, and MusicBrainz is still used.

Rainy needs ffmpeg for audio processing, and a JavaScript runtime for YouTube imports. These are installed by the Docker image and are described on the installation page.

Lyrics and light show

Variable Default What it does
RAINY_WHISPER_MODEL base The faster-whisper model used to align lyrics to audio. Larger models are slower and more accurate.
RAINY_LYRICS_LANG Unset Forces the language used for lyric alignment, for example en. When unset, Rainy detects it from the audio.
RAINY_LIGHTSHOW_DEVICE auto Where light show analysis runs. auto uses a usable CUDA GPU and falls back to the CPU. cpu never uses the GPU. cuda uses the usable GPU with the most memory, and falls back to the CPU if there is none. cuda:N uses GPU number N, or the CPU if that GPU is unusable.
RAINY_LIGHTSHOW_THREADS CPU cores, up to 8 CPU worker threads for light show analysis. A value of 0 or a non-number falls back to the default.

For GPU setup and what to expect from each device value, see GPU acceleration.

Launchers and containers

These settings are read by start.sh, start.bat or the Docker files. Set the launcher variables in your shell. Set the Compose-only variables in .env.

Variable Default Where it applies
PYTHON Auto-detected start.sh. Interpreter to use for creating .venv, honored only if it is Python 3.11 or newer.
RAINY_USE_GUNICORN 0 start.sh. Set to 1 to serve with Gunicorn. The same as passing --gunicorn.
RAINY_GUNICORN_WORKERS 2 start.sh under Gunicorn. Number of worker processes.
RAINY_GUNICORN_THREADS 4 start.sh under Gunicorn. Threads per worker.
RAINY_GUNICORN_TIMEOUT 120 start.sh under Gunicorn. Seconds before a silent worker is restarted.
DATABASE_INIT_MAX_ATTEMPTS 30 Docker entrypoint. Attempts at creating or migrating the schema, two seconds apart, before the container gives up.
RAINY_PORT 6969 Compose sets the host port with this, and start.sh uses it for the Gunicorn port when RAINY_HTTP_PORT is unset.
MUSIC_LIBRARY_PATH ./music Compose only. The host folder mounted at /music.
MYSQL_ROOT_PASSWORD Required Compose only. Root password for the bundled MySQL service.

With Docker Compose, the app service also sets MYSQL_HOST to the bundled database, plus MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE and FLASK_SECRET_KEY. Any other RAINY_* setting must be added under app.environment in compose.yaml to take effect.