LabID Settings Configuration

This guide explains how to configure your LabID instance for production use and advanced customization. For initial installation configuration, see the Installation Configuration guide.

Installation vs. Administration Configuration

• Installation Configuration: Essential settings needed during initial deployment
• This guide: Comprehensive configuration management for running instances

Configuration Approach

LabID uses Django with django-environ for flexible configuration management. Settings can be managed through multiple approaches:

1. Environment variables - Directly set in your system environment, using the export command as below.
2. .env file - Edit the .env file in the /opt/labid/labid file.
3. Custom settings files - Create specialized Python settings files for complex configurations

Almost all configuration options defined in settings/base.py can be overridden using environment variables prefixed with DJANGO_.

Environment Variables Configuration

Shown below are the commands to type in a terminal to define environment variables.
If using the .env approach, then the export is not required i.e the line should start with DJANGO_.

Basic Configuration Examples

# Core settings
export DJANGO_SECRET_KEY="your-secret-key-here"
export DJANGO_DEBUG=False
export DJANGO_DATABASE_URL="postgresql://user:password@localhost:5432/labid"
export DJANGO_ALLOWED_HOST="localhost,yourdomain.com"

# Organization
export DJANGO_ORGANIZATION="name of your organization"
export DJANGO_ORGANIZATION_ROR=https://ror.org/123456 # optional, see ror.org to find your org ror

# Email configuration
export DJANGO_EMAIL_HOST="smtp.yourdomain.com"
export DJANGO_EMAIL_HOST_USER="your-email@example.com"
export DJANGO_EMAIL_HOST_PASSWORD="your-email-password"
export DJANGO_EMAIL_PORT=587
export DJANGO_EMAIL_USE_TLS=True
export DJANGO_EMAIL_SENDER="labid@yourdomain.com"
export DJANGO_EMAIL_ADMIN="admin@yourdomain.com"
export DJANGO_EMAIL_STORES="stores@yourdomain.com" # Recipient of the "order" form
export DJANGO_ARCHIVE_SERVICE_EMAIL="archive@yourdomain.com" # Recipient of notifications related to file archiving 

Data Type Handling

The configuration system automatically handles different data types:

# Boolean values
export DJANGO_DEBUG=True
export DJANGO_EMAIL_NOTIFICATIONS=False

# Integer values  
export DJANGO_MAX_UPLOAD_SIZE=104857600

# List values (comma-separated)
export DJANGO_ALLOWED_HOST="localhost,127.0.0.1,yourdomain.com"

# JSON values (for complex configurations)
export DJANGO_GALAXY_ENDPOINTS='{
  "https://usegalaxy.eu": {
    "url": "https://usegalaxy.eu",
    "label": "Galaxy Europe",
    "is_default": false,
    "data_library_sync": false,
    "import_workflows": true
  }
}'

.env File Configuration

For centralized configuration management, create a .env file in your LabID project root. This approach is recommended for production deployments.

Production .env Example

# Core Django settings
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=False
DJANGO_DATABASE_URL=postgresql://labid_user:password@localhost:5432/labid_prod
DJANGO_ALLOWED_HOST=labid.yourdomain.com

# Organization
DJANGO_ORGANIZATION="name of your organization"
DJANGO_ORGANIZATION_ROR=https://ror.org/123456 # optional, see ror.org to find your org ror

# Email configuration
DJANGO_EMAIL_HOST=smtp.yourdomain.com
DJANGO_EMAIL_SENDER=labid@yourdomain.com
DJANGO_EMAIL_ADMIN=admin@yourdomain.com
DJANGO_EMAIL_STORES=stores@yourdomain.com
DJANGO_ARCHIVE_SERVICE_EMAIL=archive@yourdomain.com
DJANGO_EMAIL_NOTIFICATIONS=True

# Storage configuration
DJANGO_MEDIA_ROOT=/var/lib/labid/storage
DJANGO_STATIC_ROOT=/var/lib/labid/static
DJANGO_MAX_UPLOAD_SIZE=104857600

# Galaxy integration
DJANGO_GALAXY_URL=https://usegalaxy.eu
DJANGO_GALAXY_ADMIN_API_KEY=your-galaxy-api-key

# WorkflowHub configuration  
DJANGO_DEFAULT_WORKFLOWHUB=https://workflowhub.eu

Development .env Example

# Development settings
DJANGO_SECRET_KEY=dev-secret-key-not-for-production
DJANGO_DEBUG=True
DJANGO_DATABASE_URL=postgresql://labid:labid@localhost:5432/labid_dev
DJANGO_ALLOWED_HOST=localhost,127.0.0.1

# Organization
DJANGO_ORGANIZATION="name of your organization"
DJANGO_ORGANIZATION_ROR=https://ror.org/123456 # optional, see ror.org to find your org ror

# Development email (console backend)
DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
DJANGO_EMAIL_ADMIN=dev@localhost
DJANGO_EMAIL_STORES=dev@localhost
DJANGO_ARCHIVE_SERVICE_EMAIL=dev@localhost

# Development storage
DJANGO_MEDIA_ROOT=./media/
DJANGO_STATIC_ROOT=./static/

# Optional development features
DJANGO_ALLOW_FILE_REMOVAL=True

Security Best Practices

• Never commit .env files to version control - Add .env* to your .gitignore
• Use different .env files for different environments (.env.dev, .env.prod)
• Restrict file permissions: chmod 600 .env
• Use strong, unique secret keys for each environment
• Regularly rotate API keys and passwords

Complex JSON Configurations

Some advanced features require JSON configuration:

Workflow Repository Configuration

export DJANGO_DEFAULT_PUBLIC_WORKFLOWREPOSITORIES='{
  "https://workflowhub.eu": {
    "label": "WorkflowHub",
    "url": "https://workflowhub.eu", 
    "api_url": "https://workflowhub.eu",
    "trs": {
      "info": "https://workflowhub.eu/ga4gh/trs/v2/service-info",
      "search": "https://workflowhub.eu/ga4gh/trs/v2/tools"
    }
  },
  "https://dockstore.org": {
    "label": "Dockstore",
    "url": "https://dockstore.org",
    "api_url": "https://dockstore.org/api",
    "trs": {
      "info": "https://dockstore.org/api/ga4gh/trs/v2/service-info", 
      "search": "https://dockstore.org/api/ga4gh/trs/v2/tools"
    }
  }
}'

Galaxy Endpoints Configuration

Configure Galaxy instances for workflow integration. Each endpoint requires a detailed configuration object:

export DJANGO_GALAXY_ENDPOINTS='{
  "https://usegalaxy.eu": {
    "url": "https://usegalaxy.eu",
    "label": "Galaxy Europe",
    "is_default": false,
    "data_library_sync": false,
    "import_workflows": true
  },
  "https://usegalaxy.org": {
    "url": "https://usegalaxy.org",
    "label": "Galaxy Main",
    "is_default": false,
    "data_library_sync": false,
    "import_workflows": true
  },
  "https://usegalaxy.org.au": {
    "url": "https://usegalaxy.org.au",
    "label": "Galaxy Australia",
    "is_default": false,
    "data_library_sync": false,
    "import_workflows": true
  }
}'

Configuration Properties:

• url: Galaxy instance URL
• label: Human-readable name for the instance
• is_default: Whether this is the default Galaxy instance (only one should be true)
• data_library_sync: Enable data library synchronization
• import_workflows: Allow workflow import from this instance

Custom Settings Files

For complex deployments, create custom settings files that extend the base configuration.

Production Settings Example

Create settings/production.py:

from .base import *
import os

# Production security settings
DEBUG = False
ALLOWED_HOSTS = [os.environ.get('DOMAIN_NAME', 'labid.yourdomain.com')]

# Production database with connection pooling
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME', 'labid_prod'),
        'USER': os.environ.get('DB_USER', 'labid'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST', 'localhost'),
        'PORT': os.environ.get('DB_PORT', '5432'),
        'OPTIONS': {
            'MAX_CONNS': 20,
            'OPTIONS': {
                'MAX_CONNS': 20,
            }
        }
    }
}

# Production logging
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/labid/labid.log',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

# Production static files
STATIC_ROOT = '/var/www/labid/static/'
MEDIA_ROOT = '/var/lib/labid/media/'

# Production cache
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}

# Security enhancements
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'

Development Settings Example

Create settings/development.py:

from .base import *

# Development overrides
DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1', '0.0.0.0']

# Development database
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# Development email (console output)
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# Development plugins
ENABLED_PLUGINS = ENABLED_PLUGINS + ['plugins.development', 'debug_toolbar']

# Development middleware
MIDDLEWARE = ['debug_toolbar.middleware.DebugToolbarMiddleware'] + MIDDLEWARE

# Debug toolbar settings
INTERNAL_IPS = ['127.0.0.1']

Using Custom Settings Files

Specify your settings module:

# For production
export DJANGO_SETTINGS_MODULE=labid_server.settings.production
python manage.py migrate
python manage.py collectstatic

# For development
export DJANGO_SETTINGS_MODULE=labid_server.settings.development
python manage.py runserver

Configuration Categories

Core System Configuration

Setting	Environment Variable	Default	Description
Debug Mode	DJANGO_DEBUG	False	Enable debug mode
Secret Key	DJANGO_SECRET_KEY	Required	Django secret key
Allowed Hosts	DJANGO_ALLOWED_HOST	localhost	Comma-separated hostnames
Database	DJANGO_DATABASE_URL	SQLite	Database connection URL

Email Configuration

Setting	Environment Variable	Description
SMTP Host	DJANGO_EMAIL_HOST	Email server hostname
SMTP Port	DJANGO_EMAIL_PORT	Email server port (default: 587)
Email User	DJANGO_EMAIL_HOST_USER	SMTP authentication username
Email Password	DJANGO_EMAIL_HOST_PASSWORD	SMTP authentication password
From Address	DJANGO_EMAIL_SENDER	Default sender address
Admin Email	DJANGO_EMAIL_ADMIN	Administrator email address

For detailed email configuration, see Email Configuration.

Storage Configuration

Setting	Environment Variable	Description
Media Root	DJANGO_MEDIA_ROOT	Path for uploaded files
Static Root	DJANGO_STATIC_ROOT	Path for static files
Max Upload Size	DJANGO_MAX_UPLOAD_SIZE	Maximum file upload size (bytes)

For detailed storage configuration, see Storage Configuration.

Integration Configuration

• Workflow Configuration - Galaxy, WorkflowHub, and workflow repository settings
• Authentication Configuration - SSO, LDAP, and authentication backends
• SSH Keys Configuration - SSH key management for remote access

Troubleshooting

Common Configuration Issues

1. Settings not taking effect
2. Ensure environment variables are exported: echo $DJANGO_DEBUG
3. Restart the application after changes

4. Check for typos in variable names

5. JSON parsing errors

6. Validate JSON syntax using online validators
7. Escape quotes properly in shell environments

8. Use single quotes around JSON strings in bash

9. Database connection errors

10. Verify database URL format: postgresql://user:pass@host:port/dbname
11. Test database connectivity independently

12. Check firewall and network settings

13. Permission issues

14. Verify file permissions: ls -la .env
15. Ensure application user can read configuration files

16. Check directory permissions for media/static paths

17. Email not working

18. Test SMTP connectivity: telnet smtp.server.com 587
19. Verify authentication credentials
20. Check spam/junk folders

Debugging Configuration

Check current configuration values:

# Django shell
python manage.py shell

>>> from django.conf import settings
>>> print(f"Debug: {settings.DEBUG}")
>>> print(f"Database: {settings.DATABASES}")
>>> print(f"Allowed Hosts: {settings.ALLOWED_HOSTS}")

View environment variables:

# Show all Django variables
env | grep DJANGO_

# Check specific setting
echo $DJANGO_SECRET_KEY

Configuration Validation

Create a management command to validate configuration:

# management/commands/check_config.py
from django.core.management.base import BaseCommand
from django.conf import settings

class Command(BaseCommand):
    def handle(self, *args, **options):
        self.stdout.write("Configuration Check:")
        self.stdout.write(f"DEBUG: {settings.DEBUG}")
        self.stdout.write(f"DATABASE: {settings.DATABASES['default']['ENGINE']}")
        # Add more checks as needed

Related Documentation

• Installation Configuration - Initial setup and deployment configuration
• Workflow Configuration - Galaxy and workflow repository integration
• Email Configuration - Email server and notification settings
• Storage Configuration - File storage and upload settings
• Authentication Configuration - User authentication and SSO
• SSH Keys Configuration - SSH key management

Migration from Installation

If you started with basic installation configuration and need to migrate to advanced settings:

1. Review current .env file in your installation
2. Add missing production settings from the examples above
3. Consider custom settings files for complex deployments
4. Test configuration changes in a staging environment first
5. Update deployment scripts to use new settings module if needed