Deploying ESMira

Introduction

ESMira is an open-source mobile experience sampling method (ESM) platform designed for researchers conducting psychological studies, health monitoring, and behavioral research through smartphones. Developed for academic and clinical research, ESMira enables researchers to create mobile questionnaires, schedule data collection events, track participant compliance, and gather real-time data about behaviors, emotions, and experiences in participants’ natural environments.

Experience sampling methodology (ESM), also known as ecological momentary assessment (EMA), involves collecting data from participants multiple times throughout their day in real-world settings. This approach minimizes recall bias and provides rich temporal data about psychological states, behaviors, and environmental contexts that would be impossible to capture through traditional surveys or lab studies.

ESMira excels at:

Mobile-First Questionnaires: Design and deploy smartphone questionnaires with various question types including Likert scales, multiple choice, text input, photo capture, and audio recording
Flexible Scheduling: Configure random, fixed-time, or event-triggered data collection schedules tailored to research protocols
Multi-Platform Support: Native mobile apps for both Android and iOS, ensuring broad participant accessibility
Participant Management: Track enrollment, compliance rates, study progress, and send personalized notifications
Data Collection: Capture questionnaire responses, sensor data (accelerometer, GPS), app usage, and physiological measurements
Real-Time Monitoring: View participant responses and compliance dashboards as data arrives, enabling adaptive interventions
Privacy-Focused: GDPR-compliant data handling with pseudonymization, encryption, and participant consent management
Study Configuration: Web-based admin interface for creating studies, designing questionnaires, and managing participants
Data Export: Export collected data in CSV, JSON, or SPSS formats for statistical analysis
Multilingual Support: Create questionnaires in multiple languages for international research projects
Offline Capability: Mobile apps cache questionnaires and sync data when connectivity returns, ensuring no data loss
Customizable Logic: Implement branching logic, skip patterns, and conditional questions based on participant responses

ESMira is particularly valuable for research in clinical psychology (depression tracking, anxiety monitoring), health behaviors (medication adherence, diet logging), social psychology (mood fluctuations, social interactions), and behavioral intervention studies. The platform supports both intensive longitudinal studies with frequent assessments and longer-term cohort studies with periodic check-ins.

This comprehensive guide walks you through deploying ESMira on Klutch.sh using Docker, connecting to a MySQL database, configuring persistent storage for study data, and setting up production-ready research platforms that meet institutional review board (IRB) requirements and data protection standards.

Why Deploy ESMira on Klutch.sh

Deploying ESMira on Klutch.sh provides several advantages for research teams:

Automated Docker Detection: Klutch.sh automatically detects your Dockerfile and builds your ESMira container with PHP, Apache, and database drivers pre-configured
Persistent Volume Support: Attach persistent storage for ESMira’s data directory, ensuring participant responses, study configurations, and uploaded media survive container restarts
Database Connectivity: Connect to MySQL/MariaDB instances deployed on Klutch.sh or external managed databases, with environment variables for secure credential management
HTTPS by Default: All ESMira deployments get automatic HTTPS encryption, essential for protecting sensitive participant data and meeting research ethics requirements
Scalable Architecture: Handle studies with hundreds of participants and thousands of daily responses without infrastructure management
Zero-Downtime Deployments: Update ESMira versions or configurations without disrupting active studies or losing participant data
Environment Variables: Securely manage database credentials, API keys, and study-specific settings without hardcoding sensitive information
Built-in Monitoring: Track application performance, response times, and error rates to ensure study reliability
Cost-Effective Hosting: Pay only for resources used, making it affordable for academic research budgets
Rapid Deployment: Get ESMira running in minutes, allowing researchers to focus on study design rather than infrastructure setup

Prerequisites

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

A Klutch.sh account
A GitHub repository for your ESMira deployment configuration
A MySQL or MariaDB database (can be deployed on Klutch.sh - see our MySQL deployment guide)
Basic understanding of research study design and ESM methodology
Institutional review board (IRB) approval for your research study

Understanding ESMira Architecture

ESMira consists of several interconnected components:

Web Application: PHP-based admin interface for creating studies, designing questionnaires, and managing participants
API Server: RESTful API that mobile apps communicate with to fetch questionnaires and submit responses
Database: MySQL/MariaDB database storing study configurations, participant data, questionnaire responses, and media files
Mobile Apps: Native Android and iOS applications that participants install to complete questionnaires and share sensor data
Admin Dashboard: Web interface for researchers to monitor compliance, export data, and manage study settings

When deployed on Klutch.sh, ESMira automatically detects your Dockerfile and builds a container that includes PHP, Apache web server, and all necessary dependencies. The platform manages SSL certificates, traffic routing, and provides persistent storage for your research data.

