WIKI.org

Notes on WebDAV

Demo

Here’s a demo of how organice works when logging in to a WebDAV server.

On the left, you see a branded version of OwnCloud, on the right you see organice. After logging in and making a minute change, you can see that the last edited timestamp in OwnCloud changes. Also, we’re verifying the change directly in Emacs using Emacs and you can see the change has also been synchronized to my local machine.

Missing CORS headers

If your back-end doesn’t have the necessary CORS headers set (more info in the README, this is what the error will look like:

Setup your own WebDAV Server with Apache2 on Debian

For testing purposes, here are the instructions to setup WebDAV locally on your machine using Apache2 using Debian. These instructions are not meant to be used in production, though.

Initial package installation

sudo apt -y install apache2-utils apache2

Set up a new vhost for webdav

/etc/apache2/sites-available/webdav.conf

Alias /webdav /srv/dav/

RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L]

<Location /webdav>
    Options Indexes
    DAV On
    AuthType Basic
    AuthName "webdav"
    AuthUserFile /srv/dav/.htpasswd
    Require valid-user

    Header always set Access-Control-Allow-Origin "*"
    Header always set Access-Control-Allow-Methods "GET,POST,OPTIONS,DELETE,PUT,PROPFIND"
    Header always set Access-Control-Allow-Headers "Origin,Accept,X-Requested-With,Content-Type,Access-Control-Request-Method,Access-Control-Request-Headers,Authorization,X-CSRF-Token,Depth"
    Header always set Access-Control-Allow-Credentials true

    Require all granted
</location>

Enable Apache modules

sudo a2enmod headers
sudo a2enmod dav*
sudo a2enmod rewrite
sudo a2ensite webdav

Setup folder, password and rights

sudo mkdir /srv/dav
sudo htpasswd -c /srv/dav/.htpasswd webdav
sudo chmod 770 /srv/dav; sudo chown www-data. /srv/dav
sudo service apache2 restart

Test webdav access using a commandline tool

sudo apt -y install cadaver
cadaver http://localhost/webdav/

Configuring Nextcloud behind haproxy to allow WebDAV

If you’re running Nextcloud behind haproxy it’s entirely possible to use it with Organice using WebDAV. …it’s just a little bit convoluted.

The first part is the haproxy config. It should look a little bit like this:

frontend www
  acl host_nextcloud hdr(host) nextcloud.example.org
  acl path_nextcloud_public_webdav path_beg /public.php/webdav
  # Because we need to inspect the path in the backend section we set a variable
  # containing the path.
  http-request set-var(txn.path) path
  # Because the OPTIONS requests from Organice doesn't include authentication we
  # need to fake it. We can do that by redirecting all requests that satisfy these conditions:
  #
  # + host is Nextcloud
  # + path is for public webdav
  # + HTTP method is OPTIONS
  use_backend always200ok if host_nextcloud path_nextcloud_public_webdav METH_OPTIONS

# haproxy doesn't really have a way of returning an arbitrary response, unless
# you want to drop down to Lua. There's no need for that, though, as this works
# perfectly fine. This backend doesn't have any servers attached, so it'll
# always result in a 503. We override the 503 by setting a custom errorfile,
# which incidentally looks just like a HTTP 200 response and contains all the
# headers we need to satisfy a CORS request.
backend always200ok
  mode http
  errorfile 503 /etc/haproxy/errors/200-ok.http

# The Nextcloud server backend is configured here. We inject CORS headers if URL
# starts with `/public.php/webdav`.
backend nextcloud
  mode http
  option httplog
  acl is_webdav var(txn.path) -m beg /public.php/webdav
  http-response add-header Access-Control-Allow-Origin "*" if is_webdav
  http-response add-header Access-Control-Allow-Methods "GET,POST,OPTIONS,DELETE,PUT,PROPFIND" if is_webdav
  http-response add-header Access-Control-Allow-Headers "Origin,Accept,X-Requested-With,Content-Type,Access-Control-Request-Method,Access-Control-Request-Headers,Authorization,X-CSRF-Token,Depth" if is_webdav
  http-response add-header Access-Control-Allow-Credentials "true" if is_webdav
  server backend01 127.0.0.1:8001

The errorfile needs to look something like the below. Note that the text below has carriage returns (13, o15 or 0x0d); these are required as per the HTTP RFC!

HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: close
Content-Type: text/html
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,OPTIONS,DELETE,PUT,PROPFIND
Access-Control-Allow-Headers: Origin,Accept,X-Requested-With,Content-Type,Access-Control-Request-Method,Access-Control-Request-Headers,Authorization,X-CSRF-Token,Depth
Access-Control-Allow-Credentials: true

<html><body><h1>200 Stuff is good!</h1>
Something something dark side.
</body></html>

Nextcloud sharing

In order to share a document using WebDAV you might be inclined to try to follow the official documentation, but it can be a tad confusing. Here’s the executive summary for how to share things from Nextcloud using WebDAV:

• share a link to a folder/file
• remove everything but the token from the link; the token matches /[a-zA-Z0-9]+$/ (hit the button right of “Share link” if using the web interface)
• use these details when logging in:

  URL

  https://nextcloud.example.org/public.php/webdav

  Username

  the token, e.g. ed65Fxw9Bz3MTn3

  Password

  if you’ve set a password for the shared folder, here’s where you input it

Building this documentation

This comprehensive documentation is an aggregation of multiple files which all reside in the organice code repository (README.org, WIKI.org, CONTRIBUTING.org and CODE_OF_CONDUCT.md).

Building this documentation is part of the CI/CD workflow. The actual compilation happens here.