Documentació / Primers passos

Instal·lació

Instal·la Rainy amb Docker Compose, o executa'l directament amb Python a Linux, macOS o Windows.

Pots executar Rainy de dues maneres. Docker Compose és la via recomanada: la pila porta la seva pròpia base de dades MySQL 8.4, ffmpeg, l'eina fpcalc (empremtes acústiques) i l'entorn d'execució de JavaScript Deno, així que no cal instal·lar res més. La via de Python necessita Python 3.11 o una versió posterior i ho guarda tot en un únic fitxer SQLite, que és ideal per a un ordinador personal.

Totes dues vies arrenquen el servidor al port 6969 i necessiten una carpeta de música a la màquina que executa Rainy.

Opció A: Docker Compose

1. Clona el repositori i entra a la carpeta. Cal tenir instal·lats Git i el complement de Docker Compose.

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

2. Obre .env i defineix aquests quatre valors abans d'iniciar:

   Configuració	Què hi has de posar
   FLASK_SECRET_KEY	Una clau aleatòria d'almenys 32 caràcters. Rainy no s'inicia sense ella.
   MYSQL_PASSWORD	Una contrasenya segura per a l'usuari de la base de dades de Rainy.
   MYSQL_ROOT_PASSWORD	Una contrasenya segura diferent per a l'usuari root de MySQL.
   MUSIC_LIBRARY_PATH	La ruta absoluta a la teva carpeta de música, o ./music per a una biblioteca buida.

   Per generar una clau de sessió, executa python3 -c "import secrets; print(secrets.token_hex(32))" i enganxa la sortida després de FLASK_SECRET_KEY=.

3. Si l'equip no té una GPU NVIDIA, elimina tot el bloc deploy: sota el servei app a compose.yaml. Per defecte sol·licita dispositius NVIDIA, i Compose no s'iniciarà sense el NVIDIA Container Toolkit. Sense ell, Rainy analitza els espectacles de llums amb la CPU. Per a la configuració de la GPU, consulta acceleració per GPU.

4. Construeix i inicia la pila:

   docker compose up --build -d
   

5. Obre http://localhost:6969. Si has canviat RAINY_PORT, fes servir aquest port. Completa el formulari de configuració per crear el compte d'administrador i introdueix /music com a ruta de la biblioteca. Aquí és on apareix dins del contenidor la carpeta de MUSIC_LIBRARY_PATH.

6. Ves a Configuració > Manteniment i executa Escaneig ràpid per indexar els fitxers que ja hi ha a la carpeta.

El contenidor app espera que la base de dades estigui en bon estat, inicialitza l'esquema i després arrenca Gunicorn. La teva música es queda a la carpeta de l'amfitrió; la base de dades viu al volum de Docker mysql_data.

Compose només passa a dins del contenidor les variables que apareixen a app.environment. Per definir qualsevol altra opció RAINY_* amb Docker, afegeix-la a aquesta llista de compose.yaml i torna a executar docker compose up -d. Consulta configuració.

Opció B: Python amb SQLite

Instal·la primer aquests components:

• Python 3.11 o una versió posterior.
• ffmpeg al teu PATH. Rainy l'utilitza per processar l'àudio.
• Un entorn d'execució de JavaScript per a les importacions de YouTube: Deno, Node.js o Bun. Sense cap d'ells, la majoria de formats de YouTube fallen amb HTTP 403.
• fpcalc (Chromaprint), opcional. Rainy l'utilitza per reconèixer la mateixa cançó d'una altra font. Posa'l al PATH o a la carpeta bin del projecte. Sense ell, només compten com a duplicats els fitxers idèntics byte a byte.

Linux i macOS

1. Clona el repositori i entra a la carpeta.

2. Crea .env i defineix el backend de la base de dades. Copia la plantilla i obre .env:

   cp .env.example .env
   

   Descomenta RAINY_DB=sqlite. Sense això, les línies MYSQL_* actives de la plantilla seleccionen MySQL i Rainy intenta connectar-se a un servidor de base de dades.

3. Inicia Rainy amb el llançador. Crea .venv, instal·la els requisits i escriu una FLASK_SECRET_KEY segura a .env si el valor falta o és feble:

   ./start.sh
   

   Per fer servir un intèrpret concret, defineix PYTHON=python3.12 ./start.sh.

4. Obre http://localhost:6969, crea el compte d'administrador i introdueix la ruta absoluta a la teva carpeta de música. La carpeta ha d'existir ja. Després executa Configuració > Manteniment > Escaneig ràpid.

Per a un servidor permanent, executa ./start.sh --gunicorn. L'opció --gunicorn només és compatible amb el llançador de Linux i macOS.

Windows

1. Clona el repositori i obre la carpeta a l'Explorador de fitxers.
2. Crea .env copiant .env.example, després descomenta RAINY_DB=sqlite i defineix tu mateix FLASK_SECRET_KEY. A diferència de start.sh, start.bat no genera la clau. Fes servir un valor aleatori de 32 caràcters o més.
3. Fes doble clic a start.bat o executa'l des d'una finestra d'ordres. Crea .venv, instal·la els requisits i inicia app.py.
4. Obre http://localhost:6969, completa la configuració i executa un escaneig ràpid tal com s'ha explicat abans.

Execució des d'un entorn virtual

Si prefereixes gestionar tu mateix l'entorn, els llançadors fan els mateixos passos:

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

A Windows, fes servir py -m venv .venv i .venv\Scripts\activate.

Ús de MySQL

Si ja tens MySQL 8 en marxa, defineix RAINY_DB=mysql a .env i omple MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD i MYSQL_DATABASE. L'usuari de la base de dades ha de poder crear i modificar taules en aquesta base de dades.

Actualització

Amb Docker, fes una còpia de seguretat del volum mysql_data, del teu .env i de la carpeta de música, i després executa:

git pull
docker compose up --build -d

Evita docker compose down -v, que esborra el volum de la base de dades. Amb la instal·lació de Python, executa git pull i després ./start.sh de nou. El llançador reinstal·la els requisits que hagin canviat.

Resolució de problemes

Per a cada configuració que llegeix Rainy, consulta configuració. Quan el servidor respongui, continua amb primera execució.

Relacionat

• Visió general
• Primera execució
• Configuració
• Acceleració per GPU