Unmanic Media Library Optimiser on AWS

This image delivers Unmanic 0.4, the open source self-hosted media library optimiser, fully installed and secured behind an nginx reverse proxy. Unmanic watches a library folder, tests every file against a configurable plugin flow, queues the files that do not conform, and transcodes them with ffmpeg through a worker pool - so a mixed collection of containers and codecs is automatically normalised to one consistent, space-efficient format without you ever running ffmpeg by hand.

The Unmanic application is a Python service that runs under systemd, listening only on the loopback interface, with nginx in front on port 80 (and 443 once you add TLS). nginx proxies the entire web UI and API, plus the live-update WebSocket the dashboard relies on. The transcoding engine is ffmpeg and ffprobe from the Ubuntu archive. Unmanic's entire state tree, the media library and the worker transcode cache all live on a dedicated, independently-resizable EBS data volume mounted at /var/lib/unmanic, separate from the operating system disk.

Secure by default - a per-instance password, generated on first boot

A stock Unmanic install ships with no authentication of any kind - not on its web UI and not on its API, which includes mutating routes that can rewrite settings and install plugin code - and by default binds to every network interface. This image fixes both problems. The application is bound to loopback only, and the whole UI and API sit behind an nginx HTTP Basic Auth gate. The password for the admin user is generated uniquely on first boot and stored only on your running instance; it is never baked into the image. Only an unauthenticated static health endpoint at /healthz is exempt from the gate.

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).

Retrieve your web UI password and sign in

The per-instance password is written to a root-owned file on the instance. Read it over SSH:

sudo cat /root/unmanic-credentials.txt

The file lists the site URL, the username (admin) and the generated password, along with the library and cache paths. Then open Unmanic in your browser:

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

Your browser prompts for a username and password (this is the nginx Basic Auth gate). Enter admin and the password from the credentials file. You are taken to the Unmanic dashboard.

Enable HTTPS before exposing the instance to the public internet (see the TLS section below). Until then, treat the password as you would any credential sent over plain HTTP, and restrict inbound access to your own IP in the security group.

What ships pre-configured

Out of the box this image is a working transcoding appliance, not a bare install:

• The official transcoding plugin is pre-installed and enabled. Unmanic core does no transcoding on its own - the work is done by plugins. This image ships the official Transcode Video Files plugin (video_transcoder), pre-installed from a pinned offline copy and enabled on the default library. (Unmanic's in-app plugin browser proxies the vendor catalogue and returns an empty list for a free installation, so pre-installing it is what makes the appliance work immediately.)

• A worker group is configured. A clean Unmanic has zero workers, so the scanner would queue files that nothing ever processes. This image configures one worker group with one worker, so queued files are actually transcoded. Raise the worker count on a larger instance (see below).
• The transcode target is a universally playable format. The plugin's stock settings can produce an unplayable file when the source container cannot carry the encoded stream. This image targets H.264 (libx264) written into an MKV container, verified to decode. Switch to HEVC/libx265 for better compression on larger instances if you prefer.
• The library, scanner and file monitor are configured. The default Media Library points at /var/lib/unmanic/library on the data volume, with both the periodic scanner and the filesystem file monitor enabled.

Demo media and pointing the library at your own files

So that the dashboard, the pending queue and the completed history show real work on your first login, the image seeds three short synthetic demo clips (generated at build time by ffmpeg's own test sources - no third-party media, no licensing question) into the library. On first boot Unmanic scans them, queues them and transcodes them to H.264/MKV, so you can see the pipeline working end to end.

When you are ready to use your own media, remove the demo clips and copy your files in. Copy your collection in over SSH from your workstation - for example with rsync (replace the placeholders with your own paths and address):

rsync -av -e "ssh -i your-key.pem" /path/to/your/media/ ubuntu@<instance-public-ip>:/tmp/media-upload/

Then move it into the library and hand ownership to the service account, so the file monitor picks up complete files:

sudo rsync -a --chown=unmanic:unmanic /tmp/media-upload/ /var/lib/unmanic/library/ && rm -rf /tmp/media-upload

To remove the seeded demo clips:

sudo rm -f /var/lib/unmanic/library/cloudimg-demo-*

Unmanic scans the library on a schedule (every 60 minutes by default) and watches for new files via the file monitor. You can also trigger an immediate scan with Rescan library now on the dashboard.

Adjusting the transcode settings

• Workers. In Settings -> Workers raise the number of workers to match your instance size. One worker already uses multiple cores for a single ffmpeg job; add workers to transcode several files in parallel on a larger instance.
• Target codec and container. In Settings -> Plugins, open the Transcode Video Files plugin settings to change the target video codec (for example to HEVC/libx265 for smaller files at the cost of CPU time), the container, and encoder options.
• Schedule. In Settings -> Library adjust the scan schedule or rely on the file monitor for near-immediate pickup of new files.

The data volume

Unmanic's entire state lives on the dedicated EBS data volume mounted at /var/lib/unmanic:

df -h /var/lib/unmanic

That volume holds the state tree (/var/lib/unmanic/.unmanic), the media library (/var/lib/unmanic/library) and the worker transcode cache (/var/lib/unmanic/cache). It is mounted by filesystem UUID via /etc/fstab, so it survives reboots and stop/start. Keeping the cache here is important: in-flight transcodes are written to it, and on the OS disk they could fill root. To grow your storage, expand the EBS volume in the AWS console and then grow the filesystem (confirm the device name first with lsblk):

sudo resize2fs /dev/nvme1n1

Services

Two systemd services keep the appliance running, plus a one-shot that runs on first boot:

systemctl status unmanic nginx

• unmanic.service - the Unmanic application, bound to 127.0.0.1:8888.
• nginx.service - the reverse proxy and Basic Auth gate on port 80.
• unmanic-firstboot.service - a one-shot that, on first boot, generates the per-instance password, seeds the demo library and proves the auth gate. It does not run again.

The unauthenticated health endpoint is handy for load-balancer checks (from the instance itself it answers on loopback; externally use your instance address):

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/healthz

Enabling HTTPS

nginx is ready to terminate TLS on port 443. The simplest route is a domain name pointed at your instance and a Let's Encrypt certificate:

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

certbot obtains the certificate and rewrites the nginx server block to serve HTTPS and redirect HTTP to HTTPS, keeping the Basic Auth gate in place. Alternatively, terminate TLS at an Application Load Balancer in front of the instance. cloudimg support can help with either approach.

Codec licensing

The transcoding engine uses the open source H.264/H.265 encoders distributed in the Ubuntu archive. Patent licensing for using or distributing those codecs in your jurisdiction remains your responsibility; this image grants no codec licence.

Support

cloudimg provides 24/7 technical support for this image by email and live chat - deployment, upgrades, plugin and worker configuration, transcoding troubleshooting, library migration and TLS setup. Email support@cloudimg.co.uk; critical issues receive a one-hour average response.

Unmanic is a trademark of its respective owner. 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.