# Configuration Variables Explained

This document explains all required and optional configuration variables for running the Jelly Music App (JMA) on a new server or for a new user. **All paths and examples use the generic folder name `music app`—replace this with your actual folder name as needed.**

---

## Where to Find/Edit Config Files

| File/Setting           | Location in Project Structure                                  |
|-----------------------|----------------------------------------------------------------|
| .env                  | `music app/.env` or `music app/setup/.env.YOURNAME`            |
| Docker Compose        | `music app/docker-compose.yml` or `music app/setup/docker-compose.YOURNAME.yml` |
| Dockerfile            | `music app/Dockerfile` (backend), `music app/Dockerfile.ui` (frontend) |
| Source Code           | `music app/src/` (frontend), `music app/server/` (backend)      |
| Static Assets         | `music app/public/`                                              |
| Docs & Guides         | `music app/docs/`                                                |

---

## .env Variables

| Variable                  | Description                                                  | Example/Notes                                  | Where to Edit                       |
|--------------------------|--------------------------------------------------------------|------------------------------------------------|-------------------------------------|
| VITE_SERVER_URL          | URL of the frontend server                                   | http://localhost:5143                          | .env                                |
| VITE_BACKEND_URL         | URL of the backend API server (what the browser connects to) | http://localhost:5140                          | .env                                |
| VITE_BACKEND_URL_PROD    | Backend URL for production deployments                       | https://music.samcloud.ca                      | .env                                |
| VITE_FRONTEND_URL_PROD   | Frontend URL for production deployments                      | https://music.samcloud.ca                      | .env                                |
| SPOTIFY_CLIENT_ID        | Spotify API client ID                                        | (from Spotify Developer Dashboard)             | .env                                |
| SPOTIFY_CLIENT_SECRET    | Spotify API client secret                                    | (from Spotify Developer Dashboard)             | .env                                |
| JELLYFIN_URL             | Jellyfin server URL (API endpoint)                           | https://your-jellyfin-server.com               | .env                                |
| JELLYFIN_API_KEY         | Jellyfin API key                                             | (from Jellyfin user profile)                   | .env                                |
| OUTPUT_FORMAT            | Downloaded audio format                                      | mp3, flac, etc.                                | .env                                |
| OUTPUT_DIR               | Directory for downloads (inside container)                   | /app/downloads/girlfriend                      | .env and docker-compose volumes      |
| LOG_LEVEL                | Logging verbosity                                            | INFO, DEBUG, WARNING, ERROR                    | .env                                |
| WEBSOCKET_PORT           | Websocket port for backend                                   | 5144                                           | .env                                |
| NODE_ENV                 | Node environment                                             | development, production                        | .env                                |
| PLAYLIST_NAME            | Name for the user's playlist                                 | my_playlist, girlfriend_test_playlist           | .env                                |
| M3U_PLAYLIST_PATH        | Path for generated m3u playlists                             | /app/downloads/girlfriend/playlists            | .env and docker-compose volumes      |

---

## Docker Compose Variables

| Section     | Variable/Field      | Description                                  | Example/Notes                                  | Where to Edit                      |
|-------------|---------------------|----------------------------------------------|------------------------------------------------|------------------------------------|
| services    | backend/ports       | Backend port mapping                         | "5145:5145"                                   | docker-compose.YOURNAME.yml        |
| services    | backend/volumes     | Where to store music, temp, logs, etc.       | ./music:/music, ./temp:/temp                   | docker-compose.YOURNAME.yml        |
| services    | backend/environment | All .env variables above                     | See .env                                       | docker-compose.YOURNAME.yml        |
| services    | ui/ports            | Frontend port mapping                        | "5146:5146"                                   | docker-compose.YOURNAME.yml        |
| services    | ui/environment      | All .env variables above                     | See .env                                       | docker-compose.YOURNAME.yml        |

---

## Example Directory Structure

```
music app/
├── src/                    # Frontend source code
├── server/                 # Backend code
├── public/                 # Static assets
├── setup/                  # Per-user configs, setup script, example envs
│   ├── .env.YOURNAME
│   └── docker-compose.YOURNAME.yml
├── docs/                   # Documentation and guides
├── .env                    # Main env (optional, for production)
├── docker-compose.yml      # Main compose (optional, for production)
├── Dockerfile              # Backend Dockerfile
├── Dockerfile.ui           # Frontend Dockerfile
└── README.md               # Main readme
```

---

## What You MUST Change for Each Server/User
- **Spotify Keys:** Use your own or share for small use. Change if you hit rate limits.
- **Jellyfin URL/API Key:** Always set for your own server/user.
- **OUTPUT_DIR, PLAYLIST_NAME, M3U_PLAYLIST_PATH:** Always set unique for each user/server.
- **Ports:** Change if running multiple instances.
- **Volume paths in Compose:** Must match your server's directory structure.

---

## Optional/Advanced
- **LOG_LEVEL:** Use DEBUG for troubleshooting, INFO for normal use.
- **NODE_ENV:** Use production for live servers.
- **Other variables:** See comments in setup/.env.example and setup/docker-compose.example.yml.

---

For further help, see README.md or the guides in `docs/`.