# Labkey as a docker container

This git project contains everything required to start labkey as a docker container.

## Installation

### Prepare

- Install [`docker`][docker] 
- create a user `labkey` with `docker` privileges 

   ```bash
   sudo adduser labkey
   sudo usermod -G docker labkey
   ```

- clone the software 

   ```bash
   sudo su labkey
   cd
   git clone https://git0.fmf.uni-lj.si/studen/labkeyDocker.git
   ```

### Database

Set path as `POSTGRES_DIR` in `labkeyDocker/bin/env.sh`, see below. If you don't have an existing database, it is
enough to create the directory `PGPASS` from `env.sh` and `postgresql` container will create one.

EXPERT USE: To use existing database, make sure the version of the database match the container. Container versions
are set in corresponding Dockerfiles, check the one `COMPOSE` in `env.sh` points to. Adjust `PGPASS` and `password` 
in `env.sh` and `labkey.xml` accordingly.

Check if database runs:

   ```bash
   labkeyDocker/bin/startPGonly.sh
   docker logs config-labkey-db-1
   labkeyDocker/bin/stopLabkey.sh
   ```

### Files and external modules for LabKey

The files and externalModules locations are set in `bin/env.sh`, see `bin/env.sh.sample`:
   ```bash
   export EXTERNAL_MODULES=$HOME/externalModules
   export LABKEY_FILES=/data/labkey/files
   ```
Best practice is to have `labkey` own this paths.

### Install LabKey binaries

Copy target binaries from [LabKey][LabKeyBinaries] or [legacy repository][resources] to `$HOME/packages`. Uninstall and (re)install target binaries:

```bash
labkeyDocker/bin/uninstallLabkey.sh
labkeyDocker/bin/installLabkey.sh X
```

### Adjust system properties
Copy `labkeyDocker/bin/env.sh.sample` to `labkeyDocker/bin/env.sh` and update enviorment variables:
   - `POSTGRES_DIR` for location of database (on host system)
   - set a secret `PGPASS`, should match the one used in database creation if database already exists
   - set links to resources: `EXTERNAL_MODULES`, `LABKEY_FILES`
   - both `EXTERNAL_MODULES` as well as `LABKEY_FILES` should be owned by `labkey` user.
   - check `DOCKERCOMPOSE`, normally default  `docker compose` is OK, but older docker version shipped compose separately as `docker-compose`.
   - check that the `COMPOSE` points to the right `.yaml` file, where versions of labkey and compose match.
   - for running behind SSL, `hidden` compose files are available, where access ports (8080, 8443) are not shared by the host. Use a reverse proxy, like
   [this one][rproxyDocker] to terminate SSL connection.

### Setup labkey (`labkey.xml`)

Copy `labkeyDocker/tomcat/conf/Catalina/localhost/labkey.xml.temp` to `labkey.xml` in the same directory.
- set the same value as `env.sh:PGPASS` as `password` in `labkey.xml` 

EXPERT USE: In `labkey.xml` one can adjust the postgresl ports and/or server if other than dedicated server is used. 

Docker will also map `labkeyDocker/tomcat/bin/setenv.sh` to container space, which gives some global settings to the 
[tomcat][] engine of LabKey.

EXPERT USE: In `setenv.sh` one can adjust java settings, for example `add-exports` to expose internal Java implementations, ie. for 
direct [WebSocket][java17Websocket] use.


### Start containers
  
Run `bin/startLabkey.sh`. This will do several things:
  - Build a combined tomcat/R image from a recent version of tomcat
  - Copy and link files from home to the server
  - Start the server

### Check the installation
  
In principle, the service should be running at `http://localhost:8080/labkey`. Check output of inidividual 
  components by:
  
```bash
  docker logs config-labkey-db-1
  docker logs config-labkey-web-1
  docker exec -it config-labkey-db-1 bash
  docker exec -it config-labkey-web-1 bash
```

### Add libraries to R

The appropriate Dockerfile (see section on prebuilt images below) should add typicall libraries to container. Should you find a further library 
you should need, contact me or update your dockerfile similarly to examples in `Dockerfile21`.

# Pre-building images

In the latest version, images can be pre-built using docker hub as a repository for such images lacking adaptation to individual working environment.

To create such images, do
```bash
$ docker build -f config/web/Dockerfile21 -t andrejstuden/nix:x21 config/web
$ docker login -u andrejstuden docker.io
$ docker push andrejstuden/nix:x21
```
  
[docker]: https://docs.docker.com/engine/install/
[resources]: https://labkey-public.fmf.uni-lj.si/labkey/Resources
[LabKeyBinaries]: https://www.labkey.com/download-community-edition/
[rproxyDocker]: https://git0.fmf.uni-lj.si/studen/rproxyDocker
[java17Websocket]: https://docs.oracle.com/en/java/javase/17/docs/api/java.net.http/java/net/http/WebSocket.html
[tomcat]: https://tomcat.apache.org/