GothenburgBitFactory/taskchampion-sync-server
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskchampion-sync-server.git synced 2025-08-01 20:20:25 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add mdbook documentation for the sync server

Browse source
This commit is contained in:
Dustin J. Mitchell 2025-07-13 17:17:48 -04:00
parent c539e604d9
commit 60436a5524
No known key found for this signature in database
10 changed files with 178 additions and 94 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.github/workflows/checks.yml vendored
View file

@ -107,3 +107,19 @@ jobs:
with:
# exclude the binary package from semver checks, since it is not published as a crate.
exclude: taskchampion-sync-server
mdbook:
runs-on: ubuntu-latest
name: "mdBook Documentation"
steps:
- uses: actions/checkout@v4
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v2
with:
# if this changes, change it in .github/workflows/publish-docs.yml as well
mdbook-version: '0.4.48'
- run: mdbook test docs
- run: mdbook build docs

30
.github/workflows/publish-docs.yml vendored Normal file
View file

@ -0,0 +1,30 @@
name: docs
on:
push:
branches:
- main
permissions:
contents: write
jobs:
mdbook-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v2
with:
# if this changes, change it in .github/workflows/checks.yml as well
mdbook-version: '0.4.48'
- run: mdbook build docs
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/book

106
README.md
View file

@ -9,103 +9,20 @@ and other applications embedding TaskChampion can sync.
## Status
This repository was spun off from Taskwarrior itself after the 3.0.0
release. It is still under development and currently best described as
a reference implementation of the Taskchampion sync protocol.
This project provides both pre-built images for common use-cases and Rust
libraries that can be used to build more sophisticated applications. See [the documentation][documentation]
for more on how to use this project.
It is comprised of three crates:
[documentation]: https://gothenburgbitfactory.org/taskchampion-sync-server
## Repository Guide
The repository is comprised of three crates:
- `taskchampion-sync-server-core` implements the core of the protocol
- `taskchmpaion-sync-server-sqlite` implements an SQLite backend for the core
- `taskchampion-sync-server` implements a simple HTTP server for the protocol
## Running the Server
The server is a simple binary that serves HTTP requests on a TCP port. The
server does not implement TLS; for public deployments, the recommendation is to
use a reverse proxy such as Nginx, haproxy, or Apache httpd.
### Using Docker-Compose
Every release of the server generates a Docker image in
`ghcr.io/gothenburgbitfactory/taskchampion-sync-server`. The tags include
`latest` for the latest release, and both minor and patch versions, e.g., `0.5`
and `0.5.1`.
The
[`docker-compose.yml`](https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml)
file in this repository is sufficient to run taskchampion-sync-server,
including setting up TLS certificates using Lets Encrypt, thanks to
[Caddy](https://caddyserver.com/).
You will need a server with ports 80 and 443 open to the Internet and with a
fixed, publicly-resolvable hostname. These ports must be available both to your
Taskwarrior clients and to the Lets Encrypt servers.
On that server, download `docker-compose.yml` from the link above (it is pinned
to the latest release) into the current directory. Then run
```sh
TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
docker compose up
```
The `TASKCHAMPION_SYNC_SERVER_CLIENT_ID` limits the server to the given client
ID; omit it to allow all client IDs.
It can take a few minutes to obtain the certificate; the caddy container will
log a message "certificate obtained successfully" when this is complete, or
error messages if the process fails. Once this process is complete, configure
your `.taskrc`'s to point to the server:
```
sync.server.url=https://taskwarrior.example.com
sync.server.client_id=your-client-id
sync.encryption_secret=your-encryption-secret
```
The docker-compose images store data in a docker volume named
`taskchampion-sync-server_data`. This volume contains all of the task data, as
well as the TLS certificate information. It will persist over restarts, in a
typical Docker installation. The docker containers will start automatically on
system startup. See the docker-compose documentation for more information.
### Running the Binary
The server is configured with command-line options. See
`taskchampion-sync-server --help` for full details.
The `--listen` option specifies the interface and port the server listens on.
It must contain an IP-Address or a DNS name and a port number. This option is
mandatory, but can be repeated to specify multiple interfaces or ports. This
value can be specified in environment variable `LISTEN`, as a comma-separated
list of values.
The `--data-dir` option specifies where the server should store its data. This
value can be specified in the environment variable `DATA_DIR`.
By default, the server will allow all clients and create them in the database
on first contact. There are two ways to limit the clients the server will
interact with:
- To limit the accepted client IDs, specify them in the environment variable
`CLIENT_ID`, as a comma-separated list of UUIDs. Client IDs can be specified
with `--allow-client-id`, but this should not be used on shared systems, as
command line arguments are visible to all users on the system. This convenient
option is suitable for personal and small-scale deployments.
- To disable the automatic creation of clients, use the `--no-create-clients`
flag or the `CREATE_CLIENTS=false` environment variable. You are now
responsible for creating clients in the database manually, so this option is
more suitable for large scale deployments.
The server only logs errors by default. To add additional logging output, set
environment variable `RUST_LOG` to `info` to get a log message for every
request, or to `debug` to get more verbose debugging output.
## Building
### Building From Source
#### Installing Rust
@ -129,7 +46,7 @@ rustup override set stable
[rustup]: https://rustup.rs/
#### Installing TaskChampion Sync-Server
#### Building TaskChampion Sync-Server
To build TaskChampion Sync-Server binary simply execute the following
commands.
@ -144,7 +61,8 @@ After build the binary is located in
### Building the Container
To build the container execute the following commands.
To build the container, execute the following commands.
```sh
source .env
docker build \
@ -161,7 +79,7 @@ docker run -t -d \
taskchampion-sync-server
```
This start TaskChampion Sync-Server and publish the port to host. Please
This starts TaskChampion Sync-Server and publishes port 8080 to the host. Please
note that this is a basic run, all data will be destroyed after stop and
delete container. You may also set `DATA_DIR`, `CLIENT_ID`, or `LISTEN` with `-e`, e.g.,

2
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
book
tmp

3
docs/README.md Normal file
View file

@ -0,0 +1,3 @@
This is an [mdbook](https://rust-lang.github.io/mdBook/index.html) book.
Minor modifications can be made without installing the mdbook tool, as the content is simple Markdown.
Changes are verified on pull requests.

9
docs/book.toml Normal file
View file

@ -0,0 +1,9 @@
[book]
authors = ["Dustin J. Mitchell"]
language = "en"
multilingual = false
src = "src"
title = "TaskChampion Sync Server"
[output.html]
default-theme = "ayu"

5
docs/src/SUMMARY.md Normal file
View file

@ -0,0 +1,5 @@
# Summary
- [Introduction](./introduction.md)
- [Usage](./usage.md)
- [Integration](./integration.md)

3
docs/src/integration.md Normal file
View file

@ -0,0 +1,3 @@
# Integration
TBD (pending Postgres support)

11
docs/src/introduction.md Normal file
View file

@ -0,0 +1,11 @@
# Introduction
Taskchampion Sync-Server is an implementation of the TaskChampion [sync
protocol][sync-protocol] server. It supports synchronizing Taskwarrior tasks
between multiple systems.
[sync-protocol]: https://gothenburgbitfactory.org/taskchampion/sync.html
The project provides both pre-built images for common use-cases (see
[usage](./usage.md)) and Rust libraries that can be used to build more
sophisticated applications ([integration](./integration.md)).

87
docs/src/usage.md Normal file
View file

@ -0,0 +1,87 @@
# Usage
## Running the Server
The server is a simple binary that serves HTTP requests on a TCP port. The
server does not implement TLS; for public deployments, the recommendation is to
use a reverse proxy such as Nginx, haproxy, or Apache httpd.
### Using Docker-Compose
Every release of the server generates a Docker image in
`ghcr.io/gothenburgbitfactory/taskchampion-sync-server`. The tags include
`latest` for the latest release, and both minor and patch versions, e.g., `0.5`
and `0.5.1`.
The
[`docker-compose.yml`](https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml)
file in this repository is sufficient to run taskchampion-sync-server,
including setting up TLS certificates using Lets Encrypt, thanks to
[Caddy](https://caddyserver.com/).
You will need a server with ports 80 and 443 open to the Internet and with a
fixed, publicly-resolvable hostname. These ports must be available both to your
Taskwarrior clients and to the Lets Encrypt servers.
On that server, download `docker-compose.yml` from the link above (it is pinned
to the latest release) into the current directory. Then run
```sh
TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
docker compose up
```
The `TASKCHAMPION_SYNC_SERVER_CLIENT_ID` limits the server to the given client
ID; omit it to allow all client IDs.
It can take a few minutes to obtain the certificate; the caddy container will
log a message "certificate obtained successfully" when this is complete, or
error messages if the process fails. Once this process is complete, configure
your `.taskrc`'s to point to the server:
```none
sync.server.url=https://taskwarrior.example.com
sync.server.client_id=your-client-id
sync.encryption_secret=your-encryption-secret
```
The docker-compose images store data in a docker volume named
`taskchampion-sync-server_data`. This volume contains all of the task data, as
well as the TLS certificate information. It will persist over restarts, in a
typical Docker installation. The docker containers will start automatically on
system startup. See the docker-compose documentation for more information.
### Running the Binary
The server is configured with command-line options. See
`taskchampion-sync-server --help` for full details.
The `--listen` option specifies the interface and port the server listens on.
It must contain an IP-Address or a DNS name and a port number. This option is
mandatory, but can be repeated to specify multiple interfaces or ports. This
value can be specified in environment variable `LISTEN`, as a comma-separated
list of values.
The `--data-dir` option specifies where the server should store its data. This
value can be specified in the environment variable `DATA_DIR`.
By default, the server will allow all clients and create them in the database
on first contact. There are two ways to limit the clients the server will
interact with:
- To limit the accepted client IDs, specify them in the environment variable
`CLIENT_ID`, as a comma-separated list of UUIDs. Client IDs can be specified
with `--allow-client-id`, but this should not be used on shared systems, as
command line arguments are visible to all users on the system. This convenient
option is suitable for personal and small-scale deployments.
- To disable the automatic creation of clients, use the `--no-create-clients`
flag or the `CREATE_CLIENTS=false` environment variable. You are now
responsible for creating clients in the database manually, so this option is
more suitable for large scale deployments.
The server only logs errors by default. To add additional logging output, set
environment variable `RUST_LOG` to `info` to get a log message for every
request, or to `debug` to get more verbose debugging output.