OpenList on Ubuntu 24.04 on Azure User Guide

Overview

OpenList is a self-hosted file list and file management server — the community-maintained successor to AList. It presents many storage backends (local disk, S3-compatible object storage, WebDAV, FTP, and dozens of cloud drives) through a single unified web UI and a WebDAV/REST interface, with per-path access control. Point it at the storage you already have and browse, preview, share and download everything from one place, on infrastructure you control.

The OpenList server is a single self-contained Go binary that serves both the REST API and the bundled web app, using an embedded SQLite database — no external database or runtime interpreter is required. It runs behind nginx as a reverse proxy on port 80; the server itself listens on 127.0.0.1:5244 and binds to the loopback interface only.

On the first boot of every deployed VM, a one-shot service initialises a fresh SQLite database (which also yields a fresh per-instance JWT signing secret), sets a per-instance administrator password for the admin account, and writes the login to /root/openlist-credentials.txt with mode 0600. The image itself ships with no database and no default account, so two VMs deployed from the same image never share credentials.

What is included:

• OpenList 4.2.3 server (single Go binary, bundles the web UI, embedded SQLite) at /opt/openlist/openlist
• nginx reverse proxy on :80 (with upload sizes unbounded for a file manager) in front of the OpenList server on loopback :5244
• The SQLite database and configuration under /opt/openlist/data
• Per-VM administrator password generated at first boot, in a root-only file — no default login ships in the image
• openlist.service, nginx.service and a one-shot openlist-firstboot.service as systemd units
• The complete, unmodified upstream AGPL-3.0 source for the shipped version on disk under /opt/openlist/SOURCE
• A fully patched Ubuntu 24.04 LTS security baseline at capture time, with unattended security updates enabled
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point — OpenList is lightweight; scale up for very large libraries or many concurrent users. NSG inbound: allow 22/tcp from your management network and 80/tcp (plus 443/tcp once you enable HTTPS) from the networks your users will reach OpenList on.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for OpenList by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create → Create. First boot initialisation takes a few seconds after the VM starts.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name openlist \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name openlist --port 80 --priority 1010

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 — Verify the OpenList stack

Two systemd services make up the stack. Confirm both are active and that the open health endpoint answers through nginx:

systemctl is-active openlist nginx
curl -s http://127.0.0.1/ping

Both lines read active and the health endpoint returns pong.

Confirm the OpenList server binds to loopback only, with nginx the sole public listener:

sudo ss -tlnp | grep -E ':80 |:5244 '

Port 80 (nginx) listens on all interfaces; port 5244 (OpenList) is bound to 127.0.0.1 only.

Step 5 — Retrieve your administrator login

The administrator login generated on the first boot of your VM is stored in a root-only file. It lists the OpenList URL, the administrator username (admin) and the password:

sudo cat /root/openlist-credentials.txt

Store the password in your password manager and treat the file as sensitive. If you ever need to set a new password from the command line, use OpenList's own admin command:

cd /opt/openlist && sudo -u openlist ./openlist admin set 'your-new-password'

Step 6 — Verify authentication

The login API rejects a wrong password and issues a token for the generated administrator password. The first request reports HTTP code 401, the second returns a token, and the authenticated /api/me reports the admin user:

PASS=$(sudo grep '^openlist.admin.pass=' /root/openlist-credentials.txt | cut -d= -f2-)
curl -s -X POST http://127.0.0.1/api/auth/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"wrong"}' | jq -r '.code'
TOKEN=$(curl -s -X POST http://127.0.0.1/api/auth/login -H 'Content-Type: application/json' -d "{\"username\":\"admin\",\"password\":\"$PASS\"}" | jq -r '.data.token')
curl -s http://127.0.0.1/api/me -H "Authorization: $TOKEN" | jq -r '.data.username'

Step 7 — First sign-in to the web app

Open a web browser and navigate to http://<vm-public-ip>/. Sign in with the username admin and the password from /root/openlist-credentials.txt. The web app opens the file browser — once you have added a storage backend (next step), your files, folders and previews appear here, arranged in a clean list you can navigate, search, sort and share.

Step 8 — Add a storage backend

A fresh install has no storage mounted yet. Open Manage (bottom of the page, or navigate to /@manage) → Storages → Add, choose a driver and a mount path, and save. OpenList supports many backends — start with Local (a directory on the VM) and add object storage or cloud drives later:

• Local — a directory on the VM disk, e.g. mount path / → root folder /srv/files
• S3 — any S3-compatible object store (AWS S3, MinIO, Backblaze B2, Wasabi, …)
• WebDAV, FTP/SFTP, and dozens of cloud-drive providers

Each storage is mounted at a virtual path and can be independently enabled, disabled or reordered. A working storage shows Status: Working:

You can also add a storage over the API with your admin token — for example a Local backend mounted at /:

curl -s -X POST http://127.0.0.1/api/admin/storage/create \
  -H "Authorization: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"mount_path":"/","driver":"Local","order":0,"status":"work",
       "addition":"{\"root_folder_path\":\"/srv/files\"}"}'

Once a storage is mounted, list its contents over the API to confirm files are served:

curl -s -X POST http://127.0.0.1/api/fs/list -H 'Content-Type: application/json' -d '{"path":"/","page":1,"per_page":0,"refresh":true}' | jq -r '.data.content[]?.name // "(add a storage to see files)"'

Step 9 — Configure global settings

Under Manage → Settings → Global you control site-wide behaviour: hide-file patterns, package downloads, link expiry, custom head/body, sign-all for direct links, and single sign-on / LDAP integration. Site, style and preview options let you brand the front page and choose how documents, images, audio and video are previewed in the browser:

Step 10 — Access files over WebDAV

Every mounted storage is also available over WebDAV, so you can map OpenList as a network drive or use it from sync clients. The WebDAV root is served at /dav — connect with the admin user and password (or a dedicated user you create under Manage → Users):

# macOS Finder:  Go → Connect to Server → http://<vm-public-ip>/dav
# Linux:         rclone / davfs2 against  http://<vm-public-ip>/dav

Because this is your own self-hosted VM, your files and traffic never leave infrastructure you control.

Security baseline

The image is captured with the Ubuntu 24.04 security baseline fully applied (including phased updates) and ships with unattended security upgrades enabled, so your VM keeps patching itself after deployment:

cat /etc/apt/apt.conf.d/20auto-upgrades
systemctl is-enabled unattended-upgrades || true

The OpenList server binds to loopback only and nginx is the single public listener; the shipped image contains no database, so no default account exists until first boot creates a unique one:

jq -r '.scheme.address, .scheme.http_port' /opt/openlist/data/config.json

Enabling HTTPS

For production use, serve OpenList over HTTPS so that logins and file transfers are encrypted in transit. Point a DNS A record at the VM's public IP address, then install a certificate with Certbot (replace the domain):

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

After enabling HTTPS, open 443/tcp in the NSG, set the site URL under Manage → Settings → Site to your https:// address, and restrict or close inbound port 80.

Backup and maintenance

All OpenList state lives under /opt/openlist/data — the SQLite database data.db (users, storages, settings) plus the search index. The simplest logical backup is to copy that file while the service is stopped, or snapshot the OS disk:

sudo systemctl stop openlist
sudo cp /opt/openlist/data/data.db /var/backups/openlist-data-$(date +%F).db
sudo systemctl start openlist

Apply operating system security updates with sudo apt update && sudo apt upgrade; the services restart cleanly. Restart the server at any time with sudo systemctl restart openlist.

Licence and source

OpenList is free software licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). In compliance with the licence, the complete, unmodified upstream source for the exact version shipped in this image is placed on disk at /opt/openlist/SOURCE/openlist-v4.2.3-source.tar.gz, with a NOTICE pointing to it and to the upstream repository. cloudimg makes no modifications to the OpenList program itself.

Support

This image is backed by 24/7 cloudimg support. Contact us by email and chat for deployment help, storage-backend configuration, TLS termination and access-control setup.

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.