From 6b745be835b1b5800e7c875e0385abd90e40741b Mon Sep 17 00:00:00 2001 From: Josh Patra Date: Fri, 30 Jan 2026 12:00:52 -0500 Subject: [PATCH] Consolidate Quick Start and add Contributing section --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 94 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index f08f9f8..e5eef8b 100644 --- a/README.md +++ b/README.md @@ -13,19 +13,26 @@ Please report all bugs as soon as possible, as the Jellyfin addition is entirely ## Quick Start +Using Docker (recommended): + ```bash -# 1. Configure environment +# 1. Pull the latest image +docker-compose pull + +# 2. Configure environment cp .env.example .env vi .env # Edit with your settings -# 2. Start services -docker-compose up -d --build +# 3. Start services +docker-compose up -d -# 3. Check status +# 4. Check status docker-compose ps docker-compose logs -f ``` +The proxy will be available at `http://localhost:5274`. + ### Nginx Proxy Setup (Required) This service only exposes ports internally. You **must** use nginx to proxy to it: @@ -134,11 +141,11 @@ Choose your preferred provider via the `MUSIC_SERVICE` environment variable. Add - Credentials for at least one music provider (IF NOT USING SQUIDWTF): - **Deezer**: ARL token from browser cookies - **Qobuz**: User ID + User Auth Token from browser localStorage ([see Wiki guide](https://github.com/V1ck3s/allstarr/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token))) -- Docker and Docker Compose (recommended) **or** [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) for manual installation +- Docker and Docker Compose (recommended) **or** [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) for manual installation -## Quick Start (Docker) +## Configuration -The easiest way to run Allstarr is with Docker Compose. +### Environment Setup 1. **Create your environment file** ```bash @@ -188,20 +195,13 @@ The easiest way to run Allstarr is with Docker Compose. See the full `.env.example` for all available options including Deezer/Qobuz credentials. -3. **Start the container** - ```bash - docker-compose up -d - ``` - - The proxy will be available at `http://localhost:5274`. - -4. **Configure your client** +3. **Configure your client** Point your music client to `http://localhost:5274` instead of your media server directly. > **Tip**: Make sure the `DOWNLOAD_PATH` points to a directory that your media server can scan, so downloaded songs appear in your library. -## Configuration +## Advanced Configuration ### Backend Selection @@ -255,7 +255,7 @@ The easiest way to run Allstarr is with Docker Compose. | Setting | Description | |---------|-------------| -| `Qobuz:UserAuthToken` | Your Qobuz User Auth Token (required if using Qobuz) - [How to get it](https://github.com/V1ck3s/allstarr/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) | +| `Qobuz:UserAuthToken` | Your Qobuz User Auth Token (required if using Qobuz) - [How to get it](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) | | `Qobuz:UserId` | Your Qobuz User ID (required if using Qobuz) | | `Qobuz:Quality` | Preferred audio quality: `FLAC`, `FLAC_24_HIGH`, `FLAC_24_LOW`, `FLAC_16`, `MP3_320`. If not specified, the highest available quality will be used | @@ -286,11 +286,11 @@ Subsonic__EnableExternalPlaylists=false #### Deezer ARL Token -See the [Wiki guide](https://github.com/V1ck3s/allstarr/wiki/Getting-Deezer-Credentials-(ARL-Token)) for detailed instructions on obtaining your Deezer ARL token. +See the [Wiki guide](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Deezer-Credentials-(ARL-Token)) for detailed instructions on obtaining your Deezer ARL token. #### Qobuz Credentials -See the [Wiki guide](https://github.com/V1ck3s/allstarr/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) for detailed instructions on obtaining your Qobuz User ID and User Auth Token. +See the [Wiki guide](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) for detailed instructions on obtaining your Qobuz User ID and User Auth Token. ## Limitations @@ -332,7 +332,7 @@ If you prefer to run Allstarr without Docker: 1. **Clone the repository** ```bash - git clone https://github.com/your-username/allstarr.git + git clone https://github.com/SoPat712/allstarr.git cd allstarr ``` @@ -561,6 +561,79 @@ allstarr.Tests/ - **Moq** - Mocking library for tests - **FluentAssertions** - Fluent assertion library for tests +## Contributing + +We welcome contributions! Here's how to get started: + +### Development Setup + +1. **Clone the repository** + ```bash + git clone https://github.com/SoPat712/allstarr.git + cd allstarr + ``` + +2. **Build and run locally** + + Using Docker (recommended for development): + ```bash + # Copy and configure environment + cp .env.example .env + vi .env + + # Build and start with local changes + docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build + + # View logs + docker-compose logs -f + ``` + + Or using .NET directly: + ```bash + # Restore dependencies + dotnet restore + + # Run the application + cd allstarr + dotnet run + ``` + +3. **Run tests** + ```bash + dotnet test + ``` + +### Making Changes + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Make your changes +4. Run tests to ensure everything works +5. Commit your changes (`git commit -m 'Add amazing feature'`) +6. Push to your fork (`git push origin feature/amazing-feature`) +7. Open a Pull Request + +### Code Style + +- Follow existing code patterns and conventions +- Add tests for new features +- Update documentation as needed +- Keep commits focused and atomic + +### Testing + +All changes should include appropriate tests: +```bash +# Run all tests +dotnet test + +# Run specific test file +dotnet test --filter "FullyQualifiedName~SubsonicProxyServiceTests" + +# Run with coverage +dotnet test --collect:"XPlat Code Coverage" +``` + ## License GPL-3.0 @@ -568,6 +641,7 @@ GPL-3.0 ## Acknowledgments - [Navidrome](https://www.navidrome.org/) - The excellent self-hosted music server +- [Jellyfin](https://jellyfin.org/) - The free and open-source media server - [Deezer](https://www.deezer.com/) - Music streaming service - [Qobuz](https://www.qobuz.com/) - Hi-Res music streaming service - [Subsonic API](http://www.subsonic.org/pages/api.jsp) - The API specification