Installing on Server or NAS

Due to security restrictions, some application settings are provided through a configuration file. Therefore, your installation process involves the following steps:

1. Installation
2. Editing the Configuration File

Installation

You can install Balsa using the following methods:

1. Installation via Docker: Recommended for users whose target device provides a Docker GUI, such as those from major NAS manufacturers.
2. Installation via Docker Compose: Recommended for users who are comfortable using the command line and have a strong Linux foundation.
3. Binary Installation: For advanced users only.

TIP

Installing Balsa on a server or NAS can be challenging; you may need some basic Linux knowledge. If you encounter difficulties during installation, feel free to contact us for assistance.

Installation via Docker

You need to create a container using the Docker Manager (referred to as Container Station or Container Manager by some NAS vendors) in your NAS console.

Fill in the following information in the container creation form:

• Image: You can choose either of the following types:
  • docker.balsadl.com/balsa-webui:gnu: GNU-based image with better performance.
  • docker.balsadl.com/balsa-webui:musl: Musl-based image with lower storage and memory footprint.
• Network Mode: You may need to access advanced options:
  • Host
• Storage Mapping (also known as Volumes, Mounts): You must add at least one volume to store application data.
  • Mount from Host: Select a directory of your choice to store user data and mount it to /data inside the container.
  • ... You can mount more custom download directories from the host to any path inside the container. To specify these as download paths, please see Editing the Configuration File.

Once filled out, click Create to complete the installation. After installation, you can access Balsa via http://your-NAS-IP:7380. You can later edit the configuration file to customize options.

TIP

You can update Balsa by pulling the latest image and re-creating the container.

Note: Some NAS consoles provide a direct "Re-create" or "Update" option.

Installation via Docker Compose

Edit the following docker-compose.yaml file:

services:
  balsa:
    image: docker.balsadl.com/balsa-webui:gnu # Or use docker.balsadl.com/balsa-webui:musl
    # user: "1000:1000" # Use this to control the uid:gid Balsa uses to avoid permission issues with downloaded files.
    network_mode: host
    volumes:
      - <path-to-user-data>:/data # Input your desired directory for *user data*. This stores Balsa's system data and downloads, e.g., /share/Balsa:/data.
      # If you have additional download directories, add them here. 
      # Refer to the "Editing the Configuration File" section below to register these paths within Balsa.

TIP

We strongly recommend using network_mode: host to support the following features:

1. Wake-on-LAN
2. Improved IPv6 support

If you prefer the default bridge network, you will need to configure port mapping to access the WebUI. The default WebUI port is 7380 (changeable via the configuration file).

Upload the docker-compose.yaml to your server or NAS, navigate to the directory in the command line, and run:

docker compose up -d

TIP

You can check Balsa's output using docker compose logs.

If you see ... serving server listen_addr=0.0.0.0:7380, the installation was successful.

After installation, access Balsa via http://your-server-IP:7380.

TIP

To update Balsa, navigate to the directory containing docker-compose.yaml and execute:

docker compose pull
docker compose up -d

Binary Installation

You can download the Balsa WebUI binary from our Download Center for custom deployment.

# ./balsa-webui --help

Usage: balsa-webui [OPTIONS]

Options:
  -d, --data <DATA>      Custom data directory path, default: ${HOME}/.config/balsa
  -c, --config <CONFIG>  Custom config file path, default: ${DATA}/config.toml
      --show-licenses    Print 3rd-party open source licenses
  -h, --help             Print help

Editing the Configuration File

After installation and initial startup, Balsa will generate an initial configuration file in your selected user data directory. Restart Balsa after editing this file for changes to take effect.

[server]
listen = "0.0.0.0:7380" # Balsa service listening address; change the port here
# tls.cert = "./tls/cert.pem" # TLS certificate path, relative to the user data directory
# tls.key = "./tls/key.pem" # TLS private key path, relative to the user data directory

[runtime]
# max-worker-threads = 8 # Maximum allowed worker threads. This relates to CPU/Memory usage, not download connections.

# Below are storage paths for downloads. The default path is [User Data]/downloads.
# You can customize more paths here. Note: These must correspond to your volume/mount settings.
# The "key" field must be unique.
[[storage]]
key = "default"
name = "Default"
path = "./downloads"

# [[storage]]
# key = "secondary"
# name = "Secondary Storage"
# path = "/mnt/secondary"