Integrating Radicale with FileBrowser Quantum

[cryinkfly]

Description

All changes are considered, but for now please only add english documentation.

• Documentation is english only.
• Documentation is accurate to the latest version of FileBrowser Quantum.

Additional Details

- For Radicale, parts of the integration guide have already been added, but it is not yet complete!

[cryinkfly]

I have reopened this pull request because it is related to the following pull request.
However, the documentation is not finished yet and has not been migrated from my repositories for Docker and Podman.

[BaccanoMob]

Great work! Its neatly organized. Have questions on a few things.

[BaccanoMob]

Here you say, you need radicale, quantum and clients. But the example configuration uses NPM.

Can you provide how to make it for just these 2 containers alone?

[cryinkfly]

In my example, I'm using the Nginx proxy manager. However, it could be Caddy or another proxy. The important thing is that the proxy has access to the specific network so that HTTPS connections are possible, no host ports need to be exposed by FileBrowser and Radicale, and so that FileBrowser can communicate with Radicale for user and token verification via the /location settings. Currently, only users are being verified.

[BaccanoMob]

The important thing is that the proxy has access to the specific network so that HTTPS connections are possible,

Is this setup only possible with proxy and/or HTTPS?

1. Radicale server is running (Docker or Podman).
2. FileBrowser Quantum is configured to communicate with Radicale.

For minimal configuration, I thought you could just use radicale, quantum alone with http given what you mentioned in the about.md?

[cryinkfly]

I tested it myself using a proxy, since I could configure the locations there. An HTTPS connection would be possible via the example URL, and within the internal network of FileBrowser and Radicale, these two containers communicate via HTTP. So, Radicale and FileBrowser each run as separate containers, but within the same pod on my system and are on the same network as the proxy.

[BaccanoMob]

Can you put the permissions you set for the API Key here? Or if it was the minimal toggled on ?

I think API Key is the term currently used.

[cryinkfly]

It's perfectly sufficient to select the minimal option, as only the user and token will be verified later. Calendars, reminders, and contacts will be stored in Radicale and are linked.

However, the token isn't currently being verified because we might need to implement or modify something in FileBrowser so that the username and token are checked for Radicale before access to Radicale is granted.

So, for example, if I enter https://cloud.example.org/caldav as the link and the username is steve (which exists in FileBrowser), Radicale can currently authenticate the user via FileBrowser and proxy settings without a password. It doesn't matter if I enter just a letter or something else as the password in the client... because the password isn't currently being checked. But I can then use the calendar, etc. This is obviously not yet suitable for production use.

[gtsteffaniak]

"Create a token without customization."

I removed the "minimal token" language because its not exactly accurate.

[BaccanoMob]

I think Getting Help is not needed because it doesn't belong to Troubleshooting. It is intuitive to raise an GitHub issue if something is not working.

[BaccanoMob]

Dont put links in header. This gives weird naming in the TOC in the right side.

[gtsteffaniak]

@cryinkfly fyi

[Kurami32]

I'm not into Radicale, but may I ask about which debug mode you're talking about?

[cryinkfly]

For example, you can check certain things with the web browser in development mode, but this is also possible with Docker and Podman. For me under Podman in rootles mode with the quadles I can do 'podman logs containername' or 'systemctl --user status containername.service' etc.

[Kurami32]

@cryinkfly First of, great work!

But if I understand correctly, Radicale is a WebDAV client, just that here, we're creating a custom location via proxies into the same Filebrowser sub-domain, right?

I'm not sure if we should have the guides directly in docs/integrations since is not a first-party integration supported officially by Filebrowser like OnlyOffice. (which also has code in the codebase)

