### Install Dependencies and Run Development Servers

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Installs all frontend and backend dependencies using npm and then starts both the API and Web development servers. Alternatively, API or Web can be started separately.

```bash
npm run install:all  # Install frontend dependencies

npm run dev          # Start both API and Web (recommended)
# OR run separately:
npm run dev:api      # Start only backend API
npm run dev:web      # Start only frontend web
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Navigate to the frontend directory and install its specific dependencies.

```bash
cd fe
npm install
cd ..
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/listenarrs/listenarr/blob/canary/fe/README.md

Installs all the necessary packages for the project. Run this command after cloning the repository.

```sh
npm install
```

--------------------------------

### InitializeAsync Setup

Source: https://github.com/listenarrs/listenarr/blob/canary/tests/README.md

Override InitializeAsync for common test class setup. Use Init() to override or remove services for dependency injection.

```csharp
Init(services => services.WithSingleton(myMock.Object));
Init(services => services.Without<IServiceToRemove>());
```

--------------------------------

### Start Debugging with Visual Studio/Rider

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Open the solution file and press F5 to start debugging the backend API. The API will be available at http://localhost:4545.

```csharp
1. Open `listenarr.sln` in Visual Studio or Rider
2. Set `listenarr.api` as the startup project
3. Press F5 to start debugging
4. The API will be available at [http://localhost:4545](http://localhost:4545)
```

--------------------------------

### Start Backend API

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Navigate to the API directory and run the .NET backend API. This is the first step to exploring the API using Swagger.

```bash
cd listenarr.api
dotnet run
```

--------------------------------

### Start Development Servers Separately

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Start the backend API and frontend development servers in separate terminals. This is useful for backend debugging.

