This page describes a simplified deployment of LEAF-Writer using docker compose and specially crafted scripts. This method currently works only on the `exp` branch but is expected to be merged into the `dev` and `main` branches.
This page describes a simplified deployment of LEAF-Writer using docker compose and specially crafted scripts. This method currently works only on the `exp` branch but is expected to be merged into the `dev` and `main` branches.
To deploy the branches `main` and `dev` see (Deployment)[deployment]. After the merge of the current `exp` branch, the Deployment page will describe a full manual deployment. A manual deployment can bee desirable if e.g. the Keycloak server is used as a login provider for other services as well.
To deploy the branches `main` and `dev` see [Deployment](deployment). After the merge of the current `exp` branch, the Deployment page will describe a full manual deployment. A manual deployment can be desirable if e.g. the Keycloak server is used as a login provider for other services as well.
# Prerequisites
# Prerequisites
You need a server with installed `docker` and the `docker compose` plugin. The server mus be reachable from the internet and must have a domain like `leafwriter.your-university.example.com` assigned and properly configured (DNS etc.). This server needs to have a web server such as Apache or Nginx installed to act as a reverse proxy. You must have the right to execute docker containers either directly or via `sudo` and you must be able to configure the web server.
You need a server with installed `docker` and the `docker compose` plugin. The server mus be reachable from the internet and must have a domain like `leafwriter.your-university.example.com` assigned and properly configured (DNS etc.). This server needs to have a web server such as Apache or Nginx installed and running to act as a reverse proxy. You must have the right to execute docker containers either directly or via `sudo` and you must be able to configure the web server.
LEAF-Writer must be exposed to the internet only via an encrypted connection (`https`). It is the task of the reverse proxy ensure an encrypted connection, therefore you need a suitable certificate. It is enough if this certificate is valid for your chosen domain, e.g. `leafwriter.your-university.example.com`, no subdomain or wildcard capabilities are needed. You can use a `Let's encrypt` certificate, issued via `certbot`.
LEAF-Writer must be exposed to the internet only via an encrypted connection (`https`). It is the task of the reverse proxy ensure an encrypted connection, therefore you need a suitable certificate. It is enough if this certificate is valid for your chosen domain, e.g. `leafwriter.your-university.example.com`, no subdomain or wildcard capabilities are needed. You can use a `Let's encrypt` certificate, issued via `certbot`.
The following deployment tutorial will assume that you use (and have installed) `cerbot` to get a SSL-certificate. However, as described, you can also use other certificates, you just have to properly configure them in conjunction with your reverse proxy.
The following deployment tutorial will assume that you use (and have installed) `cerbot` to get a SSL-certificate. However, as described, you can also use other certificates, you just have to properly configure them in conjunction with your reverse proxy.
...
@@ -21,4 +21,5 @@ The machine you want to deploy LEAF-Writer on also needs to have `git` installed
...
@@ -21,4 +21,5 @@ The machine you want to deploy LEAF-Writer on also needs to have `git` installed
7. Adjust the given environment variables as described in the file. See below for how to obtain a `GEONAMES_USERNAME`. It is **highly recommended** to point `keycloak_data_folder` to a an absolute path that resides outside of the LEAF-Writer folder.
7. Adjust the given environment variables as described in the file. See below for how to obtain a `GEONAMES_USERNAME`. It is **highly recommended** to point `keycloak_data_folder` to a an absolute path that resides outside of the LEAF-Writer folder.
8. Run the automatic setup docker compose script: `sudo docker compose --env-file leafwriter.env -f leafwriter-configuration-files/docker-compose-keycloak-firstrun.yml up`
8. Run the automatic setup docker compose script: `sudo docker compose --env-file leafwriter.env -f leafwriter-configuration-files/docker-compose-keycloak-firstrun.yml up`
9. Wait until you see a line similar to `keycloak-thirdrun-1 exited with code 0`. Stop the running containers with e.g. `Ctrl+c` and run `sudo docker compose --env-file leafwriter.env -f leafwriter-configuration-files/docker-compose-keycloak-firstrun.yml down` to remove them
9. Wait until you see a line similar to `keycloak-thirdrun-1 exited with code 0`. Stop the running containers with e.g. `Ctrl+c` and run `sudo docker compose --env-file leafwriter.env -f leafwriter-configuration-files/docker-compose-keycloak-firstrun.yml down` to remove them
10. Build and run LEAF-Writer and all its dependencies by running: `sudo docker compose --env-file leafwriter.env -f docker-compose.yml up` If you feel brave enough, you can
10. Build and run LEAF-Writer and all its dependencies by running: `sudo docker compose --env-file leafwriter.env -f docker-compose.yml up` If you feel brave enough, you can add the `-d` option to directly launch the containers in the background. It is, however, advisable to first launch LEAF-Writer with enabled output stream to see if any problems are identifiable by the logs. You should, therefore, probably continue the rest of the steps in a second terminal and once everything is up and running switch to the detached mode. You can do this by exiting the containers with `Ctr+c`, run `sudo docker compose --env-file leafwriter.env -f docker-compose.yml down` and then `sudo docker compose --env-file leafwriter.env -f docker-compose.yml up -d`
