Configuration#

NexusLIMS-CDCS is configured through environment variables defined in a .env file. This guide documents all available configuration options.

Configuration Files#

File	Purpose
`.env.dev`	Development defaults (tracked in git)
`.env.prod.example`	Production template (tracked in git)
`.env`	Active configuration (gitignored, copy from template)

Setup:

Development: cp .env.dev .env
Production: cp .env.prod.example .env and customize

Warning

Never commit .env to version control - it contains secrets!

Environment Variables Reference#

Project Identification#

Variable	Description	Dev Default	Prod Example
`COMPOSE_PROJECT_NAME`	Docker Compose project name	`nexuslims_dev`	`nexuslims_prod`
`IMAGE_VERSION`	Docker image version tag	`latest`	`3.18.0`

Domain Configuration#

Variable	Description	Dev Default	Prod Example
`DOMAIN`	Main application domain	`nexuslims-dev.localhost`	`nexuslims.example.com`
`FILES_DOMAIN`	File server domain	`files.nexuslims-dev.localhost`	`files.nexuslims.example.com`
`SERVER_URI`	Full server URL (derived)	`https://${DOMAIN}`	`https://${DOMAIN}`
`ALLOWED_HOSTS`	Django allowed hosts	`${DOMAIN}`	`${DOMAIN}`
`CSRF_TRUSTED_ORIGINS`	Django CSRF trusted origins	`https://${DOMAIN}`	`https://${DOMAIN}`

Django Configuration#

Variable	Description	Dev Default	Prod Example
`DJANGO_SETTINGS_MODULE`	Settings module path	`config.settings.dev_settings`	`config.settings.prod_settings`
`DJANGO_SECRET_KEY`	Secret key for crypto operations	(dev key)	Generate unique key!
`DJANGO_DEBUG`	Enable debug mode	`True`	`False`

Generate a secret key:

python3 -c "from secrets import token_urlsafe; print(token_urlsafe(50))"

Database Configuration#

Variable	Description	Dev Default	Prod Example
`POSTGRES_VERSION`	PostgreSQL version	`17`	`17`
`POSTGRES_DB`	Database name	`nexuslims`	`nexuslims`
`POSTGRES_USER`	Database user	`nexuslims`	`nexuslims`
`POSTGRES_PASS`	Database password	(dev password)	Generate unique password!
`POSTGRES_HOST`	Database hostname	`postgres`	`postgres`
`POSTGRES_PORT`	Internal port	`5432`	`5432`
`POSTGRES_HOST_PORT`	Host-exposed port	`5532`	`5532`

Generate a password:

python3 -c "from secrets import token_urlsafe; print(token_urlsafe(32))"

Redis Configuration#

Variable	Description	Dev Default	Prod Example
`REDIS_VERSION`	Redis version	`8`	`8`
`REDIS_PASS`	Redis password	(dev password)	Generate unique password!
`REDIS_HOST`	Redis hostname	`redis`	`redis`
`REDIS_PORT`	Internal port	`6379`	`6379`
`REDIS_HOST_PORT`	Host-exposed port	`6479`	`6479`

Caddy Configuration#

Variable	Description	Dev Default	Prod Example
`CADDYFILE`	Caddyfile to use	`Caddyfile.dev`	`Caddyfile.prod`
`CADDY_ACME_EMAIL`	Email for Let’s Encrypt	-	`admin@example.com`
`CADDY_CERTS_HOST_PATH`	Path to manual certificates	-	`/opt/nexuslims/certs`

File Serving Configuration#

Variable	Description	Dev Default	Prod Example
`NX_DATA_PATH`	Container path for preview data	`/srv/nx-data`	`/srv/nx-data`
`NX_INSTRUMENT_DATA_PATH`	Container path for instrument data	`/srv/nx-instrument-data`	`/srv/nx-instrument-data`
`NX_DATA_HOST_PATH`	Host path for preview data	`./test-data/data`	`/mnt/nexuslims/data`
`NX_INSTRUMENT_DATA_HOST_PATH`	Host path for instrument data	`./test-data/mmf`	`/mnt/nexuslims/instrument-data`

XSLT Configuration#

Variable	Description	Dev Default	Prod Example
`XSLT_DATASET_BASE_URL`	Base URL for instrument data links	`https://files.nexuslims-dev.localhost/instrument-data`	`https://files.nexuslims.example.com/instrument-data`
`XSLT_PREVIEW_BASE_URL`	Base URL for preview image links	`https://files.nexuslims-dev.localhost/data`	`https://files.nexuslims.example.com/data`

These URLs are patched into XSLT stylesheets when they’re uploaded to the database.

Backup Configuration#

Variable	Description	Dev Default	Prod Example
`TZ`	Timezone for backup timestamps	`America/New_York`	`America/New_York`
`NX_CDCS_BACKUPS_HOST_PATH`	Host path for backups	-	`/opt/nexuslims/backups`

Gunicorn Configuration (Production Only)#

Variable	Description	Default	Notes
`GUNICORN_WORKERS`	Number of worker processes	`4`	2-4 × CPU cores
`GUNICORN_THREADS`	Threads per worker	`2`	2-4 typical
`GUNICORN_TIMEOUT`	Request timeout (seconds)	`120`	Increase for long operations

Recommended configurations:

Server Size	Cores	RAM	Workers	Threads
Small	2-4	4-8 GB	4	2
Medium	4-8	8-16 GB	8	2
Large	8+	16+ GB	12	4

Development vs Production#

Key differences between development and production configurations:

Aspect	Development	Production
Debug mode	Enabled (`True`)	Disabled (`False`)
Web server	Django runserver	Gunicorn
Certificates	Local CA (self-signed)	Let’s Encrypt (ACME)
Domains	`.localhost`	Real domains
File paths	Test data directory	Network storage mounts
Passwords	Simple defaults	Strong generated passwords
Code mounting	Yes (hot reload)	No (built into image)

XSLT URL Configuration#

XSLT stylesheets contain URLs for linking to instrument data and preview images. These URLs must match your deployment:

        %%{init: {'theme': 'base'}}%%
flowchart LR
    subgraph XSLT["XSLT Stylesheet"]
        DatasetURL["datasetBaseUrl"]
        PreviewURL["previewBaseUrl"]
    end

    subgraph ENV["Environment Variables"]
        XSLT_DATASET_BASE_URL
        XSLT_PREVIEW_BASE_URL
    end

    subgraph Caddy["Caddy File Server"]
        InstrumentData["/instrument-data/"]
        PreviewData["/data/"]
    end

    XSLT_DATASET_BASE_URL --> DatasetURL
    XSLT_PREVIEW_BASE_URL --> PreviewURL
    DatasetURL -->|links to| InstrumentData
    PreviewURL -->|links to| PreviewData

Update Process#

When you run dev-update-xslt or admin-init, the scripts:

Read the XSL file from xslt/
Replace placeholder URLs with values from environment variables
Upload the patched stylesheet to the database

Manual URL Patching#

If you need to update URLs manually:

# Inside CDCS container
python manage.py shell

from core_main_app.components.xsl_transformation.models import XslTransformation

# Get stylesheet
xslt = XslTransformation.objects.get(name="detail_stylesheet.xsl")

# Update content
xslt.content = xslt.content.replace(
    "https://old-url.com/data",
    "https://new-url.com/data"
)
xslt.save()

Optional Integrations#

SAML2 Authentication#

SAML2 configuration is stored in deployment/saml2/.env. Consult the MDCS documentation for SAML2 setup.

Handle System#

Handle system configuration is stored in deployment/handle/.env. This enables persistent identifiers for records.

Custom Settings#

For advanced customization, create a custom settings module:

Create config/settings/custom_settings.py
Import from prod_settings.py and override as needed
Set DJANGO_SETTINGS_MODULE=config.settings.custom_settings

Troubleshooting Configuration#

Environment Not Loading#

Verify .env file exists and is readable:

ls -la .env
cat .env | head -20

Variables Not Applied#

Docker Compose caches environment. Force reload:

dc-prod down
dc-prod up -d

XSLT URLs Not Updating#

XSLT stylesheets must be re-uploaded after changing URL variables:

dev-update-xslt  # Development
# or
admin-init       # Production (re-runs full initialization)

Secret Key Errors#

If Django complains about the secret key:

Ensure DJANGO_SECRET_KEY is set
Key must be at least 50 characters
Don’t use special characters that need escaping

Next Steps#

Production Deployment - Apply configuration for production deployment
Administration - Manage backups and updates
Development Setup - Set up local development environment