Operating System Debian

How to Deploy a WebDAV Server with WsgiDAV on Debian 13

Set up a WebDAV file share on Debian 13 with WsgiDAV: virtual environment, systemd service, user accounts, and Nginx with a Let's Encrypt certificate in front.

WsgiDAV is a WebDAV server written in Python. It publishes a directory over HTTP so that file managers on Windows, macOS and Linux can mount it like a network drive. This guide installs WsgiDAV on Debian 13 in a Python virtual environment, runs it as an unprivileged systemd service on a local port, and puts Nginx with a Let's Encrypt certificate in front of it. The same commands work on Debian 12; only the Python version differs (3.11 instead of 3.13).

Debian 10 is end-of-life, and installing Python programs system-wide with sudo pip3 install, as older tutorials do, is refused on current Debian releases because the system Python is marked as externally managed. A virtual environment is the supported way.

Requirements

  • A server running Debian 13 and a user with sudo rights.
  • A host name such as dav.example.com with an A (and, if you use IPv6, AAAA) record pointing to the server.
  • TCP ports 80 and 443 reachable from the internet.

Step 1: Install WsgiDAV in a virtual environment

Install the Python tooling, then create a system account and the directories for the service:

sudo apt update
sudo apt install -y python3-venv
sudo adduser --system --group --home /srv/dav wsgidav
sudo mkdir -p /etc/wsgidav

/srv/dav is the directory that will be shared; it belongs to the new wsgidav user. Create the virtual environment and install WsgiDAV together with Cheroot, the WSGI server the project recommends, and lxml, an optional faster XML parser:

sudo python3 -m venv /opt/wsgidav
sudo /opt/wsgidav/bin/pip install --upgrade pip
sudo /opt/wsgidav/bin/pip install wsgidav cheroot lxml

Check the result:

/opt/wsgidav/bin/wsgidav --version -v

Step 2: Write the configuration

WsgiDAV reads a YAML file. Create /etc/wsgidav/wsgidav.yaml:

sudo nano /etc/wsgidav/wsgidav.yaml
host: 127.0.0.1
port: 8080
server: cheroot

provider_mapping:
  "/": "/srv/dav"

http_authenticator:
  domain_controller: null
  accept_basic: true
  accept_digest: true
  default_to_digest: true

simple_dc:
  user_mapping:
    "*":
      "deploy":
        password: "ChangeThisPassword"

dir_browser:
  enable: true

verbose: 3

What the sections do:

  • host and port: the server listens only on the loopback interface. Nginx will be the public endpoint.
  • provider_mapping maps URL paths to directories. You can add more shares, and mark one read-only by writing it as a mapping with root: and readonly: true.
  • domain_controller: null selects the built-in simple controller, which takes users from simple_dc.user_mapping. The "*" entry applies to every share that is not listed by name.
  • dir_browser gives a file listing when you open the URL in a web browser.

The file contains passwords in clear text, so restrict it to root and the service account:

sudo chown root:wsgidav /etc/wsgidav/wsgidav.yaml
sudo chmod 640 /etc/wsgidav/wsgidav.yaml

Step 3: Create the systemd service

sudo nano /etc/systemd/system/wsgidav.service
[Unit]
Description=WsgiDAV WebDAV server
After=network.target

[Service]
User=wsgidav
Group=wsgidav
ExecStart=/opt/wsgidav/bin/wsgidav --config /etc/wsgidav/wsgidav.yaml
Restart=on-failure
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now wsgidav
systemctl status wsgidav

A quick local test should answer with HTTP status 401, because no credentials were sent:

curl -i http://127.0.0.1:8080/

Step 4: Put Nginx and a certificate in front

Install Nginx and Certbot with its Nginx plugin:

sudo apt install -y nginx certbot python3-certbot-nginx

Create /etc/nginx/sites-available/dav.example.com:

server {
    listen 80;
    listen [::]:80;
    server_name dav.example.com;

    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_request_buffering off;
        proxy_read_timeout 300s;
    }
}

