OpenAList Docker Setup and Secure Remote Access

Why run OpenAList, and why add a tunnel?

Many people end up with files scattered across a local disk, a NAS, and a few cloud drives. A file listing application gives all of that a single web front end, with browsing, previews and permissions in one place. OpenAList is one such application. Its project documentation describes support for multiple storage providers, including local storage, Aliyundrive, OneDrive and Google Drive, WebDAV access, light and dark modes, password protection for specific paths, and file preview for video, audio, office documents, PDF, code and images. It also lists batch download, single sign-on, offline download of torrent content to a chosen directory, a text editor, and a Crypt feature that lets you store encrypted data on a remote provider so the provider only sees the encrypted container.

The project is licensed under AGPL-3.0, and the latest release we reviewed is v3.45.31. That release's notes describe a security-related rebuild with Go 1.27.3 to distrust compromised eMudhra intermediate certificates. If you plan to modify the code and offer the result to others over a network, read the AGPL-3.0 text carefully, because that license has obligations around providing source for network use. We are not lawyers, and this is a general pointer rather than legal advice.

Running it at home or on a small server solves the "one place for my files" problem, but it creates a second one: the web UI is listening on a private address. To use it from a phone on mobile data, from an office, or to share a link with someone, you either open an inbound port on your router, set up a VPN, or use a tunnel. With Localtonet, the client on your machine makes an outbound connection to one of our relay servers, and the HTTP tunnel gives you a public HTTPS address that forwards to your local service. There is no inbound port forwarding, no firewall change and no public IP required. The tunnel only works while the client device is connected and the tunnel is running.

This guide keeps those two jobs separate on purpose. First we get OpenAList installed and verified locally, because a tunnel in front of a broken service only gives you a broken public URL. Then we publish it.

OpenAList is not OpenList: avoid mixing up the docs

The naming in this ecosystem is confusing, and it affects which commands you can safely copy. Alist is an older open-source file listing project. Community forks followed. The one in this guide is OpenAList, maintained by AlliotTech, described as a fork of Alist based on v3.45.0. A different project called OpenList, maintained by the OpenListTeam, has its own documentation, its own Docker image name (openlistteam/openlist), its own data path inside the container (/opt/openlist/data), its own admin password variable (OPENLIST_ADMIN_PASSWORD) and its own binary name.

This matters because search results often show OpenList instructions when you search for the Alist family. Some of those instructions, such as the container user changes after OpenList v4.1.0, the image suffixes like -aio, -ffmpeg and -lite, or the openlist admin random command, belong to OpenList. We have not confirmed that they apply to the OpenAList image or binary, so this guide does not use them. Where OpenAList details come from the project's README, we say so. Where the evidence is silent, we say that too.

Prerequisites

For the Docker path you need very little. Here is what to have in place before you start:

• A Linux, macOS or Windows machine that can run Docker, with Docker Engine (or Docker Desktop) installed and the daemon running. Check with docker version.
• Permission to run Docker commands, either as root, through sudo, or as a member of the docker group.
• TCP port 5244 free on the host. The README maps host port 5244 to container port 5244 and says the web UI is available at http://localhost:5244 after startup.
• A directory on the host to hold persistent data. Without a mounted volume, your configuration and database disappear when the container is removed.
• For the remote access step, a free Localtonet account and the Localtonet client installed on the machine that can reach port 5244.

Binary installs need the release archive from GitHub Releases for your operating system and architecture. Source builds additionally need Git, Go 1.27.1 or later, and a C compiler, because SQLite support uses CGO. We cover those paths briefly later, because the Docker route is the one the README documents with concrete flags.

Choosing the install method

Install OpenAList with Docker

Start by creating a host directory for the data. We use /opt/openalist/data as an example. The README specifies the path inside the container (/opt/alist/data), while the host path is your choice, so pick any location with enough space and sensible permissions.

sudo mkdir -p /opt/openalist/data

Then start the container. The image, the port mapping and the container-side data path come from the README. The flags -d, --restart=unless-stopped and --name are standard Docker options that we added for convenience, not requirements stated by the project:

docker run -d \
  --name openalist \
  --restart=unless-stopped \
  -p 5244:5244 \
  -v /opt/openalist/data:/opt/alist/data \
  alliot/alist:latest

Docker pulls the image on first use, creates the container and starts it in the background. The first start generates a random admin password, which we retrieve in the next section. If you prefer to keep the service off the network entirely until the tunnel is running, you can bind the published port to the loopback interface only by changing the mapping to -p 127.0.0.1:5244:5244. That is a general Docker feature rather than an OpenAList setting. With that mapping, the web UI is reachable only from the host itself, which is exactly what a Localtonet client running on the same host needs.

The same setup with Docker Compose

The README mentions a sample docker-compose.yml, but the exact file contents were not part of the evidence we could extract, so we do not reproduce it. Instead, here is a Compose file that expresses the same settings as the command above. Treat it as our translation, and compare it with the sample in the project README if you want to follow the maintainers' version exactly.

services:
  openalist:
    image: alliot/alist:latest
    container_name: openalist
    ports:
      - "5244:5244"
    volumes:
      - ./data:/opt/alist/data
    restart: unless-stopped

