diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index b64b59e..22ee9c3 100644 --- a/.github/workflows/checks.yml +++ b/.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 diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..cae3267 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 3af91f0..e13a875 100644 --- a/README.md +++ b/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., diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d2479eb --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +book +tmp diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7aaa35c --- /dev/null +++ b/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. diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..de5220a --- /dev/null +++ b/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" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..0ab6c68 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,5 @@ +# Summary + +- [Introduction](./introduction.md) +- [Usage](./usage.md) +- [Integration](./integration.md) diff --git a/docs/src/integration.md b/docs/src/integration.md new file mode 100644 index 0000000..bd6d642 --- /dev/null +++ b/docs/src/integration.md @@ -0,0 +1,3 @@ +# Integration + +TBD (pending Postgres support) diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 0000000..ed8055c --- /dev/null +++ b/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)). diff --git a/docs/src/usage.md b/docs/src/usage.md new file mode 100644 index 0000000..f5456f1 --- /dev/null +++ b/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. +