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
sudorights. - A host name such as
dav.example.comwith 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:
hostandport: the server listens only on the loopback interface. Nginx will be the public endpoint.provider_mappingmaps URL paths to directories. You can add more shares, and mark one read-only by writing it as a mapping withroot:andreadonly: true.domain_controller: nullselects the built-in simple controller, which takes users fromsimple_dc.user_mapping. The"*"entry applies to every share that is not listed by name.dir_browsergives 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 0removes Nginx's 1 MB upload limit.- The
X-Forwarded-ProtoandX-Forwarded-Hostheaders are the ones the WsgiDAV documentation uses for reverse proxies. WsgiDAV compares theDestinationheader ofMOVEandCOPYrequests with them; without the headers, renaming a file through an HTTPS proxy fails with a 502 error. proxy_request_buffering offstreams 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 orwebdavs://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/wsgidavand 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 astorage_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.