A Personal Task Server

This article will explain how to set up and sync with your own task server.

Why Do I Need A Task Server?

You may want to sync tasks between several machines, or you might anticipate doing that. You may also want to have a backup copy of your tasks.

Why Do I Need A Personal Task Server?

Setting up your own Task Server means having complete control and privacy.  There will be secure hosted server accounts soon, but for now you will need to set up your own server.

First Things First

This is new territory for Taskwarrior, which means using beta software, and that means we’re going to make a backup as step 1. Here is a very easy way to backup your data:

$ cd ~/.task
$ tar czf task-backup-$(date +'%Y%m%d').tar.gz *

Now put that file somewhere for safe keeping, because beta software contains bugs. The truth is that all software contains bugs, so if you aren’t making a backup of all your data, then, well, why not?

Satisfy the Dependencies

Before building the software, you will need to satisfy the dependencies by installing the following:

• GnuTLS
• libuuid
• libreadline
• cmake
• make
• A C++ Compiler

Note that some OSes (Darwin, FreeBSD …) include libuuid functionality in libc.

Build the Code

The next step is to obtain the code and build it. This means getting the Taskwarrior 2.3.0 and Task Server 1.0.0 beta2 tarballs. Here are the steps, and notice that the code is built in the home directory. Naturally you can build the code anywhere you wish, but the later in this article we will be referring to this location. Adjust accordingly.

$ cd
$ curl -O http://taskwarrior.org/download/taskd-1.0.0.beta2.tar.gz
$ tar xzf taskd-1.0.0.beta2.tar.gz
$ cd taskd-1.0.0.beta2
$ cmake .
$ make
$ sudo make install
$ cd
$ curl -O http://taskwarrior.org/download/task-2.3.0.beta2.tar.gz
$ tar xzf task-2.3.0.beta2.tar.gz
$ cd task-2.3.0.beta2
$ cmake .
$ make
$ sudo make install

Note that you may choose to run the server on one machine, and the client on another. Bear this in mind as you obtain and build the code.

Server Setup

On the server machine, a location for the data must be chosen and created. The TASKDDATA environment variable will be used to indicate that location, and is also used by the server itself. In fact, most server commands require either that the TASKDDATA variable is set, or the “–data …” option is fully specified. In this example, we are using ~/server_data.

$ export TASKDDATA=~/server_data
$ mkdir -p $TASKDDATA

Everything the server does will be confined to that directory. Now we let the server initialize that directory:

$ taskd init
You must specify the 'server' variable, for example:
taskd config server localhost:53589
Created ~/server_data/config

Next we create an organization (‘Public’) and a user (‘Your Name’ is used here). Substitute your name in the following commands:

$ taskd add org Public
Created organization 'Public'
$ taskd add user 'Public' 'Your Name'
New user key: cf31f287-ee9e-43a8-843e-e8bbd5de4294
Created user 'Your Name' for organization 'Public'

The organization is a grouping of users, and will become essential in later server releases.

Note that you will get a different ‘New user key’, than shown here, and you will need to retain that, to be used later. Note that the key is just a unique id, because your name alone is not necessarily unique.

Now we create certificates and keys. The command below will generate all the certs and keys for the server, but this includes self-signed certificates, and this is not recommended for production use. This is for personal use, and this may be acceptable for you, but if not, you will need to purchase a proper certificate and key, backed by a proper certificate authority.

$ cd ~/taskd-1.0.0.beta2/pki
$ ./generate
...

$ cp client.cert.pem $TASKDDATA
$ cp client.key.pem $TASKDDATA
$ cp server.cert.pem $TASKDDATA
$ cp server.key.pem $TASKDDATA
$ cp server.crl.pem $TASKDDATA
$ cp ca.cert.pem $TASKDDATA

$ taskd config --force client.cert $ROOT/client.cert.pem
$ taskd config --force client.key $ROOT/client.key.pem
$ taskd config --force server.cert $ROOT/server.cert.pem
$ taskd config --force server.key $ROOT/server.key.pem
$ taskd config --force server.crl $ROOT/server.crl.pem
$ taskd config --force ca.cert $ROOT/ca.cert.pem

Now we configure some basic details for the server. The chosen port is 53589.   Note that we allow Taskwarrior clients specifically.

$ cd $TASKDDATA/..
$ taskd config --force log $PWD/taskd.log
$ taskd config --force pid.file $PWD/taskd.pid
$ taskd config --force server localhost:53589
$ taskd config --force client.allow '^task [2-9]'

You can look at all the configuration settings:

$ taskd config

It is time now to launch the server:

$ taskdctl start

This command launched the server as a daemon process. Note that you use ‘taskdctl stop’ to terminate the server. This command requires the TASKDDATA variable. Your server is now running, and ready for syncing.

Client Setup

On your client machine it is assumed that you are already using Taskwarrior, and already have local tasks to sync. If this is not the case, setup and add one.  We need to create a cert and key for you, based on the server cert:

$ cd ~/taskd-1.0.0.beta2/pki
$ ./generate.client your_name
...

Copy the cert, key and ca to your ~/.task directory. The reason we are copying the CA cert is because this is a self-signed cert, and we need the CA to validate against. Alternately we could force Taskwarrior to trust all certs, but that is not recommended.

$ cp your_name.cert.pem ~/.task
$ cp your_name.key.pem ~/.task
$ cp ca.cert.pem ~/.task

Now we need to configure Taskwarrior to be aware of these certs:

$ task config taskd.certificate ~/.task/your_name.cert.pem
$ task config taskd.key ~/.task/your_name.key.pem
$ task config taskd.ca ~/.task/ca.cert.pem

Now set the server info and provide the credentials, which include the ID key generated when the user was added to the server:

$ task config taskd.server localhost:53589
$ task config taskd.credentials 'Public/Your Name/cf31f287-ee9e-43a8-843e-e8bbd5de4294'

Now your client is ready to sync.

First Time Sync

The first time you sync is special – the client sends all your pending tasks to the server. This is something you should only do once. Run this:

$ task sync init
Please confirm that you wish to upload all your pending tasks to the Task Server (yes/no) yes
Syncing with localhost:53589
Sync successful. 2 changes uploaded.

You should get an indication that tasks were uploaded, in this case 2 of them.

General Sync

After the first time sync, you switch and just use this command:

$ task sync
Syncing with localhost:53589
Sync successful. No changes.

This will give you feedback about what happened. Please note that it is perfectly safe to run this command as often as you wish. Syncing is safe and does not consume great system resources.

But it does require network connectivity, and if there is no connectivity you will be notified. It is not a problem if a sync fails because of this, because the next sync that works will catch up with all the changes, and do the right merging.

The general usage pattern is that after you modify data locally, Taskwarrior will start notifying you that you need to sync, after commands, like this:

$ task project:foo list
No matches.
There are local changes. Sync required.

This is just a reminder to sync. Respond with a sync, and the reminder goes away:

$ task sync
Syncing with <server>:<port>
Sync successful. 1 changes uploaded.

Please remember this is beta software, and if you find bugs or have unanswered questions, please contact us at support@taskwarrior.org.

For the latest version of this document, with corrections and added info see: http://taskwarrior.org/projects/taskwarrior/wiki/Server_setup

The Multiple Client Challenge

There is an issue that we need to very careful about.  We need to make sure different task server clients don’t corrupt data through the selective implementation of features.

Each client of the task server will implement different functionality.  Even if feature parity is attempted, one will likely be released ahead of the other, so essentially there will always be the possibility of different functionality between clients.

But the data is shared.  That’s the tricky part.  Fortunately this can be solved with a rule.  The rule is this:

A client MUST preserve intact all unrecognized task attributes, for all I/O operations.

That’s a fairly simple rule, but one that is essential to make different clients work together.  Let’s look at an example.

Suppose there is a client that doesn’t support tags.  By not supporting tags, it would not show tags, or allow them to be added, removed, or modified.  But as a client to the task server, tags are sure to be found in the data.  By obeying the rule, any task that does have tags will not lose those tags when handled by the client.

To look at this at a lower level, the format of the tasks to/from the server is JSON, and the rule says that the JSON structure and contents must be preserved, and only recognized constructs may be manipulated.

This may sound restrictive, but is in fact very permissive.  It allows for clients that are incredibly simple.  An example of this might be a Top Ten task app that only supports a completion action on the ten most urgent tasks, and furthermore only displays the descriptions.  Such a simple app, by obeying the rule, and implementing only one feature, remains compliant, and does not harm user data, even though it doesn’t understand all the data.

This opens the door for lightweight clients.  Small apps that might simply capture new tasks, or an app that just spell-checks task descriptions.  Not every client of the task server needs a UI…