Deploy AList with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it easy to run AList as a unified file manager for all your storage providers.

This guide walks you through deploying AList with persistent configuration and automatic HTTPS. AList is a file list program that supports multiple storage backends including local storage, S3, Google Drive, OneDrive, WebDAV, FTP, and dozens more.

Prerequisites

• A VPS with at least 1 vCPU, 1 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., files.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  alist:
    image: xhofe/alist:latest
    restart: unless-stopped
    ports:
      - "5244:5244"
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=${TZ:-UTC}
    volumes:
      - ../files/alist-data:/opt/alist/data
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:5244/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: AList uses an embedded SQLite database by default. For larger deployments, you can configure it to use MySQL or PostgreSQL through the admin settings after initial setup.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
TZ	Server timezone	America/New_York
PUID	User ID for file permissions	1000
PGID	Group ID for file permissions	1000

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. AList's primary configuration (storage backends, users, settings) is managed through the web admin panel after deployment.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/alist-data — AList configuration, SQLite database, and cached files

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., files.yourdomain.com)
3. Set the container port to 5244
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your AList container. HTTPS is recommended for secure file access and WebDAV connections.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — the alist container should start
3. Check the Logs tab for the alist service. Look for the initial admin password in the startup logs: Initial password: xxxxxxxx
4. Open https://files.yourdomain.com in your browser — you should see the AList file browser
5. Click the login icon and sign in with username admin and the initial password from the logs
6. Change the admin password immediately via Settings > Profile
7. Add storage backends via Settings > Storage — configure local storage, S3, Google Drive, OneDrive, etc.

Troubleshooting

Forgot the initial admin password If you missed the initial password in the logs, you can reset it by running a command inside the container. In Dokploy, use the terminal to execute: ./alist admin set NEW_PASSWORD inside the AList container.

Storage backend shows "failed to list" error Each storage backend has specific authentication requirements. Double-check your API keys, tokens, or credentials in the storage configuration. For cloud providers like Google Drive or OneDrive, you need to complete OAuth authorization through the admin panel.

WebDAV connections failing AList provides WebDAV access at /dav/. Ensure your WebDAV client is connecting to https://files.yourdomain.com/dav/ with your AList credentials. Some clients require you to specify the port (443 for HTTPS).

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about AList in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running AList.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.