```bash
# Terminal 1 - Backend (fast restart on code changes)
cd listenarr.api
dotnet watch run

# Terminal 2 - Frontend
cd fe
npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/listenarrs/listenarr/blob/canary/fe/README.md

Compiles and hot-reloads the application for development. This command is used for local development and debugging.

```sh
npm run dev
```

--------------------------------

### Run Listenarr API with Node.js

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Starts the Listenarr backend API using Node.js, specifying the service URL. This is typically used in conjunction with a separate frontend setup.

```bash
LISTENARR_URL=http://localhost:4545 node index.js
```

--------------------------------

### Register Infrastructure Services

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Example of registering infrastructure services in the application's DI container. This should be called from Program.cs.

```csharp
services.AddScoped<IFoo, Foo>();
```

--------------------------------

### Run Listenarr Executable on Windows

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Starts the Listenarr API executable on Windows after navigating to its directory. Assumes the executable is in a subdirectory named 'listenarr-win-x64'.

```cmd
cd .\listenarr-win-x64
.\Listenarr.Api.exe
```

--------------------------------

### Install Optional Dependencies for CSRF Support

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Install fetch-cookie and tough-cookie to improve CSRF support for the helper bot, which can prevent occasional CSRF errors.

```bash
npm install fetch-cookie tough-cookie
```

--------------------------------

### Run Listenarr Executable on macOS

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Starts the Listenarr API executable on macOS. Navigate to the correct directory (e.g., 'listenarr-osx-x64' or 'listenarr-osx-arm64') and make the executable runnable.

```bash
cd ./listenarr-osx-x64  # or osx-arm64 for Apple Silicon
chmod +x Listenarr.Api
./Listenarr.Api
```

--------------------------------

### ExternalRequests Configuration Example

Source: https://github.com/listenarrs/listenarr/blob/canary/listenarr.api/CONFIG.md

Example JSON configuration for the ExternalRequests section, controlling retry behavior for external scrapes and specifying US domain preference.

```json
{
    "ExternalRequests": {
        "PreferUsDomain": true
    }
}
```

--------------------------------

### Run Listenarr Executable on Linux

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Starts the Listenarr API executable on Linux. Requires changing directory and making the executable file runnable with `chmod +x`.

```bash
cd ./listenarr-linux-x64
chmod +x Listenarr.Api
./Listenarr.Api
```

--------------------------------

### Run Discord Bot Standalone (Development)

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Steps to run the Discord bot helper locally for development. Ensure you have Node.js 20+ and npm installed. The LISTENARR_URL environment variable points the bot to your running Listenarr instance.

```bash
cd tools/discord-bot
npm install
# Point the helper at your running Listenarr instance (defaults to http://localhost:4545)
LISTENARR_URL=http://localhost:4545 npm start
```

--------------------------------

### Run Discord Bot Standalone (Windows PowerShell)

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Instructions for running the Discord bot helper on Windows using PowerShell. This sets the LISTENARR_URL environment variable and starts the bot.

```powershell
cd tools\discord-bot
npm install
$env:LISTENARR_URL = 'http://localhost:4545'
npm start
```

--------------------------------

### Build and Run Framework-Dependent Deployment

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Publishes a framework-dependent .NET application and then runs it using the .NET runtime. This requires the .NET 8.0 Runtime to be installed on the target system.

```bash
# Requires .NET Runtime installed on target system
dotnet publish listenarr.api/Listenarr.Api.csproj -c Release
cd ./bin/Release/net8.0/publish
dotnet Listenarr.Api.dll
```

--------------------------------

### Run Frontend Unit Tests

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Navigate to the frontend directory and run unit tests using npm.

```bash
cd fe && npm run test:unit
```

--------------------------------

### Build Runtime Docker Image

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Build a runtime Docker image from the publish output. Ensure you are in the correct context directory.

```bash
# context: listenarr.api/publish/<rid>
docker build -f listenarr.api/Dockerfile.runtime -t <your-image> listenarr.api/publish/linux-x64
```

--------------------------------

### Frontend Production Build

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Build the frontend for production by navigating to the frontend directory and running the npm build command.

```bash
cd fe
npm run build
```

--------------------------------

### Build and Run Self-Contained Executable

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Builds a self-contained .NET executable for Windows x64 and then runs it. This is recommended for production deployments when not using Docker.

```bash
# Build self-contained executable for your platform
dotnet publish listenarr.api/Listenarr.Api.csproj -c Release -r win-x64 --self-contained
cd ./bin/Release/net8.0/win-x64/publish
./Listenarr.Api.exe
```

--------------------------------

### CI-first Monorepo Build (Skip Frontend)

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Build the project locally using dotnet publish, skipping the frontend build if Node.js is not available on the host.

```bash
dotnet publish listenarr.api/Listenarr.Api.csproj -c Release -o ./publish/local /p:SkipFrontendBuild=true
```

--------------------------------

### Backend Production Build

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Build the backend API for production by navigating to the API directory and running the dotnet publish command.

```bash
cd listenarr.api
dotnet publish -c Release
```

--------------------------------

### Dependency Injection Unit Test Example

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

A unit test to verify that required services are resolvable from the DI container. This helps catch layering regressions.

```csharp
public class DependencyInjectionTests
{
    [Fact]
    public void Ensure_Services_Are_Resolvable()
    {
        // Arrange
        var services = new ServiceCollection();
        // Add infrastructure services here, e.g.:
        // services.AddInfrastructureLayer(Configuration);

        // Act
        var serviceProvider = services.BuildServiceProvider();

        // Assert
        // Assert that required services can be resolved, e.g.:
        // Assert.NotNull(serviceProvider.GetService<IFoo>());
    }
}
```

--------------------------------

### Run Frontend Type Checks

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Navigate to the frontend directory and run type checking using npm.

```bash
cd fe && npm run type-check
```

--------------------------------

### Restore .NET Dependencies

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Navigate to the backend API directory and restore the .NET dependencies.

```bash
cd listenarr.api
dotnet restore
cd ..
```

--------------------------------

### qBittorrent Adapter Improvements

Source: https://github.com/listenarrs/listenarr/blob/canary/CHANGELOG.md

The qBittorrent adapter now prefers IHttpClientFactory with a cookie-client fallback and uses an injected HttpClient for authentication requests. Auth failure messages are clarified, and robustness has been improved.

```csharp
Prefer `IHttpClientFactory` with a cookie-client fallback, use injected `HttpClient` for auth requests, and clarified auth failure messages; added `QBittorrentHelpers` and robustness improvements in the adapter.
```

--------------------------------

### Docker Compose for Listenarr

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Defines a Docker Compose setup for Listenarr, specifying the image, ports, environment variables, and volume mappings. Includes a named volume for configuration persistence.

```yaml
version: '3.8'
services:
  listenarr:
    image: ghcr.io/listenarrs/listenarr:canary
    ports:
      - "4545:4545"
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - LISTENARR_PUBLIC_URL=https://your-domain.com ## OPTIONAL: Used by Discord Bot
    volumes:
      - listenarr_data:/app/config
      - /path/to/audiobooks:/audiobooks #optional
      - /path/to/downloadclient-downloads:/downloads #optional
    restart: unless-stopped