Also I think that some things can be simplified if we move all into user-guides, it may be just a single guide and then put it into the WebDAV clients folder (discussed in #39), or may be into a single folder with the client name (in this case Radicale).

[BaccanoMob]

But if I understand correctly, Radicale is a WebDAV client

@Kurami32 Its also a WebDAV like server, but for CalDAV (calendar) and CardDAV (contacts). Radicale does not fall under clients but as an integration like OnlyOffice.

I'm not sure if we should have the guides directly in docs/integrations since is not a first-party integration supported officially by Filebrowser like OnlyOffice.
Also I think that some things can be simplified if we move all into user-guides,

@cryinkfly I also feel this should be under User Guide only. Due to

1. This requires a reverse proxy to integrate.
2. Authentication is not reliable since you mention this guide only uses the user name and ignores the password.
3. Above point makes it more insecure even with HTTPS if since REMOTE_USER headers can be manipulated since it allows access to the network via proxy.

But the idea is good for simple use case for oneself or small family.

---

@gtsteffaniak Do you think Radicale can be integrated with FileBrowser? If Radicale could be integrated, FileBrowser will be All-in-one CalDAV/CardDAV/WebDAV solution, with a possibility of FileBrowser being a Radicale web frontend as well (AKA you can make/view calenders/contacts and use them across devices).

Main reason I stopped using Radicale was the WebUI is not maintained. So it would be cool if FileBrowser is at some point.

The best solution I could think of to integrate successfully is use FileBrowser as reverse proxy itself for /caldav and /cardav endpoints and keep Radicale accessible only via FileBrowser (Mainly to avoid users using REMOTE USER headers manually). This will allow minimal configuration externally.

[cryinkfly]

cryinkfly I also feel this should be under User Guide only.

As long as nothing is added to the core of FileBrowser Quantum for proxy-free integration, then that would definitely be the right place. It can always be added later in the other location.

---

The best solution I could think of to integrate successfully is use FileBrowser as reverse proxy itself for /caldav and /cardav endpoints and keep Radicale accessible only via FileBrowser (Mainly to avoid users using REMOTE USER headers manually). This will allow minimal configuration externally.

That's exactly how the OpenCloud project does it. That's why you would have to build something into the Wuantum file browser core that can be activated by the user if necessary.

With OpenCloud, for example, I don't necessarily need a proxy! Feel free to take a look proxy.yaml here: https://github.com/cryinkfly/podman-rootless-quadlets/tree/main/quadlets/opencloud-with-radicale

[gtsteffaniak]

This looks very well put together -- this type of thing is what I want the user guides section of the docs for. I want more community guides for things like this.

However, I am not sure this belongs in the integrations portion of the official docs, which is generally for first-party integrations like onlyoffice and ffmpeg.

Just to confirm, this is all supported by the main branch of the official filebrowser quantum repo correct? If so, I think the integrations guide could be removed and this would sit in the user guides section only, since no actual integration configuration on filebrowser quantum is needed.

[cryinkfly]

I'm now experimenting a bit with:

curl -v -H "Authorization: Bearer <USER-TOKEN>" https://cloud.example.org/api/users

... and the check works... now I just need to somehow connect this to the proxy and Radicale.

[cryinkfly]

This code at least checks the token and username. And if the username and token don't match, then no folder will be created at Radical.

Here is a config in mine Nginx Proxy Manager:

#################################################
# 1. Interner Auth-Check gegen FileBrowser
#################################################
location = /_auth_filebrowser {
    internal;

    proxy_pass http://filebrowser-quantum:80/api/users;  # Token prüfen
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    # Authorization-Header vom Client weiterreichen
    proxy_set_header Authorization $http_authorization;

    # Host & IP
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # Auth-Request: nur Statuscode beachten, Body egal
}

#################################################
# 2. Fehlerbehandlung
#################################################
error_page 401 = @auth_failed;
error_page 403 = @auth_failed;

location @auth_failed {
    return 401 "Access denied";
}

#################################################
# 3. well-known CalDAV / CardDAV (keine Redirects!)
#################################################
location = /.well-known/caldav {
    auth_request /_auth_filebrowser;
    proxy_pass http://filebrowser-quantum:5232;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Username direkt vom Client
    proxy_set_header X-Remote-User $http_x_username;
    proxy_set_header X-Script-Name /caldav;
}

location = /.well-known/carddav {
    auth_request /_auth_filebrowser;
    proxy_pass http://filebrowser-quantum:5232;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Username direkt vom Client
    proxy_set_header X-Remote-User $http_x_username;
    proxy_set_header X-Script-Name /carddav;
}

#################################################
# 4. CalDAV
#################################################
location /caldav/ {
    auth_request /_auth_filebrowser;

    proxy_pass http://filebrowser-quantum:5232;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Username direkt vom Client
    proxy_set_header X-Remote-User $http_x_username;
    proxy_set_header X-Script-Name /caldav;
}

#################################################
# 5. CardDAV
#################################################
location /carddav/ {
    auth_request /_auth_filebrowser;

    proxy_pass http://filebrowser-quantum:5232;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Username direkt vom Client
    proxy_set_header X-Remote-User $http_x_username;
    proxy_set_header X-Script-Name /carddav;
}

And with this command I was able to test it:

curl -v   -H "Authorization: Bearer TOKEN"   -H "X-Username: test"   https://cloud.example.org/caldav/

However, there are still problems with the clients that I need to resolve.

[gtsteffaniak]

I don't want to slow any of these docs down, but I would encourage you to take your time on both of these open user guides.

Since webdav won't be official until v1.3.0, you'll have to wait for screenshots and other things until then anyways -- I plan to release it probably next weekend or sometime soon after.

Theres a lot to test and technically this is still in a development branch for now. The implementation for webdav in 1.3.0 has been slightly altered to support the filebrowser quantum access rules and user permissions, there may be other small differences too.

If you haven't already, do some of your testing on the dev/v1.3.0 branch just to make sure nothing is too different.

[gtsteffaniak]

I would like to remove these from the "integrations" section and instead be a guide on "user guides"

[gtsteffaniak]

this is the only hangup here

[gtsteffaniak]

actually thinking about it, in general webDAV can be considered an integration since theres api code in filebrowser specifically for this -- just like onlyoffice.

So I am fine with a generic webDAV section for the integrations -- but any specific implementation examples like calDAV and radicale should be a user guide.

[gtsteffaniak]

just waiting for v1.3.0 release and a few tweaks here.

[gtsteffaniak]

@cryinkfly I see theres a few comments left here, you want us to pick this up to finish it?

[cryinkfly]

@gtsteffaniak Yes, unfortunately I've been too busy these last few weeks. Among other things, there were lectures and so on... I did mention your project in my presentation on Rootless Podman at the Chemnitz Linux Days last weekend, and many people didn't even know about it until then.

[gtsteffaniak]

ok no worries just let me know when you think its updated to match v1.3.x version