← Back to Documentation Home

GitHub Pages Deployment

Complete guide to deploying O-ELIDDI on GitHub Pages

Overview

GitHub Pages provides free static website hosting, making it ideal for deploying O-ELIDDI studies. This guide covers forking the repository, configuring your study, and setting up automatic deployment.

Benefits of GitHub Pages:

Prerequisites

Before you begin, ensure you have:

Step-by-Step Deployment

1Fork the Repository

Create your own copy of the O-ELIDDI repository:

  1. Visit the original O-ELIDDI repository on GitHub
  2. Click the "Fork" button in the top-right corner
  3. Choose your GitHub account as the destination
  4. Optionally rename the repository (e.g., "my-timeuse-study")
Repository Visibility: GitHub Pages is free for public repositories. For private repositories, you need a paid GitHub account.

2Clone Your Fork Locally

Download your fork to make configuration changes:

git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git cd YOUR_REPO_NAME

3Configure Your Study

Customize the application for your research study:

A. Update activities.json

Edit settings/activities.json with your study configuration:

{
  "general": {
    "experimentID": "YOUR_DATAPIPE_EXPERIMENT_ID",
    "app_name": "Your Study Name",
    "version": "1.0.0",
    "author": "Your Name",
    "language": "en",
    "instructions": true,
    "primary_redirect_url": "pages/thank-you.html",
    "fallbackToCSV": true
  },
  "timeline": {
    // Your timeline configuration
  }
}

B. Customize Thank You Page

Edit pages/thank-you.html to match your study completion message.

C. Update Instructions (Optional)

Modify pages/instructions.html and pages/instructions.js to customize participant instructions.

4Test Locally

Before deploying, test your configuration locally:

# Install dependencies (if needed) npm install # Start local development server npm start # Open browser to http://localhost:8080

Verify that:

5Commit and Push Changes

Save your configuration to GitHub:

git add . git commit -m "Configure study settings and activities" git push origin main

6Enable GitHub Pages

Configure GitHub to serve your repository as a website:

  1. Go to your repository on GitHub
  2. Click Settings tab
  3. Scroll down to Pages section
  4. Under Source, select "Deploy from a branch"
  5. Select main branch and / (root) folder
  6. Click Save

7Access Your Study

GitHub will provide a URL for your deployed study:

https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/

This process may take a few minutes. Check the Pages section in your repository settings for the exact URL and deployment status.

Custom Domain Setup (Optional)

You can use a custom domain instead of the default github.io URL:

Requirements

Configuration Steps

  1. In your repository's Pages settings, add your custom domain
  2. Create a CNAME file in your repository root with your domain name
  3. Configure your domain's DNS to point to GitHub Pages
  4. Enable "Enforce HTTPS" once DNS propagation is complete
DNS Configuration: Add these DNS records at your domain provider:

Automatic Deployment Workflow

GitHub Pages automatically rebuilds your site when you push changes to the main branch. However, you can create a custom GitHub Actions workflow for more control:

Create .github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install dependencies
      run: npm install
      
    - name: Run tests (if available)
      run: npm test --if-present
      
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./

URL Parameters for Participant Links

Once deployed, you can create participant-specific links by adding URL parameters:

Basic Participant Link

https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/?pid=P001&STUDY_ID=MyStudy&DIARY_WAVE=1

Prolific Integration

https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

See the URL Parameters guide for complete details on parameter configuration.

Managing Study Updates

Making Changes

  1. Edit files locally or directly on GitHub
  2. Test changes locally if significant
  3. Commit and push to main branch
  4. GitHub Pages automatically deploys updates

Version Control Best Practices

# Create a new branch for changes git checkout -b study-modifications # Make your changes, then: git add . git commit -m "Update activities for phase 2" git push origin study-modifications # Create pull request on GitHub to review changes # Merge to main when ready to deploy

Monitoring and Analytics

GitHub Insights

Monitor your study deployment through GitHub's built-in analytics:

Additional Monitoring (Optional)

For more detailed analytics, consider integrating:

Troubleshooting Common Issues

Site Not Loading

Common Solutions:

Activities Not Loading

DataPipe Export Failing

HTTPS Issues

GitHub Pages automatically provides HTTPS. If you encounter mixed content warnings:

Security and Privacy Considerations

Data Protection

Participant Privacy

Performance Optimization

Loading Speed

Mobile Optimization

O-ELIDDI is mobile-responsive by default, but consider:

Deployment Checklist

Before launching your study: