VPS Tutorials
Deploying OpenList (AList) on a VPS (2026): Docker, WebDAV, Cloud Drive Mounts, HTTPS and Security Configuration
Deploy OpenList (AList) on a VPS with Docker Compose, configure domain HTTPS, WebDAV, local storage and cloud drive drivers, and understand access protection, rate limiting, traffic costs, backup and upgrades, and common failures.
Deploying OpenList (AList) on a VPS (2026): Docker, WebDAV, Cloud Drive Mounts, HTTPS and Security Configuration
If you want to bring Alibaba Cloud Drive, OneDrive, Google Drive, S3, WebDAV or local disks together behind a single web entry point, OpenList is one of the more popular self-hosted options right now. It is a community-driven fork of AList and supports file previews, direct links, WebDAV, online playback, cross-storage copying and many cloud storage drivers.
Projects like this are most often misunderstood as "once installed, you have an unlimited-speed cloud drive." Actual speed still depends on the cloud drive API, the network between the VPS and the storage, account permissions, provider rate limits and outbound bandwidth. This article only discusses using OpenList on storage accounts and files you are authorized to use, and does not cover bypassing platform permissions, download limits or sharing rules.
OpenList suits:
- People who want to merge several personal cloud drives or object storage buckets into one file directory;
- People who want to give family members or a small team a unified file browsing entry point;
- People who need WebDAV so computers, phones or media software can access remote directories;
- People who want VPS local disks, S3 and cloud drives in the same management interface;
- People who need file previews, direct links, temporary sharing, online video playback or cross-storage copying.
If you need multi-person collaboration, permission auditing, version history and sync clients, Nextcloud, Seafile or a commercial cloud drive is a better fit. OpenList is more of a "storage aggregation and access layer" and should not be treated as your only backup.
The OpenList main program itself is very light; what actually consumes resources is thumbnails, online video playback, file packaging, caching, aria2 downloads and multiple concurrent accesses.
| Scenario | Recommended configuration | Notes |
|---|---|---|
| Personal browsing and direct links | 1 core, 1GB, 20GB SSD | Mount only a small amount of storage, no transcoding |
| Family use and WebDAV | 2 cores, 2GB, 40GB NVMe | Leave room for cache, logs and system space |
| Multiple storages, online playback | 2–4 cores, 4GB, 60GB NVMe | Watch outbound bandwidth and connection counts |
| Small team or public file entry point | 4 cores, 8GB, 100GB+ NVMe | Needs rate limiting, monitoring, backup and auditing |
If files actually live in cloud drives, you don't need to buy a very large VPS local disk; if you want to use local storage, cache thumbnails or run offline downloads, disk capacity should be calculated based on data growth. You can start by reading How to choose a VPS configuration and Does a VPS need object storage.
| Option | Core positioning | Better suited for | Main trade-offs |
|---|---|---|---|
| OpenList | Aggregates many cloud storages and local storage | People who want unified access to multiple storages | Account authorization, upstream rate limits and driver differences must be handled yourself |
| AList | The original project and its ecosystem | Those with existing old configs or dependencies on old tutorials | Confirm project maintenance and version status before migrating |
| Cloudreve | Self-hosted cloud drive and user uploads | Those who need users, quotas, uploads and a sharing system | Higher deployment and database maintenance cost |
| Nextcloud | Collaboration, sync, permissions and plugins | Team file collaboration | Higher resource usage and upgrade complexity |
| Seafile | Efficient file sync | Multi-device sync and team drives | Requires separate planning of database and storage |
OpenList's advantage is not replacing every cloud drive, but putting existing storage behind a unified entry point. If you need to truly bring your data back onto your own server, you should plan local storage, object storage and backups directly, rather than only mounting third-party cloud drives.
Use a clean Ubuntu 22.04/24.04 LTS or Debian 12. First confirm Docker is available:
docker version
docker compose version
Create the data directory and restrict permissions:
sudo mkdir -p /etc/openlist
sudo chmod 750 /etc/openlist
cd /opt
sudo mkdir -p openlist
sudo chown -R "$USER":"$USER" /opt/openlist
cd /opt/openlist
OpenList's data directory contains the database, configuration, users, storage drivers and runtime state. Do not put it in a temporary directory, and do not mount the host root directory directly into the container.
The official Compose uses the openlistteam/openlist image and mounts the host /etc/openlist into the container's /opt/openlist/data. For production, pin the version; start with the currently confirmed v4.2.4:
services:
openlist:
image: openlistteam/openlist:v4.2.4
container_name: openlist
restart: unless-stopped
user: "0:0"
environment:
UMASK: "022"
TZ: Asia/Shanghai
volumes:
- /etc/openlist:/opt/openlist/data
ports:
- "127.0.0.1:5244:5244"
- "127.0.0.1:5245:5245"
Save it as /opt/openlist/compose.yaml and start:
cd /opt/openlist
docker compose up -d
docker compose ps
docker compose logs --tail=100 openlist
Binding the port only to 127.0.0.1 is so that the public internet can only reach it through the reverse proxy. The official example maps 5244 and 5245 directly, but on a public VPS it is not advisable to expose the raw management port to the internet.
To view initial information, first check the container logs:
docker logs openlist --tail=100
After the first login, immediately change the admin password and secure entry path, and save recovery information. Do not write initial passwords, cookies or storage tokens into public repositories.
Prepare a dedicated domain, for example drive.example.com, and point the A record to the VPS. You can use Caddy, Nginx or 1Panel as the reverse proxy. Taking Caddy as an example:
drive.example.com {
reverse_proxy 127.0.0.1:5244
}
Caddy will request certificates automatically, but only if DNS, ports 80/443, the firewall and server time are all correct. After the panel or proxy configuration is complete, test:
curl -I https://drive.example.com
If you encounter certificate request failures, redirect loops or upstream connection errors, see The complete guide to using Caddy as a reverse proxy on a VPS and Troubleshooting HTTPS redirect loops on a VPS website.
Do not add 5244, 5245, database ports and the Docker Socket to the public security group. WebDAV should also go over HTTPS; do not transmit account passwords over plaintext HTTP.
Do not use admin, an email prefix or the site name as the admin account. Use a random long string for the password, and set a path for the admin entry that is not easy to scan. A secure entry is not the only protection; it must still be combined with HTTPS, login rate limiting and backups.
When sharing directories publicly, do not make the entire root directory anonymously readable. Set passwords or login requirements for sensitive directories, and set expiration times for public links. When testing, use a dedicated non-sensitive directory; do not experiment directly on the root of a private cloud drive.
If only you use it, you can restrict the source IP of the admin path at the cloud firewall or reverse proxy layer. When mobile network addresses change frequently, using WireGuard or Tailscale to enter the internal network and then access the OpenList admin page is usually more reliable than opening the backend to all IPv4 addresses.
Cloud drive refresh tokens, cookies, client secrets and S3 Secrets are all highly sensitive credentials. Do not expose them in screenshots, logs, tickets or Git repositories. When changing account passwords, revoking authorization or suspecting a leak, revoke the old token on the upstream platform and re-bind.
OpenList storage configuration usually includes driver type, mount path, sorting, root directory and authorization parameters. It is recommended to add them in the following order:
- First add an empty local test directory;
- Confirm that listing, preview, download and permissions all work;
- Then add a low-risk S3 or WebDAV storage;
- Finally add cloud drives containing many files;
- For each driver added, test directory reading, single-file download and large-file download.
The local storage directory must be a path accessible to the container. If you want to mount the host's /srv/files, you need to add an explicit read-only or read-write mount in Compose:
volumes:
- /etc/openlist:/opt/openlist/data
- /srv/files:/srv/files:ro
Read-only mode is suitable for file display and download. If you enable web upload, delete, rename or move, read-write permission is required, but the risk is also higher. Do not mount /, /home or directories containing SSH keys.
S3 storage usually requires Endpoint, Region, Bucket, Access Key, Secret Key and root path. It is recommended to create a separate least-privilege Access Key for OpenList, allowing access only to the specified Bucket or prefix; do not reuse a master key with full account permissions.
Object storage is suitable for images, videos, backups and large files, but you must calculate outbound traffic, request counts and download costs. OpenList's web entry point does not eliminate upstream object storage costs; especially when direct links are heavily accessed, set rate limits and bandwidth alerts.
WebDAV is suitable for connecting to existing self-hosted file services or office storage. When configuring, confirm the HTTPS URL, username, password and root path, and test small-file read/write first. WebDAV performance and locking mechanisms depend on the upstream service, so it is not suitable to blindly treat it as a high-concurrency file distribution layer.
These drivers require completing authorization according to OpenList's current interface and official documentation. Login, refresh tokens, family drives, shared drives and regional policies may change across platforms, so you cannot copy cookies or parameters from old tutorials directly into production.
After successful authorization, first mount a test directory, then verify:
- Whether the file list is complete;
- Whether Chinese file names display correctly;
- Whether video and image previews work;
- Whether direct links work as expected in a browser that is not logged in;
- Whether logs leak authorization information when downloads fail.
Only mount accounts and files that you or your team are authorized to access, and comply with upstream cloud drive terms of service and copyright rules.
OpenList can serve as a WebDAV entry point, letting systems or applications access remote directories. When using it, note:
- Do not use the admin account as the WebDAV user;
- Set up a separate low-privilege user for WebDAV;
- Access over HTTPS;
- Set stricter directory permissions for upload and delete operations;
- Test small files first, then large files and resumable transfers;
- Do not expose the WebDAV port directly to public internet scanning.
If you want to provide a media directory to Jellyfin, a player or a download tool, prefer letting the application access a stable local mount or S3, rather than routing all traffic through the OpenList proxy. Proxy playback consumes VPS outbound bandwidth and connection counts; when it stutters during peak hours, check the upstream cloud drive, the VPS route and the public egress at the same time.
OpenList's access layer is not a CDN. The following types of traffic most easily make bills spiral:
- Large amounts of online video playback;
- Public direct links being scraped by search engines or scripts;
- Folder packaged downloads;
- Visitor uploads being repeatedly forwarded;
- Multiple users downloading from the same VPS at the same time.
It is recommended to split by purpose:
- Put public images and static files in object storage with a CDN;
- Access private files through login or temporary links;
- Allow the admin backend only from fixed sources;
- Set rate limits and expiration times for anonymous downloads;
- Configure traffic alerts on both the VPS and object storage sides.
You can cross-check with vnStat, cloud provider traffic graphs and OpenList logs. The site's VPS traffic monitoring and overage alerts is suitable for further troubleshooting bandwidth anomalies.
At minimum back up:
- The
/etc/openlistdata directory; compose.yaml;- Reverse proxy configuration;
- Domain and DNS records;
- Storage driver list;
- Cloud drive authorization recovery notes;
- Custom themes, scripts and external tasks.
Backing up only the OpenList data directory is not the same as backing up the cloud drive files themselves. OpenList mostly stores indexes, configuration and authorization information; the actual files remain on the local disk or upstream cloud storage.
Before upgrading, record the current image:
docker inspect openlist --format '{{.Config.Image}}'
docker compose config > compose.before-upgrade.yaml
Then back up the data directory:
sudo tar -czf /opt/openlist-data-$(date +%F).tar.gz /etc/openlist
Copy the archive to another machine or object storage, then pull the new version. Do not rebuild latest into production without a backup. After upgrading, first check login, storage lists, direct links, WebDAV and downloads, then decide whether to keep the new version.
When rolling back, restore three parts at the same time:
- The previous working image;
- The
/etc/openlistfrom before the upgrade; - The reverse proxy and environment variables.
If you only roll back the image while keeping an already-migrated data structure, it may start successfully but fail to read the configuration. Before a formal upgrade, rehearse once on a temporary VPS or test directory.
Check container status, port listening and local requests:
docker compose ps
ss -lntp | rg '5244|5245'
curl -I http://127.0.0.1:5244
If the port is bound only to the local machine, public access must go through the reverse proxy. Check whether the proxy upstream is written as the container internal address, the host address or the wrong port.
First check the OpenList logs and upstream driver errors, then test a small file. Common causes include expired tokens, wrong root path, upstream returning 403, expired time signatures, insufficient object storage permissions or restricted outbound connections.
First confirm the browser, upstream driver and actual file encoding, then check the version and driver logs. Do not immediately batch-rename the original files; reproduce in a test directory first and keep the original paths.
Check HTTPS, username, password, path and whether the reverse proxy supports WebDAV methods. Some proxies only allow GET/POST by default and may block PROPFIND, PUT, DELETE. First connect a desktop client to a test directory, then open the production directory.
Test the upstream cloud drive direct link, the speed from the VPS to the upstream, the VPS public egress and the client route separately. Do not look only at VPS CPU. For proxy downloads, bandwidth, connection counts, upstream rate limits and object storage outbound costs are usually more critical than CPU.
OpenList can connect to many storage services, but "technically mountable" does not mean "can be freely shared publicly." Before going live, please confirm:
- Accounts and files are within the scope you or your team are authorized for;
- Sharing, online playback and downloads comply with upstream platform terms;
- Copyrighted files have legitimate usage rights;
- The service is not used to bypass access controls, download limits or regional restrictions;
- Public directories have authentication, expiring links and access logs enabled;
- Third-party account cookies, tokens and private files are not handed to untrusted administrators.
If the goal is team file collaboration, prefer a system with members, auditing, revocation and version control, rather than exposing a cloud drive root directory directly.
Individual users can start with a 2-core, 2GB, 40GB NVMe VPS running OpenList, Caddy and a small number of storage drivers. Once the file volume grows, online playback begins or multiple people access it, upgrade memory, disk and bandwidth, and migrate large files to object storage.
The recommended go-live order is:
- Pin the OpenList version and persist
/etc/openlist; - Listen only on the local port;
- Access via a dedicated domain and HTTPS;
- Create a low-privilege user and a test storage;
- Configure rate limits, traffic alerts and off-site backups;
- Verify with small files, large files, WebDAV and a recovery drill;
- Only then open team or public sharing.
OpenList is best used as a "unified entry point and access layer." As long as you plan authorization, networking, backups and cost boundaries in advance, it can make multi-cloud-drive and self-hosted storage easier to manage.