Administration#

This guide covers day-to-day administration tasks for NexusLIMS-CDCS including backups, XSLT management, user administration, and monitoring.

Admin Commands Overview#

Load admin commands before running any administrative task:

cd /path/to/NexusLIMS-CDCS/deployment
source admin-commands.sh

Command Summary#

Command	Description
`dc-prod`	Docker Compose alias for production stack
`admin-backup`	Backup all CDCS data
`admin-restore <dir>`	Restore from backup directory
`admin-db-dump`	Create PostgreSQL database dump
`admin-db-restore <file>`	Restore database from dump
`admin-list-users`	List all users with status
`admin-export-users`	Export users to JSON
`admin-import-users <file>`	Import users from JSON
`admin-stats`	Show system statistics
`admin-init`	Initialize environment (superuser, schema, XSLT)

Backup and Restore#

Understanding Backup Types#

NexusLIMS-CDCS supports two backup approaches:

Type	Command	Use Case
Application Backup	`admin-backup`	Regular backups, includes all data
Database Dump	`admin-db-dump`	Disaster recovery, PostgreSQL raw dump

Recommendation: Use admin-backup for regular backups. Use admin-db-dump only for disaster recovery scenarios.

Application Backup#

Application backups include:

Templates (XSD schemas)
Data records (XML documents)
Binary blobs (uploaded files)
Users (Django fixtures)
XSLT stylesheets
Persistent queries

source admin-commands.sh
admin-backup

Output:

→ Starting CDCS backup...
→ Exporting templates...
✓ Exported 1 templates to /srv/nexuslims/backups/backup_20260115_143022/templates/
→ Exporting records...
✓ Exported 42 records to /srv/nexuslims/backups/backup_20260115_143022/records/
→ Exporting blobs...
✓ Exported 128 blobs to /srv/nexuslims/backups/backup_20260115_143022/blobs/
→ Exporting users...
✓ Exported 5 users to /srv/nexuslims/backups/backup_20260115_143022/users.json
→ Exporting XSLT...
✓ Exported 2 stylesheets to /srv/nexuslims/backups/backup_20260115_143022/xslt/
✓ Backup completed: /srv/nexuslims/backups/backup_20260115_143022/

Backups are stored at the path configured in NX_CDCS_BACKUPS_HOST_PATH (default: /opt/nexuslims/backups/).

Restoring from Backup#

source admin-commands.sh
admin-restore /opt/nexuslims/backups/backup_20260115_143022

The restore command:

Imports templates
Imports records
Imports blobs
Imports users
Imports XSLT stylesheets

Database Dump (Disaster Recovery)#

For complete disaster recovery, create a PostgreSQL dump:

source admin-commands.sh
admin-db-dump

Creates a SQL file at $NX_CDCS_BACKUPS_HOST_PATH/db_backup_YYYYMMDD_HHMMSS.sql

Database Restore (Disaster Recovery)#

Warning

Database restore will DROP and RECREATE the entire database. All existing data will be lost!

source admin-commands.sh
admin-db-restore /opt/nexuslims/backups/db_backup_20260115_143022.sql

The command requires two confirmations before proceeding.

Automated Backup Schedule#

Set up a cron job for automated backups:

# Create backup script
cat > /opt/nexuslims-backup.sh << 'EOF'
#!/bin/bash
set -e
cd /opt/nexuslims/NexusLIMS-CDCS/deployment
source admin-commands.sh
admin-backup
admin-db-dump

# Cleanup old backups (30 days)
find /opt/nexuslims/backups -type d -name "backup_*" -mtime +30 -exec rm -rf {} \; 2>/dev/null || true
find /opt/nexuslims/backups -type f -name "db_backup_*.sql" -mtime +30 -delete 2>/dev/null || true
EOF

chmod +x /opt/nexuslims-backup.sh

# Add to crontab (daily at 2 AM)
(crontab -l 2>/dev/null; echo "0 2 * * * /opt/nexuslims-backup.sh") | crontab -

XSLT Stylesheet Management#

Important

XSLT stylesheets are stored in the Django database. Editing the .xsl files alone is not enough - you must update the database.

XSLT Files#

File	Purpose
`xslt/detail_stylesheet.xsl`	Full record view (single record page)
`xslt/list_stylesheet.xsl`	Search result cards (list view)

Update Process#

Edit the XSL file in the xslt/ directory
Update the database:

Development:

source dev-commands.sh
dev-update-xslt

Production:

# Re-run initialization (uploads XSLT along with schema)
docker exec -it nexuslims_prod_cdcs python /srv/scripts/init_environment.py

Or use the update script directly:

docker exec nexuslims_prod_cdcs bash /srv/scripts/update-xslt.sh

URL Patching#

XSLT stylesheets contain URLs for linking to instrument data and preview images. These are automatically patched from environment variables:

XSLT_DATASET_BASE_URL → links to instrument data files
XSLT_PREVIEW_BASE_URL → links to preview images

See Configuration for details.

Verifying XSLT Updates#

After updating, verify in the web interface:

Navigate to any record
Check that links to data files and images work correctly
Inspect the HTML source to confirm URLs are correct

Schema Management#

Schema File Location#

The NexusLIMS schema (nexus-experiment.xsd) is located at:

Repository: deployment/schemas/nexus-experiment.xsd
Container: /srv/nexuslims/schemas/nexus-experiment.xsd

Updating the Schema#

Download latest schema from the NexusLIMS repository:
```
cd deployment
bash scripts/update-schema.sh
```

Apply to database by re-running initialization:

docker exec -it nexuslims_prod_cdcs python /srv/scripts/init_environment.py

Note

Schema updates create a new template version. Existing records remain valid against their original template version.

User Management#

List Users#

source admin-commands.sh
admin-list-users

Output:

admin (admin@example.com) - Active: True, Admin: True
jsmith (jane.smith@example.com) - Active: True, Admin: False

Export Users#

Export all users to JSON for backup or migration:

admin-export-users
# Creates: /opt/nexuslims/backups/users_YYYYMMDD_HHMMSS.json

Import Users#

Import users from a JSON fixture:

admin-import-users /opt/nexuslims/backups/users_20260115_143022.json

Create Superuser#

To create an additional superuser:

docker exec -it nexuslims_prod_cdcs python manage.py createsuperuser

Reset User Password#

docker exec -it nexuslims_prod_cdcs python manage.py changepassword username

Monitoring#

System Statistics#

source admin-commands.sh
admin-stats

Output:

============================================================
NexusLIMS-CDCS System Statistics
============================================================

Users:
  Total:      5
  Active:     5
  Superusers: 1

Templates:
  Total: 1
    - Nexus Experiment Schema (Version 1)

Data Records:
  Total: 42

XSLT Stylesheets:
  Total: 2
    - detail_stylesheet.xsl
    - list_stylesheet.xsl

============================================================

Container Health#

dc-prod ps

All services should show Up and healthy.

View Logs#

# All services
dc-prod logs -f

# Specific service
dc-prod logs -f cdcs
dc-prod logs -f postgres
dc-prod logs -f caddy

Resource Usage#

docker stats

Database Queries#

For advanced troubleshooting, access the PostgreSQL shell:

docker exec -it nexuslims_prod_cdcs_postgres psql -U nexuslims nexuslims

Example queries:

-- Active connections
SELECT pid, query, state FROM pg_stat_activity WHERE state != 'idle';

-- Table sizes
SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Vacuum stats
SELECT relname, last_vacuum, last_analyze FROM pg_stat_user_tables;

Maintenance Tasks#

Clear Expired Sessions#

docker exec nexuslims_prod_cdcs python manage.py clearsessions

Clear Redis Cache#

docker exec nexuslims_prod_cdcs_redis redis-cli -a $REDIS_PASS FLUSHDB

Optimize Database#

docker exec nexuslims_prod_cdcs_postgres vacuumdb -U nexuslims --all --full --analyze

Restart Services#

source admin-commands.sh
dc-prod restart

Or restart specific services:

dc-prod restart cdcs
dc-prod restart caddy

Service Management#

Start/Stop Services#

source admin-commands.sh

# Stop all services
dc-prod down

# Start all services
dc-prod up -d

# Stop specific service
dc-prod stop cdcs

# Start specific service
dc-prod start cdcs

Update Images#

Pull latest images and restart:

dc-prod pull
dc-prod up -d

View Configuration#

Verify the resolved Docker Compose configuration:

dc-prod config

Next Steps#

Troubleshooting - Common issues and solutions
Production Deployment - Production deployment guide
Configuration - Environment variable reference

Administration#

Admin Commands Overview#

Command Summary#

Backup and Restore#

Understanding Backup Types#

Application Backup#

Restoring from Backup#

Database Dump (Disaster Recovery)#

Database Restore (Disaster Recovery)#

Automated Backup Schedule#

XSLT Stylesheet Management#

XSLT Files#

Update Process#

URL Patching#

Verifying XSLT Updates#

Schema Management#

Schema File Location#

Updating the Schema#

User Management#

List Users#

Export Users#

Import Users#

Create Superuser#

Reset User Password#

Monitoring#

System Statistics#

Container Health#

View Logs#

Resource Usage#

Database Queries#

Maintenance Tasks#

Clear Expired Sessions#

Clear Redis Cache#

Optimize Database#

Restart Services#

Service Management#

Start/Stop Services#

Update Images#

View Configuration#

Next Steps#

This Page