yarr on Ubuntu 24.04 on Azure User Guide

Overview

yarr (yet another rss reader) is a fast, lightweight, self hosted RSS and Atom feed reader and aggregator. It is a single Go binary with an embedded web interface and an embedded SQLite database, so it stays small, starts instantly and keeps your reading history entirely on infrastructure you control. Subscribe to any website's feed, organise subscriptions into folders, and read articles in a clean three pane reading view with unread tracking, full text search, a built in readability mode and OPML import and export.

The cloudimg image installs yarr 2.8 and puts it behind an nginx reverse proxy that binds the server to loopback. The appliance is secure by default: the reader is protected by an nginx login prompt, and there is no default password. On first boot yarr-firstboot.service generates a unique administrator password and writes it to a root only note at /root/yarr-info.txt. Nothing is baked into the image. The reader also ships with a small set of self contained demo feeds, served from the image itself, so the interface is populated the moment you sign in.

What is included:

• yarr 2.8 single Go binary (/usr/local/bin/yarr)
• SQLite feed and article database at /var/lib/yarr/storage.db (no separate database to maintain)
• yarr.service running as yarr, bound to loopback 127.0.0.1:7070
• nginx.service reverse proxy on TCP 80 with an HTTP Basic Auth login gate, TLS ready
• yarr-firstboot.service generating a per VM administrator password on first boot
• Self contained demo feeds so the reader is populated on first sign in
• A built in readability view, full text search, folders, OPML import and export, and a Fever compatible API for mobile apps
• Ubuntu 24.04 LTS base, latest patches, unattended security upgrades enabled
• 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key, and a VNet with a subnet. Recommended VM size: Standard_B2s (yarr is very light; 4 GB RAM is plenty).

Step 1: Deploy from the Azure Portal

Search the Azure Marketplace for yarr, choose the plan, and create the VM. In the networking step attach an NSG that allows inbound TCP 22 (SSH) and TCP 80 (the web UI) from your client networks only. Put a TLS reverse proxy in front of port 80 for production.

Step 2: Deploy from the Azure CLI

RG="yarr-prod"; LOCATION="eastus"; VM_NAME="yarr-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/yarr-ubuntu-24-04/versions/<version>"
az vm create \
  --resource-group "$RG" --name "$VM_NAME" --location "$LOCATION" \
  --image "$GALLERY_IMAGE_ID" --size Standard_B2s \
  --admin-username azureuser --generate-ssh-keys \
  --public-ip-sku Standard
# then open TCP 80 to your own client network only:
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 80 --priority 900

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

yarr.service, nginx.service and yarr-firstboot.service all start automatically on first boot.

Step 4: Verify the Service

sudo systemctl is-active yarr nginx yarr-firstboot
sudo test -f /var/lib/cloudimg/yarr-firstboot.done && echo FIRSTBOOT_DONE
sudo ss -tlnp | grep -E ':80 |:7070 '

Expected output — all three services are active, nginx is bound to the public port 80 and yarr is bound to loopback 127.0.0.1:7070 only:

active
active
active
FIRSTBOOT_DONE
LISTEN 0 4096 127.0.0.1:7070 0.0.0.0:*  users:(("yarr",...))
LISTEN 0 511  0.0.0.0:80     0.0.0.0:*  users:(("nginx",...))

Step 5: Get Your Login Credentials

The reader has no default password. On first boot a unique administrator password is generated and written to a root only note, and the nginx login gate is configured to require it:

sudo cat /root/yarr-info.txt
curl -s -o /dev/null -w 'no credentials -> HTTP %{http_code}\n' http://127.0.0.1/api/status
P=$(sudo grep '^YARR_ADMIN_PASSWORD=' /root/yarr-info.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'with the per-VM login -> HTTP %{http_code}\n' -u "admin:$P" http://127.0.0.1/api/status

The note contains the administrator username, password and URL, all unique to this machine and never baked into the image. An unauthenticated request is rejected with 401, and the per VM login returns 200:

YARR_ADMIN_USERNAME=admin
YARR_ADMIN_PASSWORD=<YARR_ADMIN_PASSWORD>
YARR_URL=http://<vm-ip>/
no credentials -> HTTP 401
with the per-VM login -> HTTP 200

The YARR_URL line uses the address the VM sees for itself; browse to the reader using your VM's own public IP address.

Step 6: Read Feeds Through the API

yarr exposes a small JSON API behind the same login. List the subscribed feeds and count the stored articles — the image ships with the demo feeds already fetched:

P=$(sudo grep '^YARR_ADMIN_PASSWORD=' /root/yarr-info.txt | cut -d= -f2-)
curl -s -u "admin:$P" http://127.0.0.1/api/feeds | jq '[.[]|{title, feed_link}]'
curl -s -u "admin:$P" http://127.0.0.1/api/items | jq '{articles: (.list|length)}'

The two demo feeds are listed and their articles are already stored:

[
  { "title": "cloudimg on Azure", "feed_link": "http://127.0.0.1/demo/cloudimg.xml" },
  { "title": "Welcome to yarr",   "feed_link": "http://127.0.0.1/demo/welcome.xml" }
]
{ "articles": 6 }

Step 7: Sign In to the Web UI

Open the web UI in a browser at your VM's public IP address. The nginx login prompt appears; enter the username admin and the password from Step 5. Once signed in you see the three pane reader: your folders and feeds on the left, the article list in the middle, and the reading pane on the right. The demo feeds and their articles are already loaded.

Step 8: Read an Article

Click any article in the middle column to open it in the reading pane on the right. Use the toolbar to mark it read or starred, open the original link, or step to the next and previous articles. The readability button fetches and cleans the full article content for sites that only publish a summary in their feed.

Step 9: Add Your Own Feeds

Open the menu in the sidebar and choose New Feed, then paste any website or feed URL. yarr discovers the feed automatically, fetches the latest articles and files them under a folder of your choosing. You can also import an existing subscription list with Import (OPML).

Step 10: Keyboard Shortcuts

yarr is built for fast keyboard driven reading. Open Shortcuts from the sidebar menu to see the full list: j/k move between articles, 1/2/3 switch between unread, starred and all, / focuses search, and r marks an article read.

Step 11: Server Components

Everything the image installs lives in a handful of predictable paths:

/usr/local/bin/yarr -version
ls -1 /usr/local/bin/yarr /var/lib/yarr/storage.db /etc/yarr/yarr.env \
  /etc/systemd/system/yarr.service /usr/local/sbin/yarr-firstboot.sh \
  /etc/nginx/sites-available/cloudimg-yarr

Expected output — the pinned version and the installed components:

v2.8 (...)
/usr/local/bin/yarr
/var/lib/yarr/storage.db
/etc/yarr/yarr.env
/etc/systemd/system/yarr.service
/usr/local/sbin/yarr-firstboot.sh
/etc/nginx/sites-available/cloudimg-yarr

Step 12: Managing the Service

sudo systemctl status yarr --no-pager
sudo systemctl restart yarr
sudo journalctl -u yarr -n 50 --no-pager

yarr is a simple systemd service with Restart=always, so it comes back automatically after a crash or a reboot. Its data lives in /var/lib/yarr/storage.db; back that single file up to preserve your subscriptions and read state.

Step 13: Change the Login Password

The login is enforced by nginx HTTP Basic Auth, using the file /etc/nginx/yarr.htpasswd. To set a new password, overwrite that file (the apache2-utils package provides htpasswd, or use openssl):

NEWPASS='<new-password>'
echo "admin:$(openssl passwd -apr1 "$NEWPASS")" | sudo tee /etc/nginx/yarr.htpasswd >/dev/null
sudo systemctl reload nginx

Update /root/yarr-info.txt to match if you rely on it, and store the new password in your own secret manager.

Step 14: Add TLS (Optional)

For production, terminate TLS in front of port 80. The reverse proxy is already in place; add a certificate with certbot against your own domain name:

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

certbot edits the nginx server block to listen on 443 with your certificate and can redirect HTTP to HTTPS. Once TLS is in place the browser login is protected in transit.

Step 15: Import an OPML Subscription List

If you are migrating from another reader, export your subscriptions as OPML and import them from the sidebar menu with Import, or via the API:

P=$(sudo grep '^YARR_ADMIN_PASSWORD=' /root/yarr-info.txt | cut -d= -f2-)
curl -s -u "admin:$P" -F "opml=@<backup-dir>/subscriptions.opml" http://127.0.0.1/opml/import -o /dev/null -w '%{http_code}\n'

yarr creates the folders and feeds from the OPML file and refreshes them.

Step 16: Security Recommendations

• Restrict inbound TCP 80 (and 443) to your own client networks with an NSG.
• Add TLS (Step 14) so the login and your reading are encrypted in transit.
• Change the login password (Step 13) and keep /root/yarr-info.txt readable only by root.
• yarr binds to loopback only; never expose port 7070 directly.
• Keep the OS patched — unattended security upgrades are enabled by default.

Step 17: Support and Licensing

yarr is distributed under the MIT license. This is a repackaged open source software product with additional charges for cloudimg support services. 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.

Deploy on Azure

Find yarr on Ubuntu 24.04 LTS on the Azure Marketplace and launch it in minutes.

Need Help?

cloudimg provides 24/7 support with a 24h response SLA. Visit www.cloudimg.co.uk or contact support through the Azure Marketplace listing.