Skip to content

README.md

Latest commit

 

History

History
163 lines (113 loc) · 4.53 KB

README.md

File metadata and controls

163 lines (113 loc) · 4.53 KB

Server Setup and Configuration

This directory contains guides for setting up and configuring a gEAR server instance.

Setup Guides

Core Installation

  • New Server Setup - Complete guide for setting up a fresh gEAR instance
    • System requirements and cloud instance setup
    • Base system configuration
    • Quick reference for common setup tasks

Component Setup

Optional Components

Quick Start

For a new server installation:

  1. Start with New Server Setup
  2. Follow the component guides in order:
    • MySQL → Python → Apache → RabbitMQ (optional) → R (optional)
  3. Configure gear.ini from template
  4. Set up systemd services for background workers
  5. Load annotation data and test datasets

System Requirements

Minimum Requirements

  • OS: Ubuntu 22.04 LTS (recommended)
  • CPU: 2 vCPUs (4+ recommended for production)
  • RAM: 16GB (48GB+ recommended for production)
  • Storage: 100GB+ SSD

Recommended for Production

  • CPU: 16+ cores
  • RAM: 100GB+
  • Storage: 300GB+ SSD (more depending on dataset sizes)

Configuration Files

  • gear.ini.template - Main configuration template
  • docker/gear.ini.docker.template - Docker-specific configuration
  • create_schema.sql - Database schema

Data Directories

After setup, ensure these directories exist and have proper permissions:

www/
├── datasets/           # H5AD dataset files
├── datasets/spatial/   # Zarr spatial data stores
├── analyses/           # Analysis results
├── carts/              # Gene lists
├── projections/        # ProjectR results
├── uploads/files/      # Upload staging area
└── img/dataset_previews/  # Dataset preview images

Common Issues

Apache won't start

  • Check Apache error logs: /var/log/apache2/error.log
  • Verify mod_wsgi is installed: apache2ctl -M | grep wsgi
  • Check gear.ini permissions and syntax

Database connection errors

  • Verify MySQL is running: systemctl status mysql
  • Check database credentials in gear.ini
  • Ensure database user has proper permissions

Python import errors

  • Activate virtual environment if using one
  • Install missing packages: pip install -r requirements.txt
  • Check Python path in wsgi configuration

RabbitMQ connection issues

  • Verify RabbitMQ is running: systemctl status rabbitmq-server
  • Check credentials and virtual host in gear.ini
  • Review RabbitMQ logs: /var/log/rabbitmq/

Migration from Existing Instance

Data Transfer

Transfer these directories from old to new instance:

$HOME/git/gEAR/www/datasets
$HOME/git/gEAR/www/analyses

Database Migration

  1. Export database from old instance:

    mysqldump -u root -p gear_db > gear_backup.sql

  2. Import on new instance:

    mysql -u root -p gear_db < gear_backup.sql

Docker Alternative

For development, strongly recommended to use Docker instead of a full server setup:

  • See Docker Setup Guide
  • Faster setup but requires more disk space
  • Good for local development and testing

Maintenance

Regular Tasks

  • Update system packages: sudo apt update && sudo apt upgrade
  • Monitor disk space (datasets can grow large)
  • Review Apache/MySQL logs for errors
  • Backup database regularly

Updating gEAR

cd /path/to/gEAR
git pull origin devel
# Restart services (if needed)
sudo systemctl restart apache2
sudo systemctl restart projectr-consumer.target gosling-upload-consumer.target
sudo systemctl restart spatial-panel.service

Apache2 - If API code was updated ProjectR consumers - If projectR code in /services/projectr was updated Spatial Panel daemon - If code in /services/spatial was updated

Getting Help

  • Check component-specific setup guides for detailed instructions
  • Review logs for error messages
  • Create an issue on GitHub
  • Contact @adkinsrs for infrastructure questions