bfren/nginx-webdav repository overview

⁠Nginx + WebDAV

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

A very simple WebDAV⁠ file server: the files in /www, shared over HTTP so they can be browsed, downloaded and (if you allow it) uploaded and changed.

It is Nginx⁠ with:

• nginx's WebDAV module, plus the dav-ext module for the PROPFIND and OPTIONS methods WebDAV clients use to list folders
• a browsable index page for each folder
• read-only access by default - turn on writing with one environment variable
• no upload size limit

There is no authentication. Run it on a private network, or behind a reverse proxy that adds a login - Caddy Proxy⁠ can do this.

⁠Quickstart

Share the files in ./files (read-only) on port 8080:

docker run -d --name dav -p 8080:80 -v ./files:/www quay.io/bfren/nginx-webdav

Or with Docker Compose, allowing changes:

services:
  dav:
    image: quay.io/bfren/nginx-webdav:7.3
    environment:
      - BF_NGINX_WEBDAV_METHODS=PUT DELETE MKCOL COPY MOVE
    ports:
      - "8080:80"
    volumes:
      - ./files:/www

Open http://localhost:8080 in a browser, or connect a WebDAV client to the same address.

⁠Features

• 📂 Browse folders in a web browser, or connect with a WebDAV client
• 🔒 Read-only unless you enable the write methods
• ⬆️ No upload size limit, and folders are created as needed when uploading
• 🧩 Add your own nginx configuration to the server block, in /etc/nginx/custom
• 🗜️ Everything from Nginx⁠: compression, logs, daily reload and a health check

⁠Tags

Images are published to Docker Hub (bfren/nginx-webdav) and Quay.io (quay.io/bfren/nginx-webdav) for linux/amd64, linux/arm/v7 and linux/arm64. There is one build, on nginx 1.30 and Alpine 3.24.

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

Nginx⁠ adds the nginx variables (access log, health check URI, …), and Alpine + S6⁠ adds timezone and cron.

⁠How It Works

⁠Starting

When the container starts, Nginx⁠ sets up nginx, then this image replaces the default site with a WebDAV server generated from a template (/etc/nginx/sites/localhost.conf), using the environment variables above. The nginx image's usual set-up of /www/public (creating it, adding a welcome page, setting ownership) is turned off - your files are left exactly as they are.

⁠Permissions

nginx runs as the www user (UID 1000), so:

• to read files, they must be readable by that user or by everyone
• to change files, /www (and anything in it you want to change) must be writable by UID 1000 - e.g. chown -R 1000:1000 ./files on the host

New files and folders are owned by www, with permissions set by BF_NGINX_WEBDAV_ACCESS.

⁠Custom configuration

Every .conf file in /etc/nginx/custom is included inside the server block, so it can contain anything valid there - including location blocks. For example, to allow longer uploads:

# /etc/nginx/custom/timeouts.conf
client_body_timeout             300s;

Earlier versions included /etc/nginx/sites/custom.conf instead. If you mounted a file there, move it to /etc/nginx/custom/ - anything left in /etc/nginx/sites is now only included at the http level.

⁠Health check, logs and reloading

These come from Nginx⁠. The health check loads http://localhost, which is the index page for /www.

⁠Building on this image

FROM quay.io/bfren/nginx-webdav:7.3

COPY ./overlay /
RUN bf-install

See Nginx⁠ for the rest.

⁠Testing

./test.nu        # builds the image and runs /test

/test runs this image's tests alongside the base images' tests, and fails if tests don't execute. They check that the dav-ext module is installed, and generate the site from its template - read-only and with the write methods enabled - checking the settings and that nginx -t accepts it, including with a location block in /etc/nginx/custom.

⁠Troubleshooting

⁠Uploads fail with 405 Not Allowed

The server is read-only - set BF_NGINX_WEBDAV_METHODS to the methods you want to allow.

⁠Uploads fail with 403 Forbidden or 500

The www user (UID 1000) can't write to /www - change the ownership or permissions of the folder on the host.

⁠The container stops at start-up

nginx's configuration test failed - often because of a file in /etc/nginx/custom, or a server-level file left in /etc/nginx/sites (see Custom configuration⁠). Check docker logs.

⁠My file manager connects, but read-only

Some clients (e.g. macOS Finder and Windows Explorer) need WebDAV locking (LOCK and UNLOCK) before they will write, and this image doesn't enable it. Use a client that doesn't need locks, such as Cyberduck⁠ or rclone⁠, or a command-line tool such as curl.

⁠FAQs

⁠How do I add a password?

Put a reverse proxy in front of it that handles logins, such as Caddy Proxy⁠. Never expose this image directly to the internet.

⁠Licence

⁠Copyright