Deploying eLabFTW

Introduction

eLabFTW is a free, open-source electronic lab notebook (ELN) designed for research laboratories and scientific institutions. It provides a secure, organized platform for documenting experiments, managing protocols, and maintaining research data integrity. Used by thousands of research groups worldwide, eLabFTW helps scientists maintain good laboratory practices while transitioning from paper notebooks to digital documentation.

Built with PHP and MySQL, eLabFTW offers a modern web interface that researchers can access from any device. The application emphasizes data security and compliance, featuring timestamping, audit trails, and data export capabilities that meet the requirements of regulatory environments and good laboratory practice (GLP) standards.

Key highlights of eLabFTW:

• Electronic Lab Notebook: Document experiments with rich text, images, and file attachments
• Protocol Database: Create and share reusable experimental protocols
• Team Collaboration: Share experiments within teams while maintaining access control
• Timestamping: Cryptographic timestamps prove data integrity and creation dates
• Scheduling: Built-in scheduler for equipment booking and resource management
• API Access: REST API for integration with other laboratory systems
• Data Export: Export data in various formats including PDF, ZIP, and ELN standard format
• Compliance Ready: Audit trails and data integrity features for regulatory compliance
• Multi-language: Available in 20+ languages
• 100% Open Source: AGPL-3.0 licensed with active development

This guide walks through deploying eLabFTW on Klutch.sh, configuring your lab’s electronic notebook, and managing research documentation.

Why Deploy eLabFTW on Klutch.sh

Deploying eLabFTW on Klutch.sh provides several advantages for research laboratories:

Simplified Deployment: Klutch.sh handles infrastructure management, letting you focus on research documentation.

Data Ownership: Keep your research data on infrastructure you control rather than third-party services.

Persistent Storage: Attach volumes for your database and uploaded files that persist securely.

HTTPS by Default: Automatic SSL certificates ensure secure access to sensitive research data.

Scalable Resources: Allocate CPU and memory based on your laboratory size and usage patterns.

Always-On Availability: Your lab notebook remains accessible 24/7 for researchers in different time zones.

Prerequisites

Before deploying eLabFTW on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with PHP applications and MySQL
• SMTP server access for email notifications
• A plan for organizing your laboratory teams and experiments
• (Optional) A custom domain for your institution

Understanding eLabFTW Architecture

eLabFTW uses a traditional LAMP-stack architecture:

PHP Application: The core application handles user authentication, experiment management, and web interface.

MySQL Database: Stores experiments, user data, team structures, and metadata.

File Storage: Uploaded files (images, documents, raw data) are stored on the filesystem.

Redis Cache: Optional caching layer for improved performance.

Timestamping Service: Integration with RFC 3161 timestamping authorities for data integrity.

Preparing Your Repository

Create a GitHub repository with your eLabFTW configuration.

Repository Structure

elabftw-deploy/
├── Dockerfile
├── config/
│   └── elabftw.yml
├── nginx/
│   └── default.conf
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for your eLabFTW deployment:

FROM elabftw/elabimg:latest

# Copy custom configuration if needed
COPY config/ /etc/elabftw/

# Copy nginx configuration
COPY nginx/default.conf /etc/nginx/conf.d/default.conf

# Create necessary directories
RUN mkdir -p /elabftw/uploads /elabftw/cache

# Set permissions
RUN chown -R nginx:nginx /elabftw

# Expose web port
EXPOSE 443

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -fsk https://localhost/login.php || exit 1

# Use default entrypoint from base image

Creating eLabFTW Configuration

Create config/elabftw.yml:

# eLabFTW configuration
# Environment variables override these settings

# Database settings
db_host: ${DB_HOST}
db_name: ${DB_NAME:-elabftw}
db_user: ${DB_USER}
db_password: ${DB_PASSWORD}
db_port: ${DB_PORT:-3306}

# Server settings
server_name: ${SERVER_NAME:-localhost}
disable_https: false
secret_key: ${SECRET_KEY}

