Add mdbook documentation for the sync server

.github/workflows/checks.yml

@@ -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

.github/workflows/publish-docs.yml

@@ -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

README.md

@@ -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.,
 

docs/.gitignore

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

docs/README.md

@@ -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.

docs/book.toml

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

docs/src/SUMMARY.md

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

docs/src/integration.md

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

docs/src/introduction.md

@@ -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)).

docs/src/usage.md

@@ -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.
+