Provide a docker-compose.yml that will run a server, with TLS (#68)

This is intended to support the user journey of someone with a VPS who wants to set up the sync server, but does not have the knowledge and skills to set up a reverse proxy and TLS certificate themselves.
GothenburgBitFactory · Dec 15, 2024 · a364791 · a364791
1 parent 26e4e6c
commit a364791
Show file tree

Hide file tree

Showing 2 changed files with 129 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -21,67 +21,63 @@ It is comprised of three crates:
 
 ## Running the Server
 
-The server is configured with command-line options. See
-`taskchampion-sync-server --help` for full details.
+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.
 
-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.
+### Using Docker-Compose
 
-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 <client-id>`.
-
-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.
+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/).
 
-## Installation
+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.
 
-### As container
+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
 
-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 .
+TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com docker compose up
 ```
 
-Now to run it, simply exec.
-```sh
-docker run -t -d \
-  --name=taskchampion \
-  -p 8080:8080 \
-  taskchampion-sync-server
+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]
 ```
 
-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.
+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.
 
-#### Persist data using a container volume
+### Running the Binary
 
-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
-```
+The server is configured with command-line options. See
+`taskchampion-sync-server --help` for full details.
 
-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
-```
+The `--data-dir` option specifies where the server should store its data, and
+`--port` gives the port on which the HTTP server runs.
 
-### From source
+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 <client-id>`.
+
+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
 
@@ -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
@@ -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