You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## What This Repo Does
6
+
7
+
Builds and publishes Docker images for LabKey Server (a biomedical data management platform) to AWS ECR. A single `Dockerfile` produces multiple distributions (`community`, `enterprise`, `lims_starter`, `allpg`) via the `LABKEY_DISTRIBUTION` build arg.
8
+
9
+
## Common Commands
10
+
11
+
```bash
12
+
# Local development cycle
13
+
make build # Build image locally (uses local .jar if present)
14
+
make up # Run community via docker-compose (https://localhost:8443)
15
+
make up-enterprise # Run enterprise distribution
16
+
make up-lims_starter
17
+
make down # Tear down containers
18
+
make test# Run smoke.bash health check against running container
19
+
20
+
# Lint
21
+
# Hadolint runs in CI; run locally via:
22
+
docker run --rm -i hadolint/hadolint < Dockerfile
23
+
24
+
# AWS ECR workflow
25
+
make login # Authenticate to ECR
26
+
make tag # Tag image for ECR
27
+
make push # Push to ECR
28
+
make all # login → build → tag → push (default)
29
+
```
30
+
31
+
## Architecture
32
+
33
+
### Build Flow
34
+
35
+
`Dockerfile` downloads the LabKey `.tar.gz` from a URL (or uses a local `.jar` file placed in the repo root for development). The `LABKEY_VERSION` and `LABKEY_DISTRIBUTION` build args control which artifact is fetched. Base image is `eclipse-temurin:25-jre-noble` (Debian); Alpine variant is also supported.
2. Optionally downloads startup properties from S3
42
+
3. Handles SSM vs. non-AWS mode: if `LABKEY_SSM_PREFIX` is set, normalizes trailing slashes on both prefix vars; otherwise removes the `context.awsParameterStore.prefix` line and substitutes `ssm:` references in `application.properties` with direct env var values
43
+
4. Runs `envsubst` on all `.properties` files, then `sed` to substitute `@@placeholder@@` values
44
+
5. Generates a self-signed TLS keystore via `openssl`
45
+
6. Unsets connection/SMTP env vars, then `exec`s `java -jar labkeyServer.jar`
46
+
47
+
### Multi-Distribution
48
+
49
+
The `startup/` directory contains per-distribution `.properties` files (`community.properties`, `enterprise.properties`, etc.). The `LABKEY_DISTRIBUTION` env var selects which file is copied in at build time and passed to the JVM.
50
+
51
+
### Configuration Surface
52
+
53
+
Almost all runtime behavior is controlled via environment variables. The major groups are documented in `README.md`:
54
+
-**DB**: `POSTGRES_*` — connection, pooling
55
+
-**App**: `LABKEY_*` — version, distribution, base URL, encryption key, initial user
56
+
-**SSM (AWS, 26.6+)**: `LABKEY_SSM_PREFIX` (app-level prefix) and `LABKEY_VPC_SSM_PREFIX` (VPC-level prefix) — when set, DB credentials (`database_user`, `database_password`), encryption key (`ek`), and SMTP credentials (`smtp_user`, `smtp_password`) are fetched from SSM instead of env vars; see `application.properties` for the `ssm:` references and `README.md` for the full SSM parameter table
Feature branches follow the pattern `fb_<description>` or `<version>_fb_<description>`.
73
+
74
+
### Local JAR Development
75
+
76
+
Place a `labkeyServer.jar.*` file in the repo root (already gitignored). The `Makefile` detects it and uses it as the build artifact instead of downloading from a remote URL, enabling local iteration without publishing.
| LABKEY_EK | LabKey [encryption key](https://www.labkey.org/Documentation/wiki-page.view?name=cpasxml#encrypt); not needed when using AWS SSM integration (see below)|`123abc456`|
191
191
| LABKEY_PORT | port to which labkey will bind within the container |`8443`|
192
192
| LABKEY_SYSTEM_DESCRIPTION | brief description of server; appears in emails |`Sirius Cybernetics`|
193
193
| LABKEY_SYSTEM_EMAIL_ADDRESS | email address system email will be sent "from"|`do_not_reply@localhost`|
@@ -216,6 +216,8 @@ Initial user API key creation was implemented in LabKey Server 20.11.
216
216
217
217
The `POSTGRES_*` default values are meant to match those of the [library/postgres](https://hub.docker.com/_/postgres) containers.
218
218
219
+
`POSTGRES_USER` and `POSTGRES_PASSWORD` are not needed when using AWS SSM integration (see below).
@@ -239,6 +243,33 @@ These replace values previously housed in `context.xml` (`ROOT.xml` or `labkey.x
239
243
| SMTP_AUTH | SMTP Auth flag | `false` |
240
244
| SMTP_STARTTLS | SMTP STARTTLS flag | `<empty>` |
241
245
246
+
## AWS SSM Integration (LabKey 26.6+)
247
+
248
+
For AWS deployments on LabKey 26.6+, DB credentials, the encryption key, and SMTP credentials can be resolved directly from AWS SSM Parameter Store by the JVM at startup, rather than being injected as container env vars. This uses LabKey's `AwsParameterStoreEnvironmentPostProcessor`.
249
+
250
+
Set two path-prefix env vars and create the corresponding SSM parameters:
When `LABKEY_SSM_PREFIX` is set, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `LABKEY_EK`, `SMTP_USER`, and `SMTP_PASSWORD` env vars are not used. When `LABKEY_SSM_PREFIX` is unset (local / non-AWS), the container falls back to those env vars as before.
270
+
271
+
In ECS, the container task role provides credentials via IMDS — no AWS credential env vars needed. For local testing with SSM, export`AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` (or use aws-vault) so the JVM can reach SSM.
272
+
242
273
## SSL/Keystore/Self-signed Cert
243
274
244
275
The `CERT_*` ENVs should look familiar to anyone that has used the `openssl`command to generate a pkcs12 keystore.
0 commit comments