Documentación / Primeros pasos

Instalación

Instala Rainy con Docker Compose, o ejecútalo directamente con Python en Linux, macOS o Windows.

Puedes ejecutar Rainy de dos maneras. Docker Compose es la opción recomendada: el stack incluye su propia base de datos MySQL 8.4, ffmpeg, la herramienta fpcalc (huellas acústicas) y el entorno de ejecución de JavaScript Deno, así que no tienes que instalar nada más. La vía de Python necesita Python 3.11 o superior y guarda todo en un único archivo SQLite, lo que resulta adecuado para un equipo personal.

Ambas vías inician el servidor en el puerto 6969 y necesitan una carpeta de música en la máquina donde se ejecuta Rainy.

Opción A: Docker Compose

1. Clona el repositorio y entra en la carpeta. Deben estar instalados Git y el plugin de Docker Compose.

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

2. Abre .env y define estos cuatro valores antes de iniciar:

   Ajuste	Qué poner
   FLASK_SECRET_KEY	Una clave aleatoria de al menos 32 caracteres. Rainy no arranca sin ella.
   MYSQL_PASSWORD	Una contraseña segura para el usuario de la base de datos de Rainy.
   MYSQL_ROOT_PASSWORD	Una contraseña segura distinta para el usuario root de MySQL.
   MUSIC_LIBRARY_PATH	Una ruta absoluta a tu carpeta de música, o ./music para una biblioteca vacía.

   Para generar una clave de sesión, ejecuta python3 -c "import secrets; print(secrets.token_hex(32))" y pega el resultado después de FLASK_SECRET_KEY=.

3. Si el equipo no tiene GPU NVIDIA, elimina todo el bloque deploy: bajo el servicio app en compose.yaml. Por defecto solicita dispositivos NVIDIA, y Compose no arrancará sin el NVIDIA Container Toolkit. Sin él, Rainy analiza los espectáculos de luces en la CPU. Para la configuración de la GPU, consulta aceleración por GPU.

4. Compila e inicia el stack:

   docker compose up --build -d
   

5. Abre http://localhost:6969. Si cambiaste RAINY_PORT, usa ese puerto en su lugar. Completa el formulario de configuración para crear la cuenta de administrador e introduce /music como ruta de la biblioteca. Aquí es donde aparece tu carpeta MUSIC_LIBRARY_PATH dentro del contenedor.

6. Ve a Ajustes > Mantenimiento y ejecuta Escaneo rápido para indexar los archivos que ya hay en la carpeta.

El contenedor app espera a que la base de datos esté en buen estado, inicializa el esquema y después arranca Gunicorn. Tu música se queda en la carpeta del equipo anfitrión; la base de datos vive en el volumen de Docker mysql_data.

Compose solo pasa al contenedor las variables que aparecen en app.environment. Para definir cualquier otra opción RAINY_* con Docker, añádela a esa lista en compose.yaml y ejecuta de nuevo docker compose up -d. Consulta configuración.

Opción B: Python con SQLite

Instala primero estos programas:

• Python 3.11 o superior.
• ffmpeg en tu PATH. Rainy lo usa para procesar el audio.
• Un entorno de ejecución de JavaScript para las importaciones de YouTube: Deno, Node.js o Bun. Sin ninguno, la mayoría de formatos de YouTube fallan con HTTP 403.
• fpcalc (Chromaprint), opcional. Rainy lo usa para reconocer la misma canción de otra fuente. Ponlo en tu PATH o en la carpeta bin del proyecto. Sin él, solo cuentan como duplicados los archivos idénticos byte a byte.

Linux y macOS

1. Clona el repositorio y entra en la carpeta.

2. Crea .env y define el backend de base de datos. Copia la plantilla y después abre .env:

   cp .env.example .env
   

   Descomenta RAINY_DB=sqlite. Sin esa línea, las líneas MYSQL_* activas de la plantilla seleccionan MySQL en su lugar, y Rainy intenta conectarse a un servidor de base de datos.

3. Inicia Rainy con el lanzador. Crea .venv, instala los requisitos y escribe una FLASK_SECRET_KEY segura en .env si el valor falta o es débil:

   ./start.sh
   

   Para usar un intérprete concreto, define PYTHON=python3.12 ./start.sh.

4. Abre http://localhost:6969, crea la cuenta de administrador e introduce la ruta absoluta a tu carpeta de música. La carpeta debe existir ya. Después ejecuta Ajustes > Mantenimiento > Escaneo rápido.

Para un servidor persistente, ejecuta ./start.sh --gunicorn en su lugar. La opción --gunicorn solo la admite el lanzador de Linux y macOS.

Windows

1. Clona el repositorio y abre la carpeta en el Explorador de archivos.
2. Crea .env copiando .env.example, descomenta RAINY_DB=sqlite y define tú mismo FLASK_SECRET_KEY. A diferencia de start.sh, start.bat no genera la clave. Usa un valor aleatorio de 32 caracteres o más.
3. Haz doble clic en start.bat o ejecútalo desde el Símbolo del sistema. Crea .venv, instala los requisitos e inicia app.py.
4. Abre http://localhost:6969, completa la configuración y ejecuta un escaneo rápido como se indicó antes.

Ejecutar desde un entorno virtual

Si prefieres gestionar tú el entorno, los lanzadores hacen los mismos pasos:

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

En Windows, usa py -m venv .venv y .venv\Scripts\activate.

Usar MySQL en su lugar

Si ya usas MySQL 8, define RAINY_DB=mysql en .env y rellena MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD y MYSQL_DATABASE. El usuario de la base de datos debe poder crear y modificar tablas en esa base de datos.

Actualizar

Con Docker, haz una copia de seguridad del volumen mysql_data, de tu .env y de tu carpeta de música, y después ejecuta:

git pull
docker compose up --build -d

Evita docker compose down -v, que elimina el volumen de la base de datos. Con la instalación de Python, ejecuta git pull y luego ./start.sh de nuevo. El lanzador reinstala los requisitos que hayan cambiado.

Solución de problemas

Para cada ajuste que lee Rainy, consulta configuración. Cuando el servidor responda, continúa con la primera ejecución.

Relacionado

• Descripción general
• Primera ejecución
• Configuración
• Aceleración por GPU