Save it as docker-compose.yml in a directory such as /opt/openalist, and run these commands from that directory:

docker compose pull
docker compose up -d

Compose creates a data directory beside the file the first time it runs, and your OpenAList database and configuration live there. Keep that directory in your backups.

Binary and source installs

If you cannot or do not want to use Docker, the README documents two other routes. We keep this section short, because the available evidence does not include the full command sequences for them, and we do not want to invent filenames or flags.

Prebuilt binary

Releases are published on the project's GitHub Releases page. The v3.45.31 release lists 22 assets, so pick the one that matches your operating system and CPU architecture. We cannot tell you the exact asset names from the evidence we have, so read the names on the release page. After extracting the archive, the README says to start the server with:

./alist server

The binary needs a place to write its data directory and must be able to bind port 5244. For anything beyond a quick test, run it under a process supervisor such as systemd so it restarts after reboots. The README evidence we have does not include a service unit, so you would write that yourself using your init system's documentation. The Docker route gives you restart handling with a single flag, which is one reason we lead with it.

Build from source

Building requires Git, Go 1.27.1 or later, and a C compiler, because SQLite is used through CGO. If the C compiler is missing, the build will not produce a working SQLite-enabled binary. The exact build commands and frontend assets handling were not in the evidence we could extract, so follow the README's build section for those. Source builds are mainly worthwhile if you want to audit the code, test a patch, or run on an architecture that has no prebuilt asset.

Find or set the admin password

The README describes two ways to get an initial admin password. By default it is generated randomly and appears in the container logs. Alternatively, you can set it yourself with the ALIST_ADMIN_PASSWORD environment variable.

Read the generated password from the logs

docker logs openalist

Scroll through the output on first start and look for the line that reports the creation of the admin user and its initial password. We do not quote the exact wording because we have only seen the wording of the related OpenList project, not confirmed output from this image. Search for "password" if the log is long:

docker logs openalist 2>&1 | grep -i password

The username is normally admin in this family of projects, but the OpenAList evidence we have does not state it explicitly. If the login rejects it, check the log line, which should name the account.

Set the password with an environment variable

To choose the password up front, add the variable when you create the container. Replace the placeholder with a strong value of your own, and do not reuse a password from another service:

docker run -d \
  --name openalist \
  --restart=unless-stopped \
  -p 5244:5244 \
  -v /opt/openalist/data:/opt/alist/data \
  -e ALIST_ADMIN_PASSWORD='choose-a-long-unique-password' \
  alliot/alist:latest

In Compose, add the same value under an environment: key of the service. Be aware that a password written in a Compose file or shell history is stored in plain text on disk, so keep that file private. A plain environment variable is also visible to anyone who can run docker inspect on the host.

Whichever route you use, sign in once, then change the password in the admin interface to something only you know. The generated password has been printed into a log file, and logs tend to get copied around.

Verify the installation locally

Before you involve any tunnel, confirm the service from the host itself. Work through these checks in order, because each one narrows down where a problem lives.

Only continue once step 5 works. A local storage entry that lists and previews a test file proves that the container, the volume mapping and the web application are healthy together.

Daily operations: logs, restarts, updates, backups

A file listing service is the kind of tool that quietly runs for months. These routine commands keep it that way. They use standard Docker behavior, not OpenAList-specific features.

Logs, stop and start

docker logs -f openalist
docker stop openalist
docker start openalist
docker restart openalist

With --restart=unless-stopped (or the equivalent Compose setting), Docker starts the container again after a host reboot unless you stopped it manually.

Updating

Because your data lives in the mounted directory, replacing the container does not remove your configuration. For a docker run deployment, pull the new image, remove the old container and start a new one with the same flags:

docker pull alliot/alist:latest
docker stop openalist
docker rm openalist
# then repeat your original docker run command

For Compose, run docker compose pull followed by docker compose up -d in the project directory. Back up the data directory before upgrades, and read the release notes. We could not see any migration notes in the release we reviewed, which only mentioned the security rebuild, but future releases may differ.

Backups

Copy the whole host data directory (for example /opt/openalist/data) to another disk or machine. For the most consistent copy, stop the container first, because the application uses a database file. Test a restore at least once by starting a second container against a copy of the backup on a different port.

Time zone and file permissions

Some container images read a TZ variable for the time zone and a UMASK variable for file creation permissions. The related OpenList documentation lists those, but we have not confirmed that the alliot/alist image uses them, so we do not include them in the commands above. If you see permission errors on a mounted directory, the cause is usually that the user inside the container cannot write to the host directory. Docker has a general --user UID:GID option for running a container as a particular user, but we have not verified how this image behaves under it, so test it on a non-critical directory first.

Reach OpenAList remotely with a Localtonet HTTP tunnel

Everything up to this point is the OpenAList installation. The tunnel is a separate layer that we add on top, and the project README does not cover it. We describe the Localtonet side using our documented workflow for HTTP tunnels. For the authoritative field list in the current dashboard, see the Localtonet HTTP tunnel documentation, since labels and options can change over time.

Configure the tunnel

The sequence below follows our general Localtonet workflow. We do not list individual dashboard field names beyond what our documentation establishes, because the exact UI can vary by client version. Use the HTTP tunnel documentation for the current screen layout.

What the HTTP tunnel covers

An HTTP tunnel forwards web traffic, so it covers the browser-based interface that listens on 5244. The README also mentions WebDAV, FTP, SFTP and S3-compatible access, but the evidence we have gives no separate port numbers for any of them, so we will not assume any. WebDAV is built on HTTP as a general networking fact, which suggests it may be reachable through the same web endpoint, but we have not confirmed the exact WebDAV path or setting in OpenAList. Check the in-app settings or the project documentation for the version you run. FTP and SFTP use their own protocols, so they would need a different tunnel type and a port you have confirmed from your own configuration, not from this article.

Secure the public exposure

A tunnel makes your service reachable from the internet. It does not change who is allowed to use it, and it does not bypass your application's authentication. The safety of the public address depends mostly on how well OpenAList itself is configured. Treat this checklist as mandatory before you share the URL.

• Change the admin password immediately, and use a long unique value. The initial password was printed to logs or set in an environment variable, so assume it has leaked into more places than you want.
• Review guest and anonymous access. Check the admin settings for whether visitors can browse without signing in, and whether they can upload, delete, rename or move files. The project lists web upload with visitor access as an option, which is useful in some setups and dangerous in others.
• Use protected routes. The project documents password protection for specific paths. Apply it to any directory that should not be public.
• Use least privilege for storage. Mount into the container only the host directories you want listed, and avoid mounting your home directory or the filesystem root. Where possible, use read-only mounts for content that OpenAList only needs to display.
• Mind the cloud credentials. If you connect cloud storage accounts, the application holds access to them. A compromised admin account becomes a path into those accounts.
• Keep the software current. The latest release we reviewed was a security-driven rebuild. Subscribe to the repository's releases and update regularly.
• Stop the tunnel when you do not need it. A stopped tunnel is a closed door. Delete tunnels you no longer use.
• Keep the token private. Anyone with your Localtonet auth token could run tunnels as your device. Never place it in screenshots, repositories or chat messages.

Does a random subdomain protect the service?

A random subdomain is hard to guess, but an unguessable address is not an access control. Addresses show up in browser history, chat messages and logs. Rely on the application's authentication, and treat the address as public once you have shared it.

Troubleshooting

The container exits right after starting

Run docker logs openalist. Typical causes are a port conflict (something else already uses 5244, in which case Docker reports the error when starting), a data directory that the process cannot write to, or a typo in the image name. If port 5244 is taken, change only the host side of the mapping, for example -p 8080:5244, and then use 8080 locally and as the tunnel target.

I cannot find the admin password

The password is printed on first start, so run docker logs openalist and search for "password". If you removed and recreated the container with the same data volume, the account already exists and no new password is printed. If your logs have rotated, you may not be able to retrieve it. See the note on resets in the password section, and check the project documentation for your version.

The page loads on localhost but not from another device on my LAN

Check whether you bound the port to 127.0.0.1 only. That mapping blocks other machines by design. Also check the host firewall for port 5244.

My data disappeared after I recreated the container

This happens when the volume was not mounted, or when you mounted a different host path the second time. Inspect the mounts with docker inspect openalist and confirm that a host directory maps to /opt/alist/data. Always use the same host path in every run.

Permission denied on a mounted directory

The user inside the container cannot read or write the host directory. Check ownership and mode on the host. Running the container with --user UID:GID matching the directory owner is a general Docker option, but we have not confirmed this image's behavior with it, so test it on a non-critical path first.

The tunnel is created but the public address shows an error

• Confirm the tunnel was actually started, not only created.
• Confirm the Localtonet client is still connected on the device.
• Confirm the local target matches the real address and port. Test curl -I http://127.0.0.1:5244 on the same machine as the client.
• If the client runs on a different machine from Docker, make sure that machine can reach the Docker host's IP and port.

The UI loads remotely, but links or assets point to the wrong address

Applications that build absolute links sometimes need to know their public address. We have not confirmed which setting, if any, OpenAList uses for that, so look through the site-related options in the admin settings if links point to localhost. Report the behavior to the project if you believe it is a bug.

Large file uploads or downloads fail through the tunnel

Test the same transfer directly on the LAN first. If it works locally and fails remotely, the limit may sit in a browser timeout, your upload bandwidth or an intermediate layer. We do not publish bandwidth or size limits for tunnels here, because such details can vary by plan, so check the current Localtonet documentation and your plan before you plan large transfers.

When another Localtonet feature is a better fit

OpenAList is a full application with storage drivers, previews and user management. If your only goal is to publish a folder of files, a simpler option exists in our own product. Localtonet File Server publishes a local folder path directly, with three sub-types: Default (a browser-based file manager), SFTP (for SFTP clients, automation and CI/CD) and WebDAV (to mount the folder as a network drive). You can read more in our File Server tunnel guide.

These are not mutually exclusive. Many people run an application like OpenAList for browsing and previews, and use other tools for different jobs.

Frequently asked questions