Skip to content

Latest commit

 

History

History
350 lines (278 loc) · 14.4 KB

WIKI.org

File metadata and controls

350 lines (278 loc) · 14.4 KB
Raw

FAQ

Synchronization back-ends

Dropbox

Permissions (“Full Dropbox” vs. “App folder”)

The reference organice host https://organice.200ok.ch/ has the permission type ”Full Dropbox”. This serves many users well - especially those who have Org files in various locations that they want to access.

If you’re a user and have concerns to give an application full access to your Dropbox, here are your options:

  1. You might not need to change anything after reading this: organice is a front-end application, there is no back-end and no monitoring whatsoever. So, when you login to Dropbox, only your browser will have access to your Dropbox. So, from a security perspective, you’re not giving too much access to a server - your data cannot be seen by anyone else but you.
  2. organice is a free and open source application. Therefore, you can review the synchronization code anytime. For Dropbox, this is pretty straight forward since the synchronization code is less than 200loc.
  3. If you still have concerns, you can take full control! Since organice is free and open source, you are free to host it yourself. You can also create your own integration with Dropbox and select the permissions as you wish. Here’s more documentation on deploying organice.

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.

https://github.com/200ok-ch/organice/wiki/videos/demo-webdav.gif

WebDAV test server

For testing purposes, we use a Docker image with a proven and well documented server: Apache2 running on Debian. You can build the Docker image yourself - and customize the Apache configuration to your needs:

docker build -f doc/webdav/Dockerfile -t apache-webdav .

or with docker-compose:

docker-compose build apache-webdav

Then run the Apache2 WebDAV server with:

docker run -dit --name apache-webdav-app -p 8080:80 apache-webdav

or with docker-compose:

docker-compose up apache-webdav

On your host machine, you can now login with any WebDAV client using the URL http://localhost:8080/webdav. There is no authentication configuration, so any user account works (including omitted user accounts). It goes without saying that if you wanted to use this for production, please enable authentication. Within the test image, you’ll find the sample.org file, so you can get started developing and testing right away.

For testing WebDAV outside of organice, and you’re an Emacs user, you can open this link (C-c C-o). Then, you will get a TRAMP session with dired open and you’ll see the sample file. You can interact with it like in any other dired buffer. Obviously, this link will not work when looking at the documentation in the browser, you’ll have to open the file WIKI.org in Emacs.

If you prefer a command line client, you could use cadaver. Install and use it like this:

sudo apt -y install cadaver
cadaver http://localhost:8080/webdav/
Bug reports

If you have any trouble connecting to WebDAV using organice, it could be your setup (please consult CORS and Gotchas with WebDAV). In any case, if you want to open a bug report, please document your issue by referencing how it doesn’t work using the official WebDAV test server.

CORS

Since organice is a front-end application, it will login with JavaScript from within the browser - in turn the Cross-Origin Resource Sharing (CORS) headers must be set appropriately. If they are not set, you will not be able to login to your service from a browser. Alternatively, if you’re using a server like Apache or Nginx, you can simply get around CORS by hosting organice on the same domain as your service.

Please note, that when your back-end does not set the correct CORS headers, organice cannot show you a really semantic error message on that. The reason is that browsers hide this information from JavaScript. You will simply get a network error. However, you can easily debug it yourself by looking into the JavaScript console. No worries, you don’t have to be a (JavaScript) developer to find out about that - here’s a screencast showing you how to do it:

https://github.com/200ok-ch/organice/wiki/videos/demo-webdav-failing-cors.gif

Gotchas with WebDAV

preflight request doesn't pass access control check error

If you are getting an error like

Access to XMLHttpRequest at 'https://my.site/dav/' from origin
'https://organice.200ok.ch' has been blocked by CORS policy: Response
to preflight request doesn't pass access control check: It does not
have HTTP ok status.

then something is wrong with your webserver config. You can check whether a CORS preflight check is returning the right headers via:

curl -v -X OPTIONS https://my.server/webdav/

# For the official organice Apache2 WebDAV test server:
# curl -v -X OPTIONS http://localhost:8080/webdav/

The output should include lines like this:

...
< HTTP/1.1 200 OK
...
< 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
< Allow: OPTIONS,GET,HEAD,POST,DELETE,TRACE,PROPFIND,PROPPATCH,COPY,MOVE,LOCK,UNLOCK

If your server doesn’t give a 200 OK response, or if the Access-Control-Allow-* headers are missing, you may find these articles helpful:

Using Apache RewriteEngine

If your WebDAV directory happens to be not only on the same webserver, but also within a subdirectory of the directory containing a .htaccess file containing a RewriteRule that also applies to the WebDAV directory (for example like this), then you will need to create another .htaccess file in the top-level WebDAV directory containing this:

RewriteEngine Off

Otherwise any attempts to use WebDAV to upload new files via HTTP PUT requests will fall foul of the /index.html rewrite rule above, resulting in a 403 Forbidden response.

Another way to avoid this more selectively is to precede that rule with:

RewriteCond %{REQUEST_METHOD} !PUT
Symlinks don’t work

Unfortunately, symlink support never made it into Apache’s =mod_dav=.

Bind-mounts of individual files don’t work

In an Apache mod_dav context, unfortunately you can’t use bind mounts of a single file instead of symlinks, because mod_dav attempts to write any changes to a file atomically, by first writing to a temporary file and then atomically renaming it to the target file, and Linux prevents renaming to bind mounts with a Device or resource busy error.

HTTP PUT requests fail with 403 Forbidden

As mentioned in the section routing, you should avoid having mod_rewrite rules apply to (PUT) requests in the WebDAV directories.

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 an 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

Can we add feature X from plugin Y?

organice is an implementation of Org mode (see What does this project do?). Therefore, it is important that the changes in the markup made by organice are 100% compatible with Org mode itself.

Hence, if feature X from plugin Y can be implemented in a compatible way, and the feature follows the contribution guideline, then: Yes, the feature can be added to organice.

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).

To build the documentation locally, run make docs.

Building the documentation and uploading it to https://organice.200ok.ch/documentation.html is part of the CI/CD workflow. The actual compilation happens here and the result gets uploaded here.