From 87ed132ae4d23724818b4f3ee967a1ed24220a92 Mon Sep 17 00:00:00 2001 From: Daniel Wiesenberg Date: Tue, 4 Aug 2020 22:06:13 +0200 Subject: [PATCH] Add README in docker folder and mention docker in Conduit's README --- README.md | 3 +++ docker/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docker/README.md diff --git a/README.md b/README.md index 404636af..4c840406 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ Yes! Just open a Matrix client ( or Element Android for You just have to clone the repo, build it with `cargo build --release` and call the binary (target/release/conduit) from somewhere like a systemd script. It's explained in more detail [here](https://git.koesters.xyz/timo/conduit/wiki/Deploy). +Or you can just build the docker image and run it with docker or docker-compose. +It's explained in more details [here](https://git.koesters.xyz/timo/conduit/wiki/Docker) or in the [README](docker/README.md) in the docker folder. + #### What is it build on? - [Ruma](https://www.ruma.io): Useful structures for endpoint requests and responses that can be (de)serialized diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 00000000..f7add181 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,62 @@ +# Docker +> **Note:** To run and use Conduit you should probably use it with a Domain or Subdomain behind a reverse proxy (like Nginx, Traefik, Apache, ...) with a Lets Encrypt certificate. + +This text is also available at the [official wiki](https://git.koesters.xyz/timo/conduit/wiki/docker). + +## Build & Dockerfile +The Dockerfile provided by Conduit has two stages, each of which creates an image. +1. **Builder:** Builds the binary from local context or by cloning a git revision from the official repository. +2. **Runtime:** Copies the built binary from **Builder** and sets up the runtime environment, like creating a volume to persist the database and applying the correct permissions. + +The Dockerfile includes a few build arguments that should be supplied when building it. + +``` Dockerfile +ARG LOCAL=false +ARG CREATED +ARG VERSION +ARG GIT_REF=HEAD +``` + +- **CREATED:** Date and time as string (date-time as defined by RFC 3339). Will be used to create the Open Container Initiative compliant label `org.opencontainers.image.created`. Supply by it like this `$(date -u +'%Y-%m-%dT%H:%M:%SZ')` +- **VERSION:** The SemVer version of Conduit, which is in the image. Will be used to create the Open Container Initiative compliant label `org.opencontainers.image.version`. If you have a `Cargo.toml` in your build context, you can get it with `$(grep -m1 -o '[0-9].[0-9].[0-9]' Cargo.toml)` +- **LOCAL:** *(Optional)* A boolean value, specifies if the local build context should be used, or if the official repository will be cloned. If not supplied with the build command, it will default to `false`. +- **GIT_REF:** *(Optional)* A git ref, like `HEAD` or a commit ID. The supplied ref will be used to create the Open Container Initiative compliant label `org.opencontainers.image.revision` and will be the ref that is cloned from the repository when not building from the local context. If not supplied with the build command, it will default to `HEAD`. + +To build the image you can use the following command + +``` bash +docker build . -t conduit_homeserver:latest --build-arg CREATED=$(date -u +'%Y-%m-%dT%H:%M:%SZ') --build-arg VERSION=$(grep -m1 -o '[0-9].[0-9].[0-9]' Cargo.toml) +``` + +which also will tag the resulting image as `conduit_homeserver:latest`. +**Note:** it ommits the two optional `build-arg`s. + +## Run +After building the image you can simply run it with + +``` bash +docker run conduit_homeserver:latest -p 8448:8000 -v db:/srv/conduit/.local/share/conduit -e ROCKET_SERVER_NAME="localhost:8000" +``` + +For detached mode, you also need to use the `-d` flag. You can pass in more env vars as are shown here, for an overview of possible values, you can take a look at the `docker-compose.yml` file. +If you just want to test Conduit for a short time, you can use the `--rm` flag, which will clean up everything related to your container after you stop it. + + +# Docker-compose +If the docker command is not for you or your setup, you can also use one of the provided `docker-compose` files. Depending on your proxy setup, use the `docker-compose.traefik.yml` including `docker-compose.override.traefik.yml` or the normal `docker-compose.yml` for every other reverse proxy. + +## Build +To build the Conduit image with docker-compose, you first need to open and modify the `docker-compose.yml` file. There you need to comment the `image:` option and uncomment the `build:` option. Then call docker-compose with: + +``` bash +CREATED=$(date -u +'%Y-%m-%dT%H:%M:%SZ') VERSION=$(grep -m1 -o '[0-9].[0-9].[0-9]' Cargo.toml) docker-compose up +``` + +This will also start the container right afterwards, so if want it to run in detached mode, you also should use the `-d` flag. For possible `build-args`, please take a look at the above `Build & Dockerfile` section. + +## Run +If you already have built the image, you can just start the container and everything else in the compose file in detached mode with: + +``` bash +docker-compose up -d +```