Adding a Replica

To add a new replica, configure a new, empty replica identically to the existing replica, and run `task sync`.

When to Synchronize

For synchronization to a server, a common solution is to run

    $ task sync

periodically, such as via cron(8).

Sync Server

To synchronize your tasks to a sync server, you will need the following information from the server administrator:

- The server's URL (such as "https://tw.example.com/path")
- A client ID ("client_id") identifying your tasks

Configure Taskwarrior with these details:

    $ task config sync.server.url               <url>
    $ task config sync.server.client_id         <client_id>

Note that the URL must include the scheme, such as 'http://' or 'https://'.

$ task config sync.server.origin <origin>

Is a deprecated synonym for "sync.server.url".

Google Cloud Platform

To synchronize your tasks to GCP, use the GCP Console to create a new project, and within that project a new Cloud Storage bucket. The default settings for the bucket are adequate.

Authenticate to the project with:

    $ gcloud config set project $PROJECT_NAME
    $ gcloud auth application-default login

Then configure Taskwarrior with:

    $ task config sync.gcp.bucket               <bucket-name>

However you can bring your own service account credentials if your `application-default` is already being used by some other application

To begin, navigate to the "IAM and Admin" section in the Navigation Menu, then select "Roles."

On the top menu bar within the "Roles" section, click "CREATE ROLE." Provide an appropriate name and description for the new role.

Add permissions to your new role using the filter "Service:storage" (not the "Filter permissions by role" input box). Select the following permissions:

- storage.buckets.create
- storage.buckets.get
- storage.buckets.update
- storage.objects.create
- storage.objects.delete
- storage.objects.get
- storage.objects.list
- storage.objects.update

Create your new role.

On the left sidebar, navigate to "Service accounts."

On the top menu bar within the "Service accounts" section, click "CREATE SERVICE ACCOUNT." Provide an appropriate name and description for the new service account. Select the role you just created and complete the service account creation process.

Now, in the Service Account dashboard, click into the new service account and select "keys" on the top menu bar. Click on "ADD KEY" to create and download a new key (a JSON key).

Then configure Taskwarrior with:

    $ task config sync.gcp.bucket               <bucket-name>
    $ task config sync.gcp.credential_path      <absolute-path-to-downloaded-credentials>

Amazon Web Services

To synchronize your tasks to AWS, select a region near you and use the AWS console to create a new S3 bucket. The default settings for the bucket are adequate.

You will also need an AWS IAM user with the following policy, where BUCKETNAME is the name of the bucket. The same user can be configured for multiple Taskwarrior clients.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "TaskChampion",
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:ListBucket",
                    "s3:DeleteObject"
                ],
                "Resource": [
                    "arn:aws:s3:::BUCKETNAME",
                    "arn:aws:s3:::BUCKETNAME/*"
                ]
            }
        ]
    }

To create such a user, create a new policy in the IAM console, select the JSON option in the policy editor, and paste the policy. Click "Next" and give the policy a name such as "TaskwarriorSync". Next, create a new user, with a name of your choosing, select "Attach Policies Directly", and then choose the newly-created policy.

You will need access keys configured for the new user. Find the user in the user list, open the "Security Credentials" tab, then click "Create access key" and follow the steps.

At this point, you can choose how to provide those credentials to Taskwarrior. The simplest is to include them in the Taskwarrior configuration:

    $ task config sync.aws.region              <region>
    $ task config sync.aws.bucket              <bucket-name>
    $ task config sync.aws.access_key_id       <access-key-id>
    $ task config sync.aws.secret_access_key   <secret-access-key>

Alternatively, you can set up an AWS CLI profile, using a profile name of your choosing such as "taskwarrior-creds":

    $ aws configure --profile taskwarrior-creds

Enter the access key ID and secret access key. The default region and format are not important. Then configure Taskwarrior with:

    $ task config sync.aws.region              <region>
    $ task config sync.aws.bucket              <bucket-name>
    $ task config sync.aws.profile             taskwarrior-creds

To use AWS's default credential sources, such as environment variables, the default profile, or an instance profile, set

    $ task config sync.aws.region              <region>
    $ task config sync.aws.bucket              <bucket-name>
    $ task config sync.aws.default_credentials true

Local Synchronization

In order to take advantage of synchronization's side effect of saving disk space without setting up a remote server, it is possible to sync tasks locally. To configure local sync:

    $ task config sync.local.server_dir /path/to/sync

The default configuration is to sync to a database in the task directory ("data.location").

Adding a New User

To add a new user to the server, invent a new client ID with a tool like `uuidgen` or an online UUID generator. There is no need to configure the server for this new client ID: the sync server will automatically create a new user whenever presented with a new client ID. Supply the ID, along with the URL, to the user for inclusion in their Taskwarrior config. The user should invent their own "encryption_secret".