Preparing Your Repository

Create the Dockerfile

Create a Dockerfile in your repository root with the following content:

FROM php:8.1-apache

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip \
    git \
    curl \
    default-mysql-client \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
    pdo \
    pdo_mysql \
    mysqli \
    zip \
    gd \
    mbstring \
    xml \
    exif \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www/html

# Clone ESMira repository
RUN git clone https://github.com/KL-Psychological-Methodology/ESMira.git . \
    && chown -R www-data:www-data /var/www/html

# Install PHP dependencies
RUN composer install --no-dev --optimize-autoloader

# Enable Apache modules
RUN a2enmod rewrite headers

# Configure Apache for ESMira
RUN echo '<Directory /var/www/html>' > /etc/apache2/conf-available/esmira.conf \
    && echo '    Options Indexes FollowSymLinks' >> /etc/apache2/conf-available/esmira.conf \
    && echo '    AllowOverride All' >> /etc/apache2/conf-available/esmira.conf \
    && echo '    Require all granted' >> /etc/apache2/conf-available/esmira.conf \
    && echo '</Directory>' >> /etc/apache2/conf-available/esmira.conf \
    && a2enconf esmira

# Create necessary directories with proper permissions
RUN mkdir -p /var/www/html/uploads /var/www/html/data /var/www/html/logs \
    && chown -R www-data:www-data /var/www/html/uploads /var/www/html/data /var/www/html/logs \
    && chmod -R 755 /var/www/html/uploads /var/www/html/data /var/www/html/logs

# Copy entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

EXPOSE 80

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["apache2-foreground"]

Create the Entrypoint Script

Create docker-entrypoint.sh in your repository root:

#!/bin/bash
set -e

# Wait for database to be ready
echo "Waiting for database connection..."
until mysql -h"${DB_HOST}" -u"${DB_USER}" -p"${DB_PASSWORD}" -e "SELECT 1" > /dev/null 2>&1; do
    echo "Database is unavailable - sleeping"
    sleep 2
done

echo "Database is ready!"

# Create ESMira configuration file
cat > /var/www/html/config.php <<EOF
<?php
define('DB_HOST', '${DB_HOST}');
define('DB_NAME', '${DB_NAME}');
define('DB_USER', '${DB_USER}');
define('DB_PASSWORD', '${DB_PASSWORD}');
define('SITE_URL', '${SITE_URL}');
define('TIMEZONE', '${TIMEZONE:-UTC}');
define('ADMIN_EMAIL', '${ADMIN_EMAIL}');
define('UPLOAD_MAX_SIZE', ${UPLOAD_MAX_SIZE:-10485760});
define('SESSION_LIFETIME', ${SESSION_LIFETIME:-3600});
?>
EOF

# Set proper permissions
chown www-data:www-data /var/www/html/config.php
chmod 640 /var/www/html/config.php

# Initialize database if needed
php /var/www/html/scripts/init-database.php

echo "ESMira initialization complete!"

# Execute the main container command
exec "$@"

Create Database Initialization Script

Create scripts/init-database.php in your repository:

<?php
require_once '/var/www/html/config.php';

try {
    $pdo = new PDO(
        "mysql:host=" . DB_HOST . ";charset=utf8mb4",
        DB_USER,
        DB_PASSWORD,
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );

    // Create database if it doesn't exist
    $pdo->exec("CREATE DATABASE IF NOT EXISTS `" . DB_NAME . "`
                CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci");

    $pdo->exec("USE `" . DB_NAME . "`");

    // Check if tables already exist
    $stmt = $pdo->query("SHOW TABLES");
    $tables = $stmt->fetchAll(PDO::FETCH_COLUMN);

    if (count($tables) === 0) {
        echo "Initializing ESMira database schema...\n";

        // Import the schema file
        $schema = file_get_contents('/var/www/html/database/schema.sql');
        $pdo->exec($schema);

        echo "Database schema created successfully!\n";
    } else {
        echo "Database already initialized.\n";
    }

} catch (PDOException $e) {
    echo "Database initialization error: " . $e->getMessage() . "\n";
    exit(1);
}
?>

Create README for Repository

Create README.md in your repository:

# ESMira Deployment for Klutch.sh

This repository contains the Docker configuration for deploying ESMira on Klutch.sh.

## Required Environment Variables

- `DB_HOST`: MySQL database host (e.g., mysql-app.klutch.sh:8000)
- `DB_NAME`: Database name (default: esmira)
- `DB_USER`: Database username
- `DB_PASSWORD`: Database password
- `SITE_URL`: Full URL where ESMira is deployed (e.g., https://esmira-app.klutch.sh)
- `ADMIN_EMAIL`: Administrator email address
- `TIMEZONE`: PHP timezone (default: UTC)
- `UPLOAD_MAX_SIZE`: Max upload size in bytes (default: 10485760)
- `SESSION_LIFETIME`: Session lifetime in seconds (default: 3600)

## Persistent Volume

Mount Path: `/var/www/html/uploads`

This directory stores participant-uploaded media files, study attachments, and exported data.

## Deployment

Push this repository to GitHub and deploy via Klutch.sh dashboard.

Create .gitignore

Create .gitignore in your repository:

config.php
.env
*.log
uploads/*
!uploads/.gitkeep
data/*
!data/.gitkeep
logs/*
!logs/.gitkeep
vendor/
node_modules/
.DS_Store

Commit and Push

git init
git add Dockerfile docker-entrypoint.sh scripts/ README.md .gitignore
git commit -m "Initial ESMira deployment configuration"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/esmira-klutch.git
git push -u origin main

Deploying ESMira on Klutch.sh

Deploy MySQL Database First

Before deploying ESMira, you need a MySQL database. Follow our MySQL deployment guide to set one up on Klutch.sh.

Key configuration for ESMira’s database:

Database Name: esmira
Port: 8000 (external), 3306 (internal)
Traffic Type: TCP
Persistent Volume: /var/lib/mysql with at least 10GB

Make note of your database connection details:

Host: mysql-app.klutch.sh (replace with your app name)
Port: 8000
Database: esmira
Username: root (or custom user)
Password: (set via environment variables)

Deploy ESMira Application

Log in to Klutch.sh
Navigate to klutch.sh/app and sign in to your account.
Create New Application
Click "Create New App" and select your ESMira repository from GitHub. Klutch.sh will automatically detect the Dockerfile in your repository root.
Configure Application Settings
Set the following configuration:
- App Name: Choose a unique name (e.g., esmira-research)
- Region: Select the region closest to your research participants
- Traffic Type: Select HTTP (ESMira is a web application)
- Port: 80 (internal Apache port)
Add Environment Variables
Configure the following environment variables in the Klutch.sh dashboard. Mark database credentials as sensitive:
- DB_HOST: mysql-app.klutch.sh:8000 (your MySQL app URL with port)
- DB_NAME: esmira
- DB_USER: root (or your MySQL user)
- DB_PASSWORD: Your MySQL password (mark as sensitive)
- SITE_URL: https://esmira-research.klutch.sh (your ESMira URL)
- ADMIN_EMAIL: research@university.edu (your email)
- TIMEZONE: America/New_York (your timezone)
- UPLOAD_MAX_SIZE: 52428800 (50MB in bytes)
- SESSION_LIFETIME: 7200 (2 hours in seconds)
Attach Persistent Volume
Add a persistent volume for ESMira's data storage:
- Mount Path: /var/www/html/uploads
- Size: 20GB (adjust based on expected media uploads and participant data)
This ensures participant responses, uploaded media, study attachments, and exported datasets persist across deployments.
Deploy Application
Click "Deploy" to start the build process. Klutch.sh will:
- Build the Docker image with PHP, Apache, and ESMira dependencies
- Initialize the MySQL database with ESMira's schema
- Configure Apache and PHP for optimal performance
- Set up HTTPS with automatic SSL certificates
- Start the ESMira web server
The initial deployment typically takes 3-5 minutes.
Verify Deployment
Once deployed, visit your ESMira URL (e.g., https://esmira-research.klutch.sh). You should see the ESMira admin login page. If you encounter errors, check the deployment logs in the Klutch.sh dashboard.

Post-Deployment Configuration

Create Administrator Account

After deploying ESMira, create your first administrator account:

Access Admin Setup: Navigate to https://your-app.klutch.sh/admin/setup
Create Admin User:
- Username: Choose a secure username
- Password: Use a strong password (minimum 12 characters)
- Email: Enter your institutional email address
- Role: Administrator
Configure Institution Settings:
- Institution Name: Your university or research organization
- Contact Email: Research team contact
- Data Retention Policy: Set based on IRB requirements
- Consent Template: Upload your IRB-approved consent form

Configure Study Settings

Access Study Configuration: Log in to ESMira and navigate to Studies → Create New Study
Basic Study Information:
- Study Title: Descriptive title for your research project
- Study Description: Participant-facing description explaining the study
- Principal Investigator: PI name and contact information
- IRB Protocol Number: Your institutional review board approval number
- Study Duration: Start and end dates
- Estimated Time Commitment: Daily/weekly time requirements for participants
Questionnaire Design:
- Question Types: Likert scales, multiple choice, text entry, photo capture, audio recording
- Branching Logic: Implement skip patterns based on previous responses
- Randomization: Randomize question or response order to reduce bias
- Required Fields: Mark mandatory questions
- Validation Rules: Set numeric ranges, text length limits, or custom validation
Scheduling Configuration:
- Fixed Schedule: Set specific times for questionnaires (e.g., 9 AM, 12 PM, 6 PM)
- Random Schedule: Define time windows for random prompts
- Event-Triggered: Trigger questionnaires based on participant actions or sensor data
- Frequency Limits: Prevent over-sampling (e.g., max 8 prompts per day)
- Notification Settings: Configure reminder notifications and escalations
Participant Settings:
- Enrollment Process: Self-enrollment with access code or manual approval
- Consent Management: Require consent acknowledgment before participation
- Participant IDs: Auto-generate pseudonymous IDs or use existing participant numbers
- Data Sharing Preferences: Allow participants to control data sharing
- Withdrawal Process: Enable participants to withdraw and delete their data

Mobile App Setup

ESMira requires participants to install mobile apps:

Android App:
- Download from Google Play Store or distribute APK directly
- Participants enter your server URL: https://your-app.klutch.sh
- Enter study access code to enroll
iOS App:
- Download from Apple App Store
- Configure server URL in app settings
- Complete enrollment with access code

Participant Instructions:

1. Install the ESMira app from your app store
2. Open the app and tap "Add Study"
3. Enter server URL: https://esmira-research.klutch.sh
4. Enter your access code: [PROVIDED BY RESEARCHER]
5. Read and accept the consent form
6. Complete the baseline questionnaire
7. Enable push notifications to receive study prompts

Data Collection and Monitoring

Monitor Compliance: View real-time compliance rates, missed responses, and participant engagement in the admin dashboard
Send Reminders: Configure automated reminders for participants with low compliance rates
View Responses: Access individual responses, aggregate statistics, and temporal trends
Data Quality Checks: Set up automated alerts for suspicious patterns (e.g., straight-line responses, extremely fast completion times)
Adaptive Interventions: Modify prompting schedules or send personalized messages based on participant data

Data Export and Analysis

Export Formats:
- CSV: For Excel and R analysis
- SPSS: For SPSS statistical software
- JSON: For custom data processing pipelines
Export Options:
- Full dataset or filtered by date range, participant, or questionnaire
- Include raw responses or computed scores
- Pseudonymized or de-identified data
Scheduled Exports: Set up daily or weekly automated exports to cloud storage
Data Dictionary: ESMira automatically generates data dictionaries describing all variables, response scales, and coding schemes

Production Best Practices

Security Hardening

Database Security:
- Use strong, unique passwords for database connections
- Restrict database access to ESMira application only
- Enable database encryption at rest
- Regular database backups stored securely off-platform
Application Security:
- Enable two-factor authentication for admin accounts
- Implement IP whitelisting for admin access
- Regularly update ESMira to latest version for security patches
- Use environment variables for all sensitive credentials
Data Protection:
- GDPR Compliance: Implement data minimization, right to erasure, and data portability
- HIPAA Compliance (if applicable): Use business associate agreements, encrypt PHI, audit logs
- Pseudonymization: Separate participant identities from research data
- Consent Management: Store signed consent forms securely with audit trails
SSL/TLS Configuration:
- Klutch.sh provides automatic HTTPS with Let’s Encrypt certificates
- Enforce HTTPS redirects (configured automatically)
- Use strong cipher suites and TLS 1.3

Performance Optimization

Database Optimization:
- Index frequently queried columns (participant IDs, timestamps, study IDs)
- Partition large tables by date for faster queries
- Regular database maintenance (OPTIMIZE TABLE, ANALYZE)
Caching Strategy:
- Enable PHP OPcache for compiled script caching
- Use Redis for session storage and application caching (optional)
- Cache questionnaire definitions to reduce database queries
Media Storage:
- Optimize uploaded images (resize, compress) before storage
- Consider external object storage (S3-compatible) for large media files
- Implement CDN for serving static assets to participants
Monitoring:
- Set up uptime monitoring with alerts for downtime
- Monitor database connection pool and query performance
- Track mobile app crash reports and API errors
- Monitor participant-facing response times

Backup Strategy

Database Backups:
- Daily automated backups of MySQL database
- Retain backups for 30 days minimum
- Test backup restoration quarterly
- Store backups in geographically separate location
File Backups:
- Daily backups of /var/www/html/uploads volume
- Include study configurations, consent forms, and media files
- Version control for study configurations
Disaster Recovery Plan:
- Document restoration procedures
- Maintain emergency contact list for research team
- Test full disaster recovery scenario annually

Compliance and Ethics

IRB Requirements:
- Maintain current IRB approval documentation
- Report adverse events or data breaches to IRB within required timeframe
- Submit protocol amendments for significant changes
- Conduct annual continuing reviews
Participant Rights:
- Provide clear opt-out mechanisms
- Honor data deletion requests within required timeframe
- Transparent data usage policies
- Accessible privacy policy and consent forms
Data Retention:
- Define data retention period based on IRB protocol
- Automated data deletion after retention period
- Securely archive data for long-term preservation if required
Audit Logging:
- Log all admin access and data exports
- Track consent withdrawals and data deletions
- Maintain immutable audit trail for compliance

Troubleshooting

Database Connection Issues

Problem: ESMira can’t connect to MySQL database

Solutions:

Verify DB_HOST includes correct hostname and port (e.g., mysql-app.klutch.sh:8000)
Confirm MySQL app is running and accessible on port 8000 (TCP traffic)
Check database credentials in environment variables

Test database connection manually:

mysql -h mysql-app.klutch.sh -P 8000 -u root -p

Review ESMira application logs for specific connection errors

Mobile App Sync Errors

Problem: Participant apps fail to sync questionnaire responses

Solutions:

Verify HTTPS is properly configured (check for certificate errors)
Confirm API endpoints are accessible from mobile networks
Check for CORS configuration issues in Apache
Review API rate limiting settings

Test API connectivity with curl:

curl -X GET https://your-app.klutch.sh/api/studies

File Upload Failures

Problem: Participants or admins cannot upload media files

Solutions:

Verify persistent volume is properly mounted at /var/www/html/uploads
Check available disk space in volume
Confirm UPLOAD_MAX_SIZE environment variable is set appropriately

Review PHP upload settings in php.ini:

upload_max_filesize = 50M
post_max_size = 50M

Check directory permissions (should be owned by www-data)

Slow Questionnaire Loading

Problem: Questionnaires load slowly in mobile apps

Solutions:

Enable PHP OPcache for performance:
```
RUN docker-php-ext-install opcache
```
Index database tables used for questionnaire queries
Reduce questionnaire complexity (fewer branching conditions)
Optimize image sizes in questionnaire media
Consider implementing Redis caching for frequently accessed data

Session Timeout Issues

Problem: Admin users logged out too frequently

Solutions:

Increase SESSION_LIFETIME environment variable (in seconds)

Configure PHP session settings:

ini_set('session.gc_maxlifetime', 7200);
ini_set('session.cookie_lifetime', 7200);

Implement “Remember Me” functionality for admin users

Data Export Errors

Problem: Data export fails or produces corrupted files

Solutions:

Check available disk space for temporary export files
Verify PHP memory limit is sufficient for large datasets:
```
ini_set('memory_limit', '512M');
```
Export data in smaller date ranges or by study
Ensure proper character encoding (UTF-8) for international characters

Advanced Configuration

Custom Questionnaire Types

Extend ESMira with custom question types:

Photo Annotation: Allow participants to annotate photos before submission
Audio Analysis: Implement voice mood analysis or speech rate detection
Sensor Integration: Collect accelerometer, gyroscope, or heart rate data
Geofencing: Trigger questionnaires when entering/exiting specific locations

Multi-Language Support

Configure ESMira for international studies:

Interface Localization: Translate admin interface and mobile apps
Questionnaire Languages: Create parallel questionnaire versions in multiple languages
Dynamic Language Selection: Let participants choose their preferred language
Cultural Adaptation: Adjust response scales and formats for different cultures

Integration with External Systems

Connect ESMira to research infrastructure:

REDCap Integration: Export data directly to REDCap for combined datasets
SPSS Automation: Scheduled SPSS exports with syntax files for automatic analysis
R Integration: Use ESMira API to pull data directly into R analysis pipelines
Fitbit/Apple Health: Import wearable device data for correlation with ESM data

Advanced Analytics

Implement sophisticated analysis features:

Real-Time Alerts: Notify researchers when participants report concerning responses (e.g., high depression scores)
Compliance Prediction: Machine learning models to predict dropout risk
Personalized Schedules: Adaptive sampling that learns optimal prompting times for each participant
Network Analysis: Analyze social interaction patterns from ESM data

Additional Resources

Deploy ESMira on Klutch.sh today and start collecting rich, real-time behavioral data for your research studies. With automated infrastructure management, GDPR-compliant data handling, and seamless mobile integration, you can focus on research insights rather than technical complexities.