# Email settings
mail_method: smtp
smtp_address: ${SMTP_HOST}
smtp_port: ${SMTP_PORT:-587}
smtp_encryption: tls
smtp_username: ${SMTP_USER}
smtp_password: ${SMTP_PASSWORD}

# Storage settings
uploads_folder: /elabftw/uploads

# Security settings
cookie_secure: true

Creating Nginx Configuration

Create nginx/default.conf:

server {
    listen 443 ssl http2;
    server_name _;

    # SSL configuration
    ssl_certificate /etc/nginx/certs/server.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    root /elabftw/web;
    index index.php;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Upload size limit
    client_max_body_size 100M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 300;
    }

    # Deny access to sensitive files
    location ~ /\.ht {
        deny all;
    }

    location ~ /\. {
        deny all;
    }
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying eLabFTW on Klutch.sh

Follow these steps to deploy your eLabFTW instance:

Set Up a MySQL Database

eLabFTW requires MySQL/MariaDB. Set up a database through:

• A managed MySQL service
• A separate Klutch.sh deployment

Note the connection details for environment variables.

Generate a Secret Key

Generate a secure secret key for eLabFTW:

openssl rand -base64 32

Configure Email Settings

Gather your SMTP server details for sending email notifications.

Push Your Repository to GitHub

Initialize and push your configuration:

git init
git add .
git commit -m "Initial eLabFTW configuration"
git remote add origin https://github.com/yourusername/elabftw-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project for your laboratory notebook.

Create a New App

Create a new app within your project and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 443

Set Environment Variables

Configure the following environment variables:

Variable	Value
DB_HOST	Your MySQL host
DB_NAME	elabftw
DB_USER	Your database username
DB_PASSWORD	Your database password
SECRET_KEY	Your generated secret key
SERVER_NAME	your-app.klutch.sh
SMTP_HOST	Your SMTP server
SMTP_PORT	587
SMTP_USER	SMTP username
SMTP_PASSWORD	SMTP password

Attach Persistent Volumes

Add persistent volumes for eLabFTW:

Mount Path	Recommended Size	Purpose
/elabftw/uploads	100 GB	Uploaded files and attachments
/elabftw/cache	5 GB	Application cache

Size uploads volume based on expected data volume.

Deploy Your Application

Click Deploy to build and start eLabFTW.

Complete Installation

Access your eLabFTW instance at https://your-app-name.klutch.sh/install/ to complete the installation wizard.

Create Admin Account

During installation, create the Sysadmin account that will manage your eLabFTW instance.

Initial Setup and Configuration

Completing the Installation

The installation wizard guides you through:

1. Database connection verification
2. Sysadmin account creation
3. Initial configuration settings
4. Email testing

Creating Teams

Organize your laboratory with teams:

1. Log in as Sysadmin
2. Go to Sysadmin Panel
3. Navigate to Teams
4. Create teams for different research groups

Adding Users

Add researchers to your eLabFTW instance:

1. Users can self-register (if enabled)
2. Or Sysadmin can create accounts directly
3. Assign users to appropriate teams
4. Set user permissions (User, Admin, Sysadmin)

Configuring Team Settings

As Team Admin, configure team-specific settings:

1. Default experiment templates
2. Status options for experiments
3. Team visibility settings
4. Shared resources

Managing Experiments

Creating Experiments

Researchers create experiments by:

1. Click “Create” from the experiments view
2. Enter a title and description
3. Use the rich text editor for detailed documentation
4. Attach files, images, and protocols
5. Add tags for organization

Rich Text Editor

eLabFTW provides a full-featured editor:

• Formatting: Bold, italic, headings, lists
• Tables: Data tables with formatting
• Images: Embed images directly in text
• Code: Syntax-highlighted code blocks
• Math: LaTeX equation support

File Attachments

Attach files to experiments:

• Images and figures
• Raw data files
• Analysis scripts
• Supplementary documents

Linking Experiments

Create relationships between experiments:

• Link related experiments
• Reference previous work
• Build experiment chains

Timestamping

Enable cryptographic timestamps:

1. Configure a timestamping authority in settings
2. Timestamp experiments to prove creation date
3. Timestamps are cryptographically verified

Protocol Database

