This paragraph reminds the absolute basics. If the CalDAV and CardDAV protocol already are something you heard of, you can jump to the next title

The choice of describing how to setup servers for calendars, todolists and contacts all at once may seem rather odd, and maybe you are wondering why I’m doing one post instead of three. The reason is simple: all of these services are actually (almost) one and the same. Let me explain.

First, a todolist is just a special calendar. You have some different fields, such as priority, and the dates of events are not mandatory, but basically it’s the same thing. So todolists and calendars are actually the same thing, stored in ics files, the iCalendar format.

For the contacts things are a little different (hence the precautionnary almost above). Contacts are stored using the vCard format, in vcf files. The vCard format, as the iCalendar format, is a textual format and both look very much alike. But what truly put them together is the protocol used to sync them with a remote server. Contacts are synced using CardDAV, calendars and todolists are synced using CalDAV. Both protocols are extensions of the WebDAV protocol, itself an extension of the HTTP protocol.

Consequently, servers generally choose to implement both protocols and therefore act as CalDAV and CardDAV servers. Which means you can install and configure just one server and have calendars, contacts and todolists synchronized. Cool, huh?

For ease of installation, deinstallation, update and concistency, I insist that all my self-hosted services run inside Docker containers, and this one will be no exception. If you don’t know about Docker yet, I encourage you to check out their website and read through the tutorial pages. For the rest of this post, I will assume you know at least what Docker is and how it runs.

There are a lot of different CalDAV/CardDAV projects ouit there. After browsing them for a while ¹, I settled on Radicale. The features are basically the same than the other projects. What decided me was :

Anyway, the website is here, if you want to take a look.

I said that there was an official Dockerfile, but there are no official Docker repository on te Docker hub². So the first thing we need to do is build it ourselves:

You should of course replace lertsenem with whatever your own Docker login is.

After the docker image is built, you can run it using the following command:

Radicale uses the port 5232 by default, we will need to change that later. The interesting directory of the docker image is /data/config, which holds the server configuration. We mapped it here to /tmp/radicaledata on our host system, now we are going to fill it.

The git repo contains a default example configuration for Radicale, which we can use as a starting point. Here is my final config file.

First, one important note: I leave the ssl setting to False, but that’s because I’m using an http proxy that manage all the SSL encryption.

Also note that the default protocole suit is PROTOCOL_SSLv23, which is good for interoperability, but not so much for security. Unless you are using an oudated web browser³ you will be better using PROTOCOL_TLSv1.2.

In the [auth] section, you will then need to specify the authentication method you intend to use for you users. If you are very tech savvy and love playing sysadmin on your free time, maybe you already have an LDAP server that you can use for authentication. If you want to use the unix accounts of your machine, use the PAM setting⁴. But if you are someone simple and direct, you can use the htpasswd setting. You can then add a htpasswd_filename and a htpasswd_encryption⁵, and all you are needing is a htpasswd file with some users in it. You can create one thusly:

Finally, you have to give rights upon different collections to your users. Some easy settings for that are type = owner_only or owner_write. They both give users full permissions on directories matching their logins, and the second one also gives read permissions to every authenticated users on every directory. The authenticated setting is easier even, giving full permissions on every collection to every user authenticated. But that does not satisfy us, we want security and privacy, with shared collections, and we are going to achieve that using type = from_file.

Of course we now need to create a rights file.

Here is mine.

The rights file is simple to understand. Each section of the file is a rule, and you can give it any name you want. Then for each rule, you have to specify:

Every permission that is not exmplicitly autorized is forbidden.

The syntax uses regular exressions and some specific symbols. Here for example, the first rule [owner-write] specifies that any user with a login matching . (which means more than one character: no anonymous) has full rw permissions on collections matching their login. You could guess it with the name, that’s a reimplementation of the +owner-write setting we saw earlier.

The [shared] rule is more complex and specifies that any authenticated user⁶ has full read and write permissions on collections starting with shared and containing their login (separated by dashes). This allows both my users my@email.com and anotheruser to access and modify the collections under shared-my@email.com-anotheruser/*.

And with that our server is configured. Let’s create some empty collections.

And now our server is working.

We have the server, now we will need clients. I will start with the client I’m going to use the most: the one on my smartphone.

The Radicale website propose several alternatives for android clients. I picked DavDroid, because why not. The icon seems clean enough that someone put some effort in the app, the updates seem regulat, and it’s available on F-Droid.

The configuration of DavDroid is very straightforward, but the apps is not exempt of problems. For example, you have to delete an account to register new calendars/todolists. Yep, that sucks. Also, you cannot create new calendars/todolists from the app. Sorry.

Keep in mind that if the application does not seem to detect your collections, it’s almost certainly a permissions problem on your collections, on the Radicale side. Go check the Radicale logs.

Once DavDroid is correctly configured, you should have access to your calendars and contacts through the regular Android applications. Remember to spend some time in the settings of your account in the DavDroid application, especially to check the synchronization delays. By default DavDroid syncs contacts, calendars and tasks once every day and on each local modification. I found that not to be enough for the tasks and calendars I share with my girlfriend, so I set it to sync more often (every hour for the calendars and every 15 minutes for the tasks lists).

Now, a smartphone is the main device I’m using to manage my agenda and contacts, but I still want to have a valid alternative for my desktop computer. Oh, and I want it with a command line interface too, because, you know, command line is fun.

Searching through the web for an application that would suit my needs, I stumble upon khal and vdirsyncer, which are so similar in principle to my alot/offlineimap setup that I immediately adopted them.

vdirsyncer will play the part of offlineimap, syncing my remote collections (contacts and calendars/todolists) to a local folder. Here is the configuration I use (description follows):

As you can see, the configuration file is very similar to the offlineimap one.

First, in the [general] section you will find global settings. Here the status_path indicates where vdirsyncer should put its database.

For each connection, you will then have a [pair xxx] section describing the syncing of your remote and local calendars or contacts (and how to solve conflicts). You need to define two matching [storage xxx] sections to describe how to access your local and remote collections. As you can see, I chose to put my local collections under _/Contacts/ and /Calendars/.

Also, note for the remote parts the verify=false and verify_fingerprint settings. They are here because I was too lazy to generate a real certificate and instead reused an old one, meant for another domain name. Thus vdirsyncer cannot really verify it (verify=false) and instead verifies its fingerprint. Of course this is not ideal and only meant as a temporary fix⁷.

On the remote side, you also need to specify a username and a password. You can pass them directly in the config file, using the username and password settings, but that would be leaving your credentials in clear text on your disk, which is unsafe (especially if you are not the only user of your computer). Instead, you can use the username.fetch and password.fetch to specify a command line that will get the credentials, and put them in a dedicated keyring app. Here I’m using a python script I got (and improved) from the Archlinux website to get my credentials from the gnome keyring, which is included with Ubuntu⁸.

Once your configuration is done, use vdirsyncer discover to initialise your base. Until your collections change, you will then just need to run vdirsyncer sync to synchronize your pairs.

While vdirsyncer was an offlineimap-like, khal is an alot-like. It’s a command-line frontend to navigate the local Calendars folder. It’s written in Python and packaged for pypi, so you can install it easily. Just remember to use pip3 to get the up-to-date python3 version.

The configuration is pretty simple, you just need to indicate the location of your synced Calendars on your disk. Optionally you may specify colors to prettify your interface, and that’s about it.

You can use khal as a simple command line tool: typing khal in console will print a view of the current month, with colors marking days with events and a summary of the events of the present day. You can also start khal interactive and navigate throiugh each day, viewing, editing, adding and removing events with vi-like controls. Of course, you will need to vdirsyncer sync once you are done to synchronize your local modifications with your remote server.

Finally I was looking for a frontend like khal to read and write my todo lists. I found it with todoman.

Like khal, todoman is a Python app, and you can install it using pip3. Like khal, the configuration is very easy (you have your content saved locally after all): just point the path toward the directory containing your collections and you are done.

todoman is easy to use. Here are the basics: use todo to get a list of all your tasks. You can refine this using todo list MyList. Once a todo command has printed out some numbered tasks, you can act on them base on their number. Thus todo done 3 will check the third task you last printed with a todo or todo list command. There’s more features available, but for a basic usage you are all set. Use todo --help for more pointers. :)

I’m pretty satisfied with my setup. Both the configuration and daily usage are very similar to my mail setup, which makes it easier to use. My calendars and contacts (and todolists, but that’s just a type of calendar) are now saved on my personnal server. I’ll wait to have a backup solution before I completely migrate my data though. :]

I didn’t speak about it in the article, but there’s a setting in the client mail alot to use contact completion. I wrote a short⁹ shell script to parse the VCF files in my local ~/Contacts/ directory:

Now I can add the following section to my alot configuration:

And boom: when writing a mail I can autocomplete the recipients fields using <Tab>.

That’s it for today, next time I will probably talk about a nice solution of backup, or about how to reinstall you server from scratch quickly after a fatal crash. :]

As always for comments, suggestions or insults, please use my twitter account.