Skip to content
Snippets Groups Projects

Deployment

Last edited by Jacob Benz

Following this guide will lead to a fully functional leafwriter instance.

Note: Setting up leafwriter is an involved process that requires various dependencies up and running.

Prerequisites

  • Working docker installation including docker compose
  • proxy server: The following guide will assume nginx. The sample configuration files are for nginx. Better - as in better free software - webservers like Apache can be obviously used as well.
  • Certificates for SSL. The following guide will assume that letsencrypt-certificates via certbot are used and that certbot with a plugin for the chosen proxy server is installed. However other certificates will work as well, configuration of them is not discussed here.
  • Working sudo command. Alternatively you have to make sure, that the user you are using for setup has the privileges to start docker containers.

Repositories

To deploy LEAF-Writer, three repositories are needed.

  1. The main leafwriter repository, available at: https://code.fbi.h-da.de/leaf-writer-x/leafwriter-x/
  2. The Auth-APi repository, available here: https://gitlab.com/calincs/infrastructure/auth-api
  3. The NSSI repository, available from upstream at: https://gitlab.com/calincs/conversion/NSSI

For convenience, a repository with example nginx-configuration files is available: https://code.fbi.h-da.de/leaf-writer-x/dependencies/nginx-conf-files

All three repositories should be cloned and available for the next steps

Setup

Disable the default configured site of your webserver. If your are using nginx on Debian or a derivate you can do this by rm /etc/nginx/sites-enabled/default followed by a restart/reload of the webserver.

If you have chosen to use the example nginx config files, clone that repo as well and copy the provided files to e.g. /etc/nging/sites-available

Keycloak

  1. Switch to the cloned NSSI-repository
  2. Modify the file docker-compose.keycloak.yml
    • In the section volumes add ./ in front of keycloak-data:/var/lib/postgresql/data
    • Under environment:
      • Set KEYCLOAK_PASSWORD to a unique password.
      • Add PROXY_ADDRESS_FORWARDING=true
      • Change KEYCLOAK_FRONTEND_URL to https://keycloak.example.com/auth/ where example.com is the domain you want to run Leaf-Writer on.
  3. sudo docker compose -f docker-compose.keycloak.yml build
  4. Start the containers with e.g. sudo docker compose -f docker-compose.keycloak.yml up -d
  5. Change server_name under /etc/nginx/sites-available/keycloak to a appropriate value like keycloak.example.com
  6. Enable the keycloak proxy with e.g. sudo ln -s /etc/nginx/sites-available/keycloak /etc/nginx/sites-enabled/
  7. Restart/reload nginx
  8. If you opt to use let's-encrypt certificates obtain one with e.g. sudo certbot -d keycloak.example.com
  9. Check that you can access keycloak and login with the set admin password under the url you chose.
  10. Add a new realm by hovering over "Master" on the left side and choose "Add realm". Name the new realm lincs

Setup Github as authorization provider

Note: You can use alternatively gitlab, the code for that should be in Leaf Writer, however, this is by default disabled. Especially if you want to use your own Gitlab instance, further code modification is necessary.

  1. Go to the realm "lincs". Select "Identity providers"
  2. Chose "Github" as identity provider
  3. Go to github and log in with the account you want to use to provide the OAuth authentication. This will be the account users logging in to LEAF Writer will see, when Github informs them about the permission they give. So use an appropriate account name.
  4. On Github go to "Settings -> Developer Settings" (the last option on the settings page, far down).
  5. Select "OAuth Apps" -> "New OAuth App"
  6. Chose a name, preferably something like "Leaf Writer". Set as homepage the URL to your LEAF Writer installation like "https://leafwriter.example.com/", as callback URL copy the URL named "Redirect URI" from the "Add identity provider" page in Keycloak. Add a description so users know, what LEAF Writer is.
  7. Copy the "client ID" and "Client Secret" from Github to Keycloak.
  8. Set "repo user:email" as default scopes in Keycloak (Note: This enabled access to private repos, if you wan't less access, chose a different scope, "user:email" is always needed.)
  9. Enable "Store Tokens" and "Stored Tokens readable" in Keycloak.
  10. Save the new identity provider.

Setup clients

  1. Go to "Clients" in the realm "lincs".
  2. Select "admin-cli".
  3. Change "Access type" to confidential and save.
  4. Go to the tab "Credentials" and keep the "Secret" ready to put it in configuration files later.
  5. Go back to "clients" and create a new client, named "nssi".
  6. After creating the client, set the "Access type" to confidential and fill in the following fields, replacing "example.com" with your domain:
  7. Save
  8. Write down the secret under the "Credentials" tab.
  9. Create a new client again, called "leaf-writer"
  10. Put the following in the client settings and save, again replace "example.com" with your URL:
  11. Go to the tab "Scope" of the client leaf-writer and check that "Full Scope allowed" is checked.
  12. Go to the tab "Mappers".
  13. Select "Add Builtin".
  14. Select the options "family name", "username", "given name", "realm roles" and add these.
  15. Select "Create".
  16. Chose "Mapper Type" User Session Note
  17. Enter for "Name", "User Session Note" and "Token Claim Name" identity_provider.
  18. Select String for "Claim JSON Type".
  19. Save.

NSSI

To build the NSSI docker images, a Java 18 installation is necessary. You can use the method of your distribution to install openJDK 18. If you can't or don't want to, see the NSSI Readme for a manual method. Note that if you used the manual installation method and use sudo to start containers you need something like sudo -E [command] to preserve the java path.

  1. Install openJDK 18.
  2. Switch to the cloned NSSI-repository.
  3. Build the docker images
    • sudo ./mvnw clean install && sudo ./mvnw jib:dockerBuild -pl Service/ -Ddebug
    • sudo ./mvnw clean install -pl NSSIGateway && sudo ./mvnw compile jib:dockerBuild -pl NSSIGateway
  4. In the file docker-compose.yml set the following environment variables:
    • KEYCLOAK_SECRET=[Secret for the client "nssi"]
    • KEYCLOAK_ADMIN_CLI_SECRET=[Secret for the admin-cli]
  5. Start the docker containers with e.g. sudo docker compose -f docker-compose.yml up -d
  6. Change server_name under /etc/nginx/sites-available/nssi to a appropriate value like nssi.example.com
  7. Enable the nssi proxy with e.g. sudo ln -s /etc/nginx/sites-available/nssi /etc/nginx/sites-enabled/
  8. Restart/reload nginx
  9. If you opt to use let's-encrypt certificates obtain one with e.g. sudo certbot -d nssi.example.com
  10. Check that you can access nssi under your chosen domain. If you can, you should see a page named "Whitelabel error page"

auth-api

  1. Change to the auth-api folder.
  2. Edit the file docker-compose.yml, replace example.com with the appropriate values
    • KEYCLOAK_BASE_URL: https://keycloak.example.com/auth
    • ADMIN_USER: admin
    • ADMIN_PASSWORD: [password you set for the keycloak admin account earlier]
    • ADMIN_CLI_SECRET: [secret you wrote down for the admin-cli]
  3. These env-variables meanwhile have been slightly renamed, figuring them out is left as an exercise for the reader.
  4. The exposed port has also been changed. It is now by default 3000 which conflicts with LeafWriter itself? You have to figure that out as well and correct it in the docker-compose.yml-file and the configuration file for the reverse proxy.
  5. Again, if you are using the updated version of auth-api, it will not properly work with the way this guide configured Keycloak, I don't know why and I don't care. If you don't care either, you can either ignore this problem entirely and accept a non-fatal error on login with GitHub or you can comment out every instance of middleware: [KC.protect('admin')] in the file apps/api/src/routes/v1/users/index.ts.
  6. Build the docker image with e. g. sudo docker compose -f docker-compose.yml build
  7. Start the docker image with e.g. sudo docker compose -f docker-compose.yml up -d
  8. Change server_name under /etc/nginx/sites-available/authapi to a appropriate value like authapi.example.com
  9. Enable the authapi proxy with e.g. sudo ln -s /etc/nginx/sites-available/authapi /etc/nginx/sites-enabled/
  10. Restart/reload nginx
  11. If you opt to use let's-encrypt certificates obtain one with e.g. sudo certbot -d authapi.example.com
  12. Check that you can access the authapi under your chosen domain. If you can, you should see a page with "LINCS Keycloak admin functions. Use /accountLinkUrl or /linkedAccounts"

LEAF-Writer

Note: Building the docker image of LEAF Writer may fail at the npm install step. The author of this guide has no clue why this is. A solution is, to first install nodejs and do a npm install locally in the repo. After this, the docker build succeeds.

  1. Change to the leafwriter folder
  2. Edit the file docker-compose.yml, replace example.com accordingly:
    • KEYCLOAK_URL=https://keycloak.example.com/auth
    • NSSI_URL=https://nssi.example.com
    • AUTH_API_URL=https://authapi.example.com
  3. Build the docker image with e. g. sudo docker compose -f docker-compose.yml build
  4. Start the docker image with e.g. sudo docker compose -f docker-compose.yml up -d
  5. Change server_name under /etc/nginx/sites-available/leaf to a appropriate value like leafwriter.example.com
  6. Enable the leafwriter proxy with e.g. sudo ln -s /etc/nginx/sites-available/leaf /etc/nginx/sites-enabled/
  7. Restart/reload nginx
  8. If you opt to use let's-encrypt certificates obtain one with e.g. sudo certbot -d leafwriter.example.com
  9. Go to the chosen url and LEAF Writer should run and you should be able to sign in with Github. Check in the developer console that especially the "keycloak.example.com" and "auth-api.example.com" are successfully accessed by LEAF Writer. If everything works, you deserve now some of your favorite drugs as a reward, if not, good luck finding the problem …

Comments

    Please register or sign in to add a comment.