# For Docker Hub, replace the image with docker.io/therobbiedavis/listenarr:canary

volumes:
  listenarr_data:
```

--------------------------------

### Development Commands

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Run these npm commands from the repository root to manage development and build processes for the API and web frontend.

```bash
npm run dev          # Start both API and Web
npm run dev:api      # Start only backend API
npm run dev:web      # Start only frontend web
npm run build        # Build both for production
npm run test         # Run frontend tests
```

--------------------------------

### Run Backend Tests

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Execute backend unit and integration tests using the .NET CLI.

```bash
dotnet test
```

--------------------------------

### CI-first Monorepo Build

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Build the project locally using dotnet publish, which includes building the frontend and copying its output to the API's wwwroot. This creates a single publish artifact.

```bash
# from repo root
dotnet publish listenarr.api/Listenarr.Api.csproj -c Release -o ./publish/local
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/listenarrs/listenarr/blob/canary/CONTRIBUTING.md

Execute frontend tests using npm scripts. The frontend utilizes Vitest/Vite.

```bash
cd fe && npm test
```

--------------------------------

### Run Listenarr with Docker

Source: https://github.com/listenarrs/listenarr/blob/canary/README.md

Launches Listenarr in a Docker container. Configure ports, user/group IDs, and volume mounts for persistent data and media access. Optional environment variables like LISTENARR_PUBLIC_URL are supported.

```bash
docker run -d \
  --name listenarr \
  -p 4545:4545 \
  ## OPTIONAL: Set container runtime user/group and file creation mask
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=022 \
  ## OPTIONAL: Used by Discord Bot
  -e LISTENARR_PUBLIC_URL=https://your-domain.com \
  -v listenarr_data:/app/config \
  -v /path/to/audiobooks:/audiobooks #optional \
  -v /path/to/downloadclient-downloads:/downloads #optional \
  ghcr.io/listenarrs/listenarr:canary
```

--------------------------------

### Run Discord Bot Stub (Command Line)

Source: https://github.com/listenarrs/listenarr/blob/canary/tools/discord-bot/README.md

Navigate to the discord-bot directory and run the stub using Node.js.

```bash
cd tools\discord-bot
node index.js
```

--------------------------------

### Build for Production

Source: https://github.com/listenarrs/listenarr/blob/canary/fe/README.md

Type-checks, compiles, and minifies the application for production deployment. This command generates optimized build artifacts.

```sh
npm run build
```

--------------------------------

### Run Discord Bot Stub (PowerShell)

Source: https://github.com/listenarrs/listenarr/blob/canary/tools/discord-bot/README.md

Execute the Discord bot stub from the repository root using PowerShell.

```powershell
node .\tools\discord-bot\index.js
```

--------------------------------

### qBittorrent Authentication Test

Source: https://github.com/listenarrs/listenarr/blob/canary/CHANGELOG.md

The qBittorrent client test now attempts authentication using values from the unauthenticated /api/v2/app/version endpoint.

```csharp
`qBittorrent` client test now attempts authentication when the unauthenticated `/api/v2/app/version` values.
```

--------------------------------

### Run End-to-End Tests (Production Build)

Source: https://github.com/listenarrs/listenarr/blob/canary/fe/README.md

Tests the production build of the application using Cypress. This is recommended before deploying to ensure the production version functions correctly.

```sh
npm run build
npm run test:e2e
```