diff --git a/README.md b/README.md index 39aca23..3be02cd 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,52 @@ It is comprised of three crates: ## 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 + +The [`docker-compose.yml`](./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, clone this repository (or just download `docker-compose.yml` to +the current directory -- the rest of the contents of this repository are not +required) and run + +```sh +TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com docker compose up +``` + +It can take a few minutes to obtain the certificate; the caddy container will +log a msg "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 `--data-dir` option specifies where the server should store its data, and -`--port` gives the port on which the HTTP server runs. The server does not -implement TLS; for public deployments, the recommendation is to use a reverse -proxy such as Nginx, haproxy, or Apache httpd. +`--port` gives the port on which the HTTP server runs. By default, the server allows all client IDs. To limit the accepted client IDs, such as when running a personal server, use `--allow-client-id `. @@ -36,52 +75,9 @@ 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. -## Installation +## Building -### As container - -To build the container execute the following commands. -```sh -source .env -docker build \ - --build-arg RUST_VERSION=${RUST_VERSION} \ - --build-arg ALPINE_VERSION=${ALPINE_VERSION} \ - -t taskchampion-sync-server . -``` - -Now to run it, simply exec. -```sh -docker run -t -d \ - --name=taskchampion \ - -p 8080:8080 \ - taskchampion-sync-server -``` - -This start TaskChampion Sync-Server and publish the port to host. Please -note that this is a basic run, all data will be destroyed after stop and -delete container. - -#### Persist data using a container volume - -TaskChampion Sync-Server container image uses a volume -`/var/lib/taskchampion-sync-server` to store database. You can exec the -following to mount it in your host as persistent storage. -```sh -docker run -t -d \ - --name=taskchampion \ - -p 8080:8080 \ - -v /my/taskchampion-sync-server:/var/lib/taskchampion-sync-server \ - taskchampion-sync-server -``` - -Take note that you must create before the directory -`/my/taskchampion-sync-server` and set ownership to UID/GID 100. -```sh -mkdir -p /my/taskchampion-sync-server -chown -R 100:100 /my/taskchampion-sync-server -``` - -### From source +### Building From Source #### Installing Rust @@ -112,3 +108,25 @@ cargo build --release After build the binary is located in `target/release/taskchampion-sync-server`. +### Building the Container + +To build the container execute the following commands. +```sh +source .env +docker build \ + --build-arg RUST_VERSION=${RUST_VERSION} \ + --build-arg ALPINE_VERSION=${ALPINE_VERSION} \ + -t taskchampion-sync-server . +``` + +Now to run it, simply exec. +```sh +docker run -t -d \ + --name=taskchampion \ + -p 8080:8080 \ + taskchampion-sync-server +``` + +This start TaskChampion Sync-Server and publish the port to host. Please +note that this is a basic run, all data will be destroyed after stop and +delete container. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..7d6255d --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,64 @@ +volumes: + data: + +services: + # Make the necessary subdirectories of the `data` volume, and set ownership of the + # `tss/taskchampion-sync-server` directory, as the server runs as user 100. + mkdir: + image: caddy:2-alpine + command: | + /bin/sh -c " + mkdir -p /data/caddy/data /data/caddy/config /data/tss/taskchampion-sync-server && + chown -R 100:100 /data/tss/taskchampion-sync-server + " + volumes: + - type: volume + source: data + target: /data + read_only: false + volume: + nocopy: true + + caddy: + image: caddy:2-alpine + restart: unless-stopped + ports: + - "80:80" + - "443:443" + volumes: + - type: volume + source: data + target: /data + read_only: false + volume: + nocopy: true + subpath: caddy/data + - type: volume + source: data + target: /config + read_only: false + volume: + nocopy: true + subpath: caddy/config + command: caddy reverse-proxy --from https://${TASKCHAMPION_SYNC_SERVER_HOSTNAME} --to http://tss:8080 + depends_on: + mkdir: + condition: service_completed_successfully + + tss: + image: ghcr.io/gothenburgbitfactory/taskchampion-sync-server:main + restart: unless-stopped + volumes: + - type: volume + source: data + target: /tss + read_only: false + volume: + nocopy: true + subpath: tss + command: --data-dir /tss/taskchampion-sync-server --port 8080 + environment: + - RUST_LOG=info + depends_on: + mkdir: + condition: service_completed_successfully