Microservices Documentation

April 6, 2026 · View on GitHub

gEAR uses several microservices for specialized functionality. This directory consolidates documentation for all services.

Available Services

ProjectR Service

Matrix projection service for dimensionality reduction and analysis.

Location: services/projectr/
Deployment: Docker container on Google Cloud Run or local
Purpose: Performs ProjectR matrix projections for tSNE/UMAP analysis

Spatial Panel Service

Dashboard service for spatial transcriptomics data visualization.

Location: services/spatial/
Deployment: Docker container (Panel app)
Purpose: Interactive visualization of spatial datasets

RabbitMQ Consumers

Background workers that process async jobs from message queue.

Location: listeners/
Deployment: Systemd services
Purpose: Process ProjectR, analysis, and other long-running tasks

How to create Plugins

Information on how to extend the gEAR platform with a domain-specific plugins

Location: www/plugins/

Service Architecture

gEAR API (Flask)
    |
    ├──> ProjectR Service (Cloud Run or local)
    |    └── Matrix projection computations
    |
    ├──> Spatial Panel Service
    |    └── Spatial data visualization
    |
    └──> RabbitMQ
         └──> Consumer Workers (systemd)
              ├── ProjectR consumer
              └── Gosling upload consumer

Configuration for projectR

All services are configured via gear.ini:

[projectR_service]
hostname = https://staging---projectr-service-7822838784.us-east1.run.app
;; 0 - disable, 1 - enable
cloud_run_enabled = 1
;; 0 - disable RabbitMQ, 1 - enable. Disabling could lead to potential server crashes if many jobs are run simultaneously
queue_enabled = 0
queue_host = localhost

Deployment Options

Option 1: Cloud Run (Recommended for Production)

Deploy ProjectR as Cloud Run service
No local R installation needed
Auto-scaling
RabbitMQ is recommended (see Option 2 for configuration option)
Configuration: cloud_run_enabled = 1

Option 2: Local with RabbitMQ (Development)

Run ProjectR consumers via systemd
Requires local R installation
Good for development/testing
Configuration: queue_enabled = 1

Option 3: In-Process (Quick Testing)

Run ProjectR directly in Apache process
Simple but blocks request thread
Only for testing
Configuration: cloud run enabled = 0; queue_enabled = 0

Quick Start

Setting Up ProjectR Cloud Service

Build Docker image (see projectr.md)
Push to Google Artifact Registry
Deploy to Cloud Run
Update gear.ini with service URL

Setting Up Local RabbitMQ Consumers

Install RabbitMQ (see rabbitmq_consumers.md)
Install R and packages (see docs/developer/setup/r_rpy2.md)

Start consumer services:

sudo systemctl start projectr-consumer.target gosling-upload-consumer.target

Setting Up Spatial Panel

Build spatial panel image (see spatial.md)

Start service:

sudo systemctl start spatial-panel.service

Monitoring Services

Cloud Run Services

View in Google Cloud Console
Check logs via Cloud Logging
Monitor request counts and latency

Monitoring Systemd Services

# Check service status
sudo systemctl status projectr-consumer@1.service

# View logs
sudo journalctl -u projectr-consumer@1.service -f

# Restart service
sudo systemctl restart projectr-consumer@1.service

RabbitMQ

# Management UI (if enabled)
http://localhost:15672

# Command line
sudo rabbitmqctl list_queues

Scaling Services

Cloud Run

Auto-scales based on request load
Configure max instances in Cloud Run console
Adjust CPU/memory per instance

Systemd Services

# Start additional workers
sudo systemctl start projectr-consumer@2.service
sudo systemctl start projectr-consumer@3.service

# Or use target to manage all at once
sudo systemctl start projectr-consumer.target

Troubleshooting

ProjectR Service Issues

Service not responding: Check Cloud Run logs
Timeout errors: Increase timeout in Cloud Run config (currently 1200s)
Memory errors: Increase memory allocation (currently 16GB)

RabbitMQ Consumer Issues

Jobs not processing: Check systemd service status
Consumer crashes: Check logs via journalctl
Connection errors: Verify RabbitMQ is running and credentials in gear.ini

Spatial Panel Issues

Panel not loading: Check systemd service logs
Port conflicts: Verify port 5006 is available
Zarr data errors: Verify spatial dataset paths

Development

For local development, a Docker Compose stack is used and recommended. See the Docker setup documentation for more information.

Service-Specific Documentation

ProjectR: See projectr.md for detailed setup and deployment
Spatial Panel: See spatial.md for configuration
RabbitMQ Consumers: See rabbitmq_consumers.md for worker management

Additional Resources

Systemd service templates: systemd/
Docker configurations: docker/
Setup guides: docs/developer/setup/