Bazarr on AWS

This image delivers Bazarr 1.6.0, the popular open source subtitle manager and companion to Sonarr and Radarr, fully installed, secured and reverse-proxied with nginx. Bazarr watches the same TV and movie libraries that Sonarr and Radarr manage, works out which of your wanted subtitle languages are missing or could be upgraded, searches your configured subtitle providers, downloads the best matches, and files them alongside your media automatically.

Bazarr is a Python application running under systemd as a dedicated unprivileged bazarr service account, with all state under /var/lib/bazarr. It is bound to the loopback interface only; an nginx TLS reverse proxy on port 443 is the sole network door, so Bazarr itself is never directly reachable from the network and all traffic to the web UI and REST API is encrypted. The self-updater is turned off so the running system never drifts from the published image - upgrades ship as a new cloudimg image version.

This image ships Bazarr on its own. You connect it to your own existing Sonarr and Radarr instances and your own media library - no media, Sonarr or Radarr is bundled.

Secure by default

A stock Bazarr starts with authentication switched off, which means anyone who can reach it gets full control of the application and its API key. This image never ships in that state:

• Bazarr binds to 127.0.0.1 only and is fronted by nginx TLS on port 443.
• Authentication is enforced (form login), and a unique administrator password and a unique API key are generated on every instance's first boot. The password is stored only as a one-way digest inside Bazarr; the plain values are written to a root-only file for you to read.
• A unique self-signed TLS certificate is generated per instance on first boot. Because it is self-signed, your browser will warn until you install your own certificate (see Replacing the TLS certificate).
• The service will not start until the secured configuration is in place, so there is no window in which the appliance serves world-open before first boot has rotated the credential.

Connecting to your instance

Connect over SSH on port 22 using the default login user for your operating system variant and the EC2 key pair you launched with.

Replace <instance-public-ip> with your instance's public IPv4 address (or its private address if you reach it over a VPN or Direct Connect).

Security group: the recommended security group opens only port 22 (SSH) and port 443 (the HTTPS front door). Scope both to your own administrator network (your office or VPN CIDR) rather than 0.0.0.0/0 - Bazarr is a private service, not a public website.

Retrieving your administrator credentials

The per-instance administrator username, password and API key are generated on first boot and written to a root-only file. Read them over SSH:

sudo cat /root/bazarr-credentials.txt

You will see the web URL, the admin username (admin), the generated password and the API key. These values are unique to your instance and are not present in the cloudimg image.

First sign-in

Open Bazarr in your browser over HTTPS:

https://<instance-public-ip>/

Because the certificate is self-signed by default, your browser shows a certificate warning the first time - choose to proceed (or, better, install your own certificate first). Sign in with the admin username and the generated password from the credentials file. You are taken to the Bazarr interface.

Connecting Bazarr to Sonarr and Radarr

Bazarr does its work by talking to your existing Sonarr (TV) and Radarr (movies). In the web UI, open Settings and select Sonarr (and then Radarr). Enable it, then enter the host address, port and API key of your Sonarr/Radarr instance and click Test to confirm connectivity.

Sonarr's default port is 8989 and Radarr's is 7878; you can find each application's API key under its own Settings -> General. If Sonarr/Radarr run on other hosts, make sure your security groups allow Bazarr's instance to reach them. Once connected, Bazarr synchronises your series and movies and begins tracking which subtitles are wanted.

Choosing languages and providers

Under Settings -> Languages, create a languages profile listing the subtitle languages you want and assign it to your series and movies. Under Settings -> Providers, enable the subtitle providers you want Bazarr to search (some require a free account or an API key).

With a languages profile assigned and providers enabled, the Series and Movies views show your library and the subtitle status of each item, and Bazarr fetches and upgrades subtitles automatically on its schedule. You can also trigger a manual search from any item.

Using the REST API

Bazarr exposes a documented REST API. Authenticate with the X-API-KEY header using the API key from your credentials file (the certificate is self-signed, so pass -k or install your own certificate):

curl -k -H "X-API-KEY: <your-api-key>" https://<instance-public-ip>/api/system/status

Verifying the deployment

The commands below confirm the appliance is healthy and shipped in the secure state. Run them over SSH on the instance.

Confirm both services are active:

systemctl is-active bazarr nginx

Confirm the health endpoint returns HTTP 200 through the nginx TLS front door (the ping endpoint is unauthenticated by design, for load-balancer probes):

curl -ks -o /dev/null -w 'ping HTTP %{http_code}\n' https://127.0.0.1/api/system/ping

Confirm authentication is enforced - an unauthenticated API call is refused with HTTP 401:

curl -ks -o /dev/null -w 'unauthenticated status HTTP %{http_code}\n' https://127.0.0.1/api/system/status

Confirm Bazarr is bound to the loopback interface only (nginx fronts it on 443):

sudo ss -tln | grep -q '127.0.0.1:6767' && echo 'bazarr bound to loopback OK'

Confirm the running version by authenticating with the per-instance API key:

K=$(sudo grep '^BAZARR_API_KEY=' /root/bazarr-credentials.txt | cut -d= -f2-); curl -ks -H "X-API-KEY: $K" https://127.0.0.1/api/system/status | grep -o '"bazarr_version": *"[^"]*"'

Managing the services

Bazarr and nginx are managed with systemd:

sudo systemctl status bazarr
sudo systemctl restart bazarr
sudo systemctl status nginx
sudo journalctl -u bazarr -f

Bazarr's configuration and database live under /var/lib/bazarr (config/config.yaml, db/bazarr.db, logs and backups). The application is installed under /opt/bazarr. The nginx site is /etc/nginx/sites-available/bazarr and the TLS material is in /etc/nginx/ssl.

Replacing the TLS certificate

The image generates a per-instance self-signed certificate on first boot so the front door is encrypted immediately. For production, replace it with a certificate your clients trust. The simplest option is a Let's Encrypt certificate - point a DNS A record at your instance, ensure port 443 (and temporarily 80 for the HTTP-01 challenge) is reachable, then:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d bazarr.your-domain.example

Certbot edits the nginx site to serve a trusted certificate and sets up automatic renewal. Alternatively, drop your own certificate and key into /etc/nginx/ssl/bazarr.crt and /etc/nginx/ssl/bazarr.key and run sudo systemctl reload nginx, or terminate TLS at an AWS load balancer with an ACM certificate and forward to the instance.

Backups

Bazarr has a built-in backup feature under Settings -> Scheduler (and a manual backup under System -> Backups) that snapshots its database and settings. For disaster recovery, also take periodic EBS snapshots of the instance's root volume, which holds /var/lib/bazarr.

Support

This image is commercially supported by cloudimg. We provide 24/7 technical support by email and chat for deployment, connecting Bazarr to Sonarr and Radarr, subtitle provider configuration, TLS termination and certificate replacement, backups and scaling.

Bazarr, Sonarr and Radarr are trademarks of their respective owners. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.