Installation

Quickstart

To start using the backend, you can look at the provided docker-compose.yml file and merge it into your existing qBittorrent docker configuration.

We provide examples with and without gluetun (or any VPN container).

Once it's done, head to your VueTorrent instance (make sure you update the URL accordingly) and the backend should be automatically detected!

Note

Since 2.X, VueTorrent is now able to automatically detect the backend if installed properly.

If so, you can clear the "Backend URL Override" value if you're migrating from a previous version.

If you are a newcomer, you're good to go!

Warning

Before installing the backend, make sure that the "Host header validation" settings is disabled in the qBittorrent settings > WebUI.

The default qBittorrent security policy prevents forwarding requests from different ports. You will be unable to login if it's enabled, even with bypass configured.

Docker (recommended)

This repository provides a Docker image to use it directly.

Using Github Container Registry

Pull the image from the GitHub Container Registry using the included docker-compose.yml:

docker compose pull
docker compose up -d

Note: To target a specific version of the image, you must edit the docker-compose.yml file and change the image tag. See this doc for more information.

Build docker image from source

You'll have to toggle the comment of build and image attribute in docker-compose.yml to use the local image.

### Before:
#build: .
image: ghcr.io/vuetorrent/vuetorrent-backend:latest

### After:
build: .
#image: ghcr.io/vuetorrent/vuetorrent-backend:latest

docker compose build
docker compose up -d

Or simply

docker compose up --build -d

From source (not recommended)

# Clone the repository
git clone git@github.com:VueTorrent/vuetorrent-backend.git

# Navigate to the project directory
cd vuetorrent-backend

# Install dependencies
npm install

# Copy env template, feel free to edit it to match your setup
cp .env.dist .env

# Start the server
npm start

This will start the Node.js server on port 3000 by default, you can change settings in the .env file.

Healthcheck

To test whether the backend is accessible, you can go to the /backend/ping page of the backend. It should respond with a pong text.

Troubleshooting

If the ping doesn't respond correctly, make sure that:

• The container / app is running.
• For a docker container, port 3000 has been forwarded to your host machine (you must change the left side of the port mapping).

If the ping respond correctly BUT the backend doesn't work, make sure that the QBIT_BASE environment variable is correct. It should point to the qBittorrent URL accessible from the container.

• If on the same docker network, you can use the service name.
• If on a different docker network, you can use the host.docker.internal to refer to the host machine.
• If on a different machine, simply put the qBittorrent URL you're using to access the WebUI.