Installation Guide

Docker Installation

This guide covers the Dockerized installation of Magellon. For non-Docker installations, refer to the standard installation guide.

This documentation walks you through installing and configuring Magellon — a cryo-EM analysis platform — using Docker. The Dockerized version simplifies dependency management and ensures consistent performance across different environments.

1. Install Docker

   Docker Desktop is the recommended installation method as it provides a consistent experience across platforms.

   • Download and install Docker Desktop for your operating system.
   • Verify installation by running docker --version in your terminal.

2. Download the Demo Data

   Access the demo dataset using the Globus file transfer service.

   • Navigate to the Globus File Manager.
   • Log in or create a Globus account if needed.
   • Transfer the demo files to your local system.

3. Download Magellon Source Code

   Clone the Magellon repository from GitHub:

   git clone https://github.com/sstagg/Magellon.git

   Alternatively, download the ZIP archive from the GitHub repository.

4. Create Magellon Directories

   Magellon’s data plane lives under a single root — the GPFS directory. Everything else (results, scratch jobs, imported sessions) is a subdirectory inside it. The simplest path is to copy the magellon directory under docker/ to wherever you want it — it already contains the expected layout.

   • GPFS Directory — the data-plane root, mapped to /gpfs inside the containers (e.g. /magellon/gpfs).
     • home/ — where Magellon writes processing results.
     • jobs/ — scratch space for in-flight job files.
     • <session-name>/ — each imported session lands here.

   magellon/
   ├── gpfs/
   │   ├── home/
   │   ├── jobs/
   │   └── <imported sessions>/
   └── services/

   Why nested?

   Earlier releases used three sibling directories (home/, gpfs/, jobs/). Consolidating under gpfs/ means one bind mount, one host path to configure, and a layout that mirrors how shared HPC filesystems are usually mounted.

5. Configure Environment Settings

   Navigate to the Docker subdirectory in the Magellon source, then:

   cp .env.example .env

   Edit .env to point at your Magellon GPFS directory — that’s the only host path you need:

   MAGELLON_GPFS_PATH=/magellon/gpfs

   Inside CoreService and the plugin containers, MAGELLON_HOME_DIR and MAGELLON_JOBS_DIR default to relative names (home, jobs) that resolve against MAGELLON_GPFS_PATH at config load. You only need to override them if you want results or scratch to live outside gpfs/.

6. Start Magellon Containers

   From the Docker directory:

   bash start.sh

   Wait for container initialization (longer on first run). For subsequent starts:

   docker compose --profile default up -d

   First Run Performance

   ⏱️ 5-10 minutes

   The first run downloads and initializes every supporting container — this can take a while on slow networks. Subsequent starts are much faster.

7. Import Demo Data

   • Move the Globus demo data into your Magellon GPFS directory.
   • Open the front-end at http://localhost:8080/en/panel/images.
   • Click Login, then the menu icon in the top-left.
   • Select Import and open the Magellon import tab.
   • Double-click the 24dec03a directory, then session.json.
   • Click IMPORT DATA to start the import.
   Import Processing Time

   Import can take 5–60 minutes depending on system resources. On Linux with a compatible GPU, Magellon performs frame alignment, which can extend the processing time.

8. Explore Magellon

   Navigate to http://localhost:8080/en/panel/images and select the imported session (e.g. 24DEC03A) to begin exploring your data.