update readme for >=24.3 (#96)

* readme updates for >=24.3
LabKey · May 13, 2024 · 401ddf3 · 401ddf3
1 parent 21edf7a
commit 401ddf3
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -6,11 +6,18 @@ This repo contains a Dockerfile, `docker-compose.yml`, and various other files f
 
 This repo is a work in progress. Containers created from these sources are untested. Until further work is done, integrations with LabKey products that traditionally have relied on OS configuration such as R reports or Python scripts will **NOT** work.
 
+## Upgrading from 23.11 to 24.3
+March 2024 saw [many changes](https://github.com/LabKey/Dockerfile/commits/24.3.0) in an effort to bring this repo in line with LabKey server versioning/releases, starting with v24.3, in which the embedded tomcat version has been upgraded from 9 to 10. 
+
+v24.3 also removes the version number from the .jar extracted from the build archive, so it is now simply `labkeyServer.jar`.
+
+Using a pre-24.3 version of the .jar with a post-24.3 version of this repo will fail spectacularly.
+
 ## Prerequisites
 
 To fully use this repo, you will need installed:
 
-- Docker >= v20.10.9 recommended 
+- Docker >= v20.10.24 recommended 
 - GNU Make
 - GNU Awk
 
@@ -20,7 +27,8 @@ Optionally, to publish containers to AWS's ECR service using this repo's `Makefi
 
 **You will also need the `.jar` file of an embedded LabKey distribution.**
 
-A [`COPY` instruction](https://docs.docker.com/engine/reference/builder/#copy) in the Dockerfile expects this `.jar` file's filename to look like: "labkeyServer-${LABKEY_VERSION}.jar" (where `LABKEY_VERSION` is defined by the "LABKEY_VERSION" environment variable), and for it to be **in the root of this repo**. You will mostly likely _not_ need to rename the file, but you _will_ need to set `LABKEY_VERSION` according to the version within the file's name.
+A [`COPY` instruction](https://docs.docker.com/engine/reference/builder/#copy) in the Dockerfile expects this `.jar` file's filename to look like: "labkeyServer.jar", and for it to be **in the root of this repo**. 
+Set the `LABKEY_VERSION` environment variable to the version number from the installation archive filename (eg '24.3.4' from 'LabKey24.3.4-6-community-embedded.tar.gz').
 
 You can obtain this file by following these steps:
 
@@ -38,7 +46,7 @@ You can obtain this file by following these steps:
   1. Copy in the labkey community embedded `.jar` file to the same directory as the repo (see above on how to obtain)
   1. Export the minimal required environment variables or edit and source the quickstart_envs.sh
 
-        `export LABKEY_VERSION="21.9.0"` ... 
+        `export LABKEY_VERSION="24.3.4"` ... 
      
         or
      
@@ -60,7 +68,7 @@ You can obtain this file by following these steps:
 
 ## Building a Container
 
-This repo includes a `Makefile` which aim is to ease the running of the necessary commands for creating containers. The **default action** of the `Makefile` is to log into the AWS ECR service, build, tag, and push a docker container (the `all:` target) to an ECR repo named after the chosen distribution.
+This repo includes a `Makefile` which aims to ease the running of the necessary commands for creating containers. The **default action** of the `Makefile` is to log into the AWS ECR service, build, tag, and push a docker container (the `all:` target) to an ECR repo named after the chosen distribution.
 
 Building a container is as simple as `make build`:
 
@@ -70,10 +78,10 @@ docker build \
   --rm \
   --compress \
   --no-cache \
-  -t labkey/community:21.3-snapshot \
+  -t labkey/community:24.3.4 \
   -t labkey/community:latest \
   --build-arg 'DEBUG=' \
-  --build-arg 'LABKEY_VERSION=21.3-SNAPSHOT' \
+  --build-arg 'LABKEY_VERSION=24.3.4' \
   --build-arg 'LABKEY_DISTRIBUTION=community'
   --build-arg 'LABKEY_EK=123abc456' \
   .
@@ -84,7 +92,7 @@ Step 27/27 : ENTRYPOINT /entrypoint.sh
 Removing intermediate container db19946ff9de
  ---> 6c15d5de57a6
 Successfully built 6c15d5de57a6
-Successfully tagged labkey/community:21.3-snapshot
+Successfully tagged labkey/community:24.3.4
 Successfully tagged labkey/community:latest
 ```
 
@@ -115,25 +123,38 @@ Setting `DEBUG` to any value will suffice: `docker build ... --build-arg DEBUG=1
 
 ## Docker
 
-The `Dockerfile` currently supports 2 base-container operating systems, Alpine Linux and Debian-based Linux. Both of which originate from `eclipse-temurin`. Toggling between the two or overriding them can be achieved by changing the `FROM_TAG` Docker build arg. The `Dockerfile` provides 2 examples:
+The `Dockerfile` currently supports 2 base-container operating systems, Alpine Linux and Debian-based Linux, both of which originate from `eclipse-temurin`. Debian-based Linux deployments are much more thoroughly tested. Toggling between the two or overriding them can be achieved by changing the `FROM_TAG` Docker build arg. The `Dockerfile` provides 2 examples:
 
-- alpine-based
-  - FROM_REPO_IMAGE=eclipse-temurin
-  - FROM_TAG=17-jre-alpine
 - debian-based
-  - FROM_REPO_IMAGE=eclipse-temurin
   - FROM_TAG=17-jre
+- alpine-based
+  - FROM_TAG=17-jre-alpine
+
+| name            | purpose                                                                          | default                  |
+| --------------- | ------------------------------------------------------                           | ------------------------ |                          
+| FROM_REPO_IMAGE | Docker repository & image to use as basis of container                           | `eclipse-temurin` |
+| FROM_TAG        | repository tag to use as basis of container                                      | `17-jre`             |
+| LABKEY_HOME     | The Docker WORKDIR and top level under which all LabKey-related files are nested | `/labkey` |
+| BUILD_REMOTE_TAG | allows for alternate remote tags during `make tag` and `make push`  | [BUILD_REPO_URI]/labkey/community:[LABKEY_VERSION] |
+
+## Docker Compose
 
-| name            | purpose                                                | default                  |
-| --------------- | ------------------------------------------------------ | ------------------------ |
-| FROM_REPO_IMAGE | Docker repository & image to use as basis of container | `adoptopenjdk` |
-| FROM_TAG        | repository tag to use as basis of container            | `16-jre`             |
+Several ENVs and 'up' commands were added to faciliate running different distribution containers on the same system (though not simultaneously)
+
+| name          | purpose                                                                    | default|
+| ----          | ----                                                                       | -----   |
+| COMPOSE_IMAGE | 'image:' for docker-compose service                                         | labkey/community |
+| IDENT         | isolate postgres data directory from other containers (.pgdata/[IDENT]-data) | postgres |
+
+These can be leveraged with commands such as:
+* COMPOSE_IMAGE=labkey/lims_starter IDENT=lims_starter LABKEY_DISTRIBUTION=lims_starter make up-lims_starter
+* COMPOSE_IMAGE=labkey/enterprise IDENT=enterprise LABKEY_DISTRIBUTION=enterprise make up-enterprise
 
 ## LabKey
 
-Original locations for these configuration details range from XML file contents from `server.xml` to `context.xml` (`ROOT.xml` or `labkey.xml`), to ENVs consumed by java (`JAVA_OPTS`), ENVs consumed directly by LabKey, and ENVs consumed by tomcat (`setenv.sh`, `CATALINA_OPTS`). The goal here is to expose them all as ENVs configurable via Docker at both build time and run time.
+Non-Docker LabKey server installations prior to 24.3 kept configuration details in a range of XML files (eg `server.xml`, `ROOT.xml`, `labkey.xml`), ENVs consumed by java (`JAVA_OPTS`), ENVs consumed directly by LabKey, and ENVs consumed by tomcat (`setenv.sh`, `CATALINA_OPTS`). The goal *here* is to expose them all as ENVs configurable via Docker at both build time and run time. If you are migrating to this Docker setup from a standard server installation, you may need to first gather your configuration details. See [this upgrade document](https://www.labkey.org/Documentation/wiki-page.view?name=labkeyxml) for more details, but note that it is intended for server-to-server migrations, not server-to-Docker.
 
-A better description of the LabKey settings can be found [in the LabKey docs](https://www.labkey.org/Documentation/wiki-page.view?name=customizeLook#properties).
+A better description of the LabKey settings can be found in the LabKey docs [here](https://www.labkey.org/Documentation/wiki-page.view?name=customizeLook#properties).
 
 `LABKEY_GUID` is only relevant if you are attempting to created/run a container destined to connect to a pre-existing database belonging to a pre-existing LabKey.
 
@@ -204,7 +225,7 @@ The `CERT_*` ENVs should look familiar to anyone that has used the `openssl` com
 | TOMCAT_KEYSTORE_ALIAS        | self-signed cert/keystore "alias"                            | `tomcat`                                                 |
 | TOMCAT_KEYSTORE_FILENAME     | self-signed cert/keystore filename                           | `labkey.p12`                                             |
 | TOMCAT_KEYSTORE_FORMAT       | self-signed cert/keystore format                             | `PKCS12`                                                 |
-| TOMCAT_SSL_CIPHERS           | allowable SSL ciphers for use by Spring Boot                 | `HIGH:!ADH:!EXP:!SSLv2:!SSLv3:!MEDIUM:!LOW:!NULL:!aNULL` |
+| TOMCAT_SSL_CIPHERS           | allowable SSL ciphers for use by tomcat | `HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!kRSA:!EDH:!DHE:!DH:!CAMELLIA:!ARIA:!AESCCM:!SHA:!CHACHA20` |
 | TOMCAT_SSL_ENABLED_PROTOCOLS | allowable SSL protocols and versions                         | `TLSv1.3,TLSv1.2`                                        |
 | TOMCAT_SSL_PROTOCOL          | basic SSL protocol to use                                    | `TLS`                                                    |
 | CERT_C                       | "Country" value for the generated self-signed cert           | `US`                                                     |
@@ -228,12 +249,10 @@ Since java can be picky about the position of CLI values, `JAVA_PRE_JAR_EXTRA` a
 
 ## Development Notes
 
-In contrast to `application.properties`, the "startup properties" files housed in `startup/`, are LabKey's own implementation of `.properties` file(s) and generally are less feature rich that Springs'. Environment Variable substitution for example does not function within LabKey `.properties` files, which is why `gettext` is required for `entrypoint.sh`'s use of `envsubst`.
+In contrast to `application.properties`, the "startup properties" files housed in `startup/`, are LabKey's own implementation of `.properties` file(s) and generally are less feature rich that Spring Boot's, and are specific to LabKey application settings.
 
 ## Tips
 
-Users of macOS will have more luck using GNU Make as installed by **Homebrew** and executed as `gmake`.
-
 Q: Why is my labkey container "unhealthy"?
 
 A: LabKey containers produced from this repo contain a [`HEALTHCHECK` instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) which defines a simple "smoke" test Docker can use internally to determine if the container is healthy. The healthcheck built into this Dockerfile boils down to a `curl` to `localhost`-- but it can be customized based on a number of `HEALTHCHECK_*` ENVs that the Dockerfile defines. A customization that may be helpful would be to define a `HEALTHCHECK_HEADER_NAME` or `HEALTHCHECK_HEADER_USER_AGENT` that matches a value already filtered out of the access log by the application. Most container orchestrations tools either explicitely disable containers' built-in HEALTCHECKs or give you the option to disable able it. A succinct example of this is `docker-compose`'s own [healthcheck](https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck) syntax.
@@ -244,9 +263,8 @@ A: LabKey containers produced from this repo contain a [`HEALTHCHECK` instructio
 - [Sample `pg.properties` file](https://github.com/LabKey/server/blob/develop/server/configs/pg.properties) -- contains some values referenced in application.properties above
 - [LabKey Bootstrap Properties](https://www.labkey.org/Documentation/wiki-page.view?name=bootstrapProperties)
 - [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/)
-- [Compose file v3 Reference](https://docs.docker.com/compose/compose-file/compose-file-v3/)
+- [Compose file Reference](https://docs.docker.com/compose/compose-file/)
 - [`logback` "pattern" Reference](http://logback.qos.ch/manual/layouts.html#conversionWord)
 - [`log4j2` "pattern" Reference](https://logging.apache.org/log4j/log4j-2.0/manual/layouts.html)
 - [`log4j` Migration Reference](https://logging.apache.org/log4j/2.x/manual/migration.html)
 - [How the JVM Finally Plays Nice with Containers](https://www.atamanroman.dev/articles/usecontainersupport-to-the-rescue/)
-- ["how to reduce spring boot memory usage?"](https://stackoverflow.com/a/52993285)
diff --git a/quickstart_envs.sh b/quickstart_envs.sh
@@ -3,7 +3,7 @@
 # example minimal set of environment variables to get started - see readme for additional envs you may wish to set
 
 # embedded tomcat LabKey .jar version to build container with
-export LABKEY_VERSION="23.10.0"
+export LABKEY_VERSION="24.3.4"
 
 # minimal SMTP settings
 export SMTP_HOST="localhost"