Skip to content

Commit 48b3aeb

Browse files
djmitchedjmitche
authored
Merge pull request #131 from djmitche/issue124
Add mdbook documentation for the sync server
2 parents c539e60 + 60436a5 commit 48b3aeb

File tree

10 files changed

+178
-94
lines changed

10 files changed

+178
-94
lines changed

‎.github/workflows/checks.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,3 +107,19 @@ jobs:
107107
with:
108108
# exclude the binary package from semver checks, since it is not published as a crate.
109109
exclude: taskchampion-sync-server
110+
111+
mdbook:
112+
runs-on: ubuntu-latest
113+
name: "mdBook Documentation"
114+
115+
steps:
116+
- uses: actions/checkout@v4
117+
118+
- name: Setup mdBook
119+
uses: peaceiris/actions-mdbook@v2
120+
with:
121+
# if this changes, change it in .github/workflows/publish-docs.yml as well
122+
mdbook-version: '0.4.48'
123+
124+
- run: mdbook test docs
125+
- run: mdbook build docs

‎.github/workflows/publish-docs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
mdbook-deploy:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Setup mdBook
19+
uses: peaceiris/actions-mdbook@v2
20+
with:
21+
# if this changes, change it in .github/workflows/checks.yml as well
22+
mdbook-version: '0.4.48'
23+
24+
- run: mdbook build docs
25+
26+
- name: Deploy
27+
uses: peaceiris/actions-gh-pages@v4
28+
with:
29+
github_token: ${{ secrets.GITHUB_TOKEN }}
30+
publish_dir: ./docs/book

‎README.md‎

Lines changed: 12 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -9,103 +9,20 @@ and other applications embedding TaskChampion can sync.
99

1010
## Status
1111

12-
This repository was spun off from Taskwarrior itself after the 3.0.0
13-
release. It is still under development and currently best described as
14-
a reference implementation of the Taskchampion sync protocol.
12+
This project provides both pre-built images for common use-cases and Rust
13+
libraries that can be used to build more sophisticated applications. See [the documentation][documentation]
14+
for more on how to use this project.
1515

16-
It is comprised of three crates:
16+
[documentation]: https://gothenburgbitfactory.org/taskchampion-sync-server
17+
18+
## Repository Guide
19+
20+
The repository is comprised of three crates:
1721

1822
- `taskchampion-sync-server-core` implements the core of the protocol
1923
- `taskchmpaion-sync-server-sqlite` implements an SQLite backend for the core
2024
- `taskchampion-sync-server` implements a simple HTTP server for the protocol
2125

22-
## Running the Server
23-
24-
The server is a simple binary that serves HTTP requests on a TCP port. The
25-
server does not implement TLS; for public deployments, the recommendation is to
26-
use a reverse proxy such as Nginx, haproxy, or Apache httpd.
27-
28-
### Using Docker-Compose
29-
30-
Every release of the server generates a Docker image in
31-
`ghcr.io/gothenburgbitfactory/taskchampion-sync-server`. The tags include
32-
`latest` for the latest release, and both minor and patch versions, e.g., `0.5`
33-
and `0.5.1`.
34-
35-
The
36-
[`docker-compose.yml`](https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml)
37-
file in this repository is sufficient to run taskchampion-sync-server,
38-
including setting up TLS certificates using Lets Encrypt, thanks to
39-
[Caddy](https://caddyserver.com/).
40-
41-
You will need a server with ports 80 and 443 open to the Internet and with a
42-
fixed, publicly-resolvable hostname. These ports must be available both to your
43-
Taskwarrior clients and to the Lets Encrypt servers.
44-
45-
On that server, download `docker-compose.yml` from the link above (it is pinned
46-
to the latest release) into the current directory. Then run
47-
48-
```sh
49-
TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
50-
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
51-
docker compose up
52-
```
53-
54-
The `TASKCHAMPION_SYNC_SERVER_CLIENT_ID` limits the server to the given client
55-
ID; omit it to allow all client IDs.
56-
57-
It can take a few minutes to obtain the certificate; the caddy container will
58-
log a message "certificate obtained successfully" when this is complete, or
59-
error messages if the process fails. Once this process is complete, configure
60-
your `.taskrc`'s to point to the server:
61-
62-
```
63-
sync.server.url=https://taskwarrior.example.com
64-
sync.server.client_id=your-client-id
65-
sync.encryption_secret=your-encryption-secret
66-
```
67-
68-
The docker-compose images store data in a docker volume named
69-
`taskchampion-sync-server_data`. This volume contains all of the task data, as
70-
well as the TLS certificate information. It will persist over restarts, in a
71-
typical Docker installation. The docker containers will start automatically on
72-
system startup. See the docker-compose documentation for more information.
73-
74-
### Running the Binary
75-
76-
The server is configured with command-line options. See
77-
`taskchampion-sync-server --help` for full details.
78-
79-
The `--listen` option specifies the interface and port the server listens on.
80-
It must contain an IP-Address or a DNS name and a port number. This option is
81-
mandatory, but can be repeated to specify multiple interfaces or ports. This
82-
value can be specified in environment variable `LISTEN`, as a comma-separated
83-
list of values.
84-
85-
The `--data-dir` option specifies where the server should store its data. This
86-
value can be specified in the environment variable `DATA_DIR`.
87-
88-
By default, the server will allow all clients and create them in the database
89-
on first contact. There are two ways to limit the clients the server will
90-
interact with:
91-
92-
- To limit the accepted client IDs, specify them in the environment variable
93-
`CLIENT_ID`, as a comma-separated list of UUIDs. Client IDs can be specified
94-
with `--allow-client-id`, but this should not be used on shared systems, as
95-
command line arguments are visible to all users on the system. This convenient
96-
option is suitable for personal and small-scale deployments.
97-
98-
- To disable the automatic creation of clients, use the `--no-create-clients`
99-
flag or the `CREATE_CLIENTS=false` environment variable. You are now
100-
responsible for creating clients in the database manually, so this option is
101-
more suitable for large scale deployments.
102-
103-
The server only logs errors by default. To add additional logging output, set
104-
environment variable `RUST_LOG` to `info` to get a log message for every
105-
request, or to `debug` to get more verbose debugging output.
106-
107-
## Building
108-
10926
### Building From Source
11027

11128
#### Installing Rust
@@ -129,7 +46,7 @@ rustup override set stable
12946

13047
[rustup]: https://rustup.rs/
13148

132-
#### Installing TaskChampion Sync-Server
49+
#### Building TaskChampion Sync-Server
13350

13451
To build TaskChampion Sync-Server binary simply execute the following
13552
commands.
@@ -144,7 +61,8 @@ After build the binary is located in
14461

14562
### Building the Container
14663

147-
To build the container execute the following commands.
64+
To build the container, execute the following commands.
65+
14866
```sh
14967
source .env
15068
docker build \
@@ -161,7 +79,7 @@ docker run -t -d \
16179
taskchampion-sync-server
16280
```
16381

164-
This start TaskChampion Sync-Server and publish the port to host. Please
82+
This starts TaskChampion Sync-Server and publishes port 8080 to the host. Please
16583
note that this is a basic run, all data will be destroyed after stop and
16684
delete container. You may also set `DATA_DIR`, `CLIENT_ID`, or `LISTEN` with `-e`, e.g.,
16785

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
book
2+
tmp

‎docs/README.md‎

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

‎docs/book.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[book]
2+
authors = ["Dustin J. Mitchell"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "TaskChampion Sync Server"
7+
8+
[output.html]
9+
default-theme = "ayu"

‎docs/src/SUMMARY.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Summary
2+
3+
- [Introduction](./introduction.md)
4+
- [Usage](./usage.md)
5+
- [Integration](./integration.md)

‎docs/src/integration.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integration
2+
3+
TBD (pending Postgres support)

‎docs/src/introduction.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Introduction
2+
3+
Taskchampion Sync-Server is an implementation of the TaskChampion [sync
4+
protocol][sync-protocol] server. It supports synchronizing Taskwarrior tasks
5+
between multiple systems.
6+
7+
[sync-protocol]: https://gothenburgbitfactory.org/taskchampion/sync.html
8+
9+
The project provides both pre-built images for common use-cases (see
10+
[usage](./usage.md)) and Rust libraries that can be used to build more
11+
sophisticated applications ([integration](./integration.md)).

‎docs/src/usage.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Usage
2+
3+
## Running the Server
4+
5+
The server is a simple binary that serves HTTP requests on a TCP port. The
6+
server does not implement TLS; for public deployments, the recommendation is to
7+
use a reverse proxy such as Nginx, haproxy, or Apache httpd.
8+
9+
### Using Docker-Compose
10+
11+
Every release of the server generates a Docker image in
12+
`ghcr.io/gothenburgbitfactory/taskchampion-sync-server`. The tags include
13+
`latest` for the latest release, and both minor and patch versions, e.g., `0.5`
14+
and `0.5.1`.
15+
16+
The
17+
[`docker-compose.yml`](https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml)
18+
file in this repository is sufficient to run taskchampion-sync-server,
19+
including setting up TLS certificates using Lets Encrypt, thanks to
20+
[Caddy](https://caddyserver.com/).
21+
22+
You will need a server with ports 80 and 443 open to the Internet and with a
23+
fixed, publicly-resolvable hostname. These ports must be available both to your
24+
Taskwarrior clients and to the Lets Encrypt servers.
25+
26+
On that server, download `docker-compose.yml` from the link above (it is pinned
27+
to the latest release) into the current directory. Then run
28+
29+
```sh
30+
TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
31+
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
32+
docker compose up
33+
```
34+
35+
The `TASKCHAMPION_SYNC_SERVER_CLIENT_ID` limits the server to the given client
36+
ID; omit it to allow all client IDs.
37+
38+
It can take a few minutes to obtain the certificate; the caddy container will
39+
log a message "certificate obtained successfully" when this is complete, or
40+
error messages if the process fails. Once this process is complete, configure
41+
your `.taskrc`'s to point to the server:
42+
43+
```none
44+
sync.server.url=https://taskwarrior.example.com
45+
sync.server.client_id=your-client-id
46+
sync.encryption_secret=your-encryption-secret
47+
```
48+
49+
The docker-compose images store data in a docker volume named
50+
`taskchampion-sync-server_data`. This volume contains all of the task data, as
51+
well as the TLS certificate information. It will persist over restarts, in a
52+
typical Docker installation. The docker containers will start automatically on
53+
system startup. See the docker-compose documentation for more information.
54+
55+
### Running the Binary
56+
57+
The server is configured with command-line options. See
58+
`taskchampion-sync-server --help` for full details.
59+
60+
The `--listen` option specifies the interface and port the server listens on.
61+
It must contain an IP-Address or a DNS name and a port number. This option is
62+
mandatory, but can be repeated to specify multiple interfaces or ports. This
63+
value can be specified in environment variable `LISTEN`, as a comma-separated
64+
list of values.
65+
66+
The `--data-dir` option specifies where the server should store its data. This
67+
value can be specified in the environment variable `DATA_DIR`.
68+
69+
By default, the server will allow all clients and create them in the database
70+
on first contact. There are two ways to limit the clients the server will
71+
interact with:
72+
73+
- To limit the accepted client IDs, specify them in the environment variable
74+
`CLIENT_ID`, as a comma-separated list of UUIDs. Client IDs can be specified
75+
with `--allow-client-id`, but this should not be used on shared systems, as
76+
command line arguments are visible to all users on the system. This convenient
77+
option is suitable for personal and small-scale deployments.
78+
79+
- To disable the automatic creation of clients, use the `--no-create-clients`
80+
flag or the `CREATE_CLIENTS=false` environment variable. You are now
81+
responsible for creating clients in the database manually, so this option is
82+
more suitable for large scale deployments.
83+
84+
The server only logs errors by default. To add additional logging output, set
85+
environment variable `RUST_LOG` to `info` to get a log message for every
86+
request, or to `debug` to get more verbose debugging output.
87+

0 commit comments

Comments
 (0)