Three details matter for WebDAV:

  • client_max_body_size 0 removes Nginx's 1 MB upload limit.
  • The X-Forwarded-Proto and X-Forwarded-Host headers are the ones the WsgiDAV documentation uses for reverse proxies. WsgiDAV compares the Destination header of MOVE and COPY requests with them; without the headers, renaming a file through an HTTPS proxy fails with a 502 error.
  • proxy_request_buffering off streams uploads to WsgiDAV instead of writing them to a temporary file first.

Enable the site and request the certificate. Certbot adds the HTTPS server block and a redirect, and renews the certificate automatically.

sudo ln -s /etc/nginx/sites-available/dav.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d dav.example.com

If you use a firewall, allow ports 80 and 443 and leave 8080 closed.

Step 5: Test and connect

Upload a file and list the share with curl; it asks for the password:

echo hello > test.txt
curl --anyauth -u deploy -T test.txt https://dav.example.com/
curl --anyauth -u deploy -X PROPFIND -H "Depth: 1" https://dav.example.com/

The second command returns an XML listing that contains test.txt. To connect from a desktop:

  • Windows: File Explorer, "Map network drive", folder https://dav.example.com/.
  • macOS: Finder, Go, "Connect to Server", same URL.
  • Linux: enter davs://dav.example.com/ in GNOME Files or webdavs://dav.example.com/ in Dolphin.

Optional: log in with system accounts (PAM)

WsgiDAV can check passwords against the server's PAM stack instead of the YAML file. Install the extra dependency and change the authenticator section:

sudo /opt/wsgidav/bin/pip install "wsgidav[pam]"
http_authenticator:
  domain_controller: wsgidav.dc.pam_dc.PAMDomainController
  accept_basic: true
  accept_digest: false
  default_to_digest: false

pam_dc:
  service: "login"
  allow_users: "all"

PAM needs the clear-text password, so only Basic authentication is possible, which is acceptable here because clients reach the server through HTTPS only. Use deny_users with a list of names to exclude accounts such as root. Be aware that verifying other users' passwords normally requires the service to run as root, which gives up the isolation of the dedicated account, and that all files are still written with the service's own identity, not the identity of the user who logged in. For a handful of users, the YAML user list is the safer choice.

Maintenance

  • After editing the configuration: sudo systemctl restart wsgidav. Logs: journalctl -u wsgidav.
  • Updates do not come through apt. Upgrade inside the virtual environment and restart: sudo /opt/wsgidav/bin/pip install --upgrade wsgidav cheroot lxml.
  • After a Debian release upgrade that brings a new Python version, recreate the environment: delete /opt/wsgidav and repeat step 1.
  • File locks are kept in memory by default and are lost on restart. The documentation describes a persistent alternative, wsgidav.lock_man.lock_storage.LockStorageShelve, with a storage_path.

The full option list is in the WsgiDAV configuration documentation.

Frequently asked questions

Can WsgiDAV serve HTTPS itself, without Nginx?

Yes. The options ssl_certificate, ssl_private_key and ssl_certificate_chain make Cheroot terminate TLS. The service then needs read access to the private key and permission to bind port 443, which usually means running as root or adding extra plumbing; a reverse proxy avoids both and lets Certbot handle renewals.

Why does Windows refuse to connect or to copy large files?

The Windows WebDAV client rejects Basic authentication over plain HTTP, so always use the https:// URL. It also has its own client-side file size limit, set in the registry of the Windows machine, which is independent of anything on the server.

How do I add a read-only public share?

Add a second entry to provider_mapping, for example "/pub" with root: "/srv/dav-pub" and readonly: true, and allow anonymous access to it by adding "/pub": true under simple_dc.user_mapping.

Is there a Docker image?

The project publishes mar10/wsgidav on Docker Hub and labels it experimental. It serves the directory mounted at /var/wsgidav-root on port 8080. For a permanent server, the virtual environment described here is the documented installation method.

Share story:

Continue reading other guides on How VPS.