Rewrite of README

README.md

@@ -6,130 +6,104 @@ This git project contains everything required to start labkey as a docker contai
 
 ### Prepare
 
-- Install [`docker`][docker] and [`docker-compose`][dockerCompose]
-- create a user `labkey` with `docker` privileges
+- Install [`docker`][docker] 
+- create a user `labkey` with `docker` privileges 
 
-```bash
-sudo adduser labkey
-sudo usermod -G docker labkey
-```
+   ```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
-```
+   ```bash
+   sudo su labkey
+   cd
+   git clone https://git0.fmf.uni-lj.si/studen/labkeyDocker.git
+      ```
 
 ### Database
 
-Create directory or copy appropriate database cluster to `labkeyDocker/postgresql/data`:
-
-```bash
-mkdir -p labkeyDocker/postgresql/data
-```
-
-Links are OK, too. Exact path is set in `bin/env.sh`, see below.
+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
-```
+   ```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
+   ```
+
+### Install LabKey binaries
+
+Copy target binaries from [LabKey][LabKeyBinaries] or [legacy repository][resources] to `$HOME/packages`. Uninstall and (re)install target binaries:
+
 ```bash
-export EXTERNAL_MODULES=$HOME/externalModules
-export LABKEY_FILES=/data/labkey/files
+labkeyDocker/bin/uninstallLabkey.sh
+labkeyDocker/bin/installLabkey.sh X
 ```
 
-### Install LabKey binaries
+### 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.
 
-- copy binaries from `https://labkey-public.fmf.uni-lj.si/labkey/Resources to `$HOME/packages`. Remember the version number for next step.
-- run `labkeyDocker/bin/installLabkey.sh 22` to unzip the LabKey binary code and make appropriate links.
-- copy `labkeyDocker/bin/env.sh.sample` to `labkeyDocker/bin/env.sh` and set a secret `$PGPASS`, other settings are probably OK, 
-  check `$DOCKERCOMPOSE`
-- copy 
-- set the same value as `password` in `labkeyDocker/tomcat/conf/Catalina/localhost/labkey.xml` 
+### Setup labkey (`labkey.xml`)
 
-### Permissions
+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` 
 
-To run as non-root user labkey, files should have the proper permissions. I believe that starting from scratch, 
-the neccesary files will be created with appropriate permissions. If using an old implementation or in case of troubles, the following directories should be owned by labkey:labkey on host machine:
+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.
 
-```bash
-~/labkey/externalModules
-~/labkey/files
-```
 
 ### Start containers
   
 Run `bin/startLabkey.sh`. This will do several things:
-   - Download PostgreSQL image and initialize a persistent database at `~/postgresl/data`. 
   - 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:8443/labkey`. Check output of inidividual 
+In principle, the service should be running at `http://localhost:8080/labkey`. Check output of inidividual 
   components by:
   
 ```bash
-  docker logs config-db-1
-  docker logs config-web-1
-  docker exec -it config-db-1 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 ggplot2 to R
-
-Connect to running instance of labkey:
+### Add libraries to R
 
-```bash
-docker exec -it config_labkey-web_1 bash
-```
-
-Start R:
-
-```bash
-R
-```
-
-In R, install`ggplot2` with dependencies:
-
-```R
-install.packages('ggplot2', repos='http://cran.us.r-project.org', dependencies=TRUE)
-```
-
-#### Install ggpubr
-
-For ggpubr, install `cmake` first. When in config_labkey-web_1 do:
-```bash
-apt update
-apt install cmake
-```
-
-Then, in R:
-```R
-install.packages('ggpubr')
-```
-
-### Manage postgresql
-
-Create `${POSTGRES_DIR}` directory as user that will be running the container.
-If you have trouble with initial setup, the base can be reset by deleting everything under `postgresql/data`.
-
-
-### Expected errors
-  
-Errors of the type `500: Unexpected server error` are common and related 
+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
 
@@ -143,4 +117,8 @@ $ docker push andrejstuden/nix:x21
 ```
   
 [docker]: https://docs.docker.com/engine/install/
-[dockerCompose]: https://docs.docker.com/compose/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/