Creating Protocols

Build a library of reusable protocols:

1. Navigate to the Database section
2. Create a new item with category “Protocol”
3. Document the procedure in detail
4. Add required materials and equipment

Using Protocols in Experiments

Reference protocols in experiments:

1. Link protocols to experiments
2. Create experiments from protocol templates
3. Document any deviations from protocols

Sharing Protocols

Share protocols across teams:

1. Set protocol visibility to “Organization”
2. Teams can view and use shared protocols
3. Maintain version history

Scheduling and Resources

Equipment Booking

Use the scheduler for resource management:

1. Define schedulable resources (equipment, rooms)
2. Researchers book time slots
3. View availability calendar
4. Avoid scheduling conflicts

Calendar Integration

Export schedules to external calendars:

1. Subscribe to iCal feeds
2. Sync with Google Calendar or Outlook
3. Get notifications for bookings

Data Export and Compliance

Exporting Experiments

Export data in various formats:

Format	Use Case
PDF	Archival and printing
ZIP	Complete backup with attachments
ELN	Standard electronic notebook format
JSON	Data integration

Compliance Features

eLabFTW supports regulatory compliance:

• Audit Trails: Track all changes to experiments
• Timestamps: Prove data creation dates
• Signatures: Electronic approval workflows
• Data Integrity: Checksums for file verification

Data Retention

Configure data retention policies:

1. Set experiment archival rules
2. Export data for long-term storage
3. Maintain compliance with institutional requirements

API Integration

REST API

eLabFTW provides a comprehensive API:

# Get experiment list
curl -H "Authorization: $API_KEY" \
     https://your-elabftw.klutch.sh/api/v2/experiments

# Create experiment
curl -X POST \
     -H "Authorization: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title": "New Experiment"}' \
     https://your-elabftw.klutch.sh/api/v2/experiments

API Keys

Generate API keys for integration:

1. Go to User Panel > Settings
2. Generate an API key
3. Use the key for authenticated requests

Integration Examples

• LIMS Integration: Sync sample data
• Automation: Create experiments from instruments
• Backup: Automated data export

Production Best Practices

Performance Optimization

• Redis Cache: Enable Redis for improved performance
• File Storage: Use fast SSD storage for uploads
• Database: Optimize MySQL for your workload

Security Recommendations

• Strong Passwords: Enforce password policies
• 2FA: Enable two-factor authentication
• Access Control: Use granular permissions
• Regular Updates: Keep eLabFTW updated

Backup Strategy

Regular backups should include:

1. MySQL database dump
2. Uploads directory
3. Configuration files

Implement a 3-2-1 backup strategy:

• 3 copies of data
• 2 different storage types
• 1 offsite backup

Troubleshooting Common Issues

Cannot Log In

Symptoms: Login fails or redirects.

Solutions:

• Verify database connection
• Check session configuration
• Clear browser cookies
• Review PHP error logs

Uploads Failing

Symptoms: File uploads fail or timeout.

Solutions:

• Check upload directory permissions
• Verify PHP upload limits
• Ensure adequate disk space
• Review nginx client_max_body_size

Email Not Sending

Symptoms: Notifications not received.

Solutions:

• Test SMTP connection
• Verify credentials
• Check firewall rules
• Review email logs

Slow Performance

Symptoms: Pages load slowly.

Solutions:

• Enable Redis caching
• Optimize database queries
• Increase PHP memory limit
• Check server resources

Additional Resources

• eLabFTW Documentation
• eLabFTW GitHub Repository
• eLabFTW Official Website
• eLabFTW API Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying eLabFTW on Klutch.sh gives your research laboratory a professional, secure electronic lab notebook with full data ownership. The combination of eLabFTW’s research-focused features and Klutch.sh’s container management means you can document experiments, manage protocols, and maintain compliance without complex IT infrastructure.

With timestamping for data integrity, comprehensive audit trails, and flexible collaboration features, eLabFTW supports good laboratory practices while making daily research documentation efficient and organized. Whether you’re a small research group or a large institution, eLabFTW on Klutch.sh provides the foundation for modern, digital research documentation.