Installation Guide

# Linux (Ubuntu/Debian)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker
 
# Verify installation
docker --version
docker compose version

git clone https://github.com/BGI-MICOS/MICOS-2024.git
cd MICOS-2024

# Start all services
docker compose -f deploy/docker-compose.example.yml up -d
 
# Verify services are running
docker compose -f deploy/docker-compose.example.yml ps
 
# View logs
docker compose -f deploy/docker-compose.example.yml logs -f

# Enter the main analysis container
docker compose -f deploy/docker-compose.example.yml exec micos bash
 
# Run analysis
python -m micos.cli --help

# Download Miniforge installer
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
 
# Run installer
bash Miniforge3-Linux-x86_64.sh -b -p $HOME/miniforge
 
# Initialize shell
$HOME/miniforge/bin/conda init bash
source ~/.bashrc

# Clone repository
git clone https://github.com/BGI-MICOS/MICOS-2024.git
cd MICOS-2024
 
# Create environment with mamba (faster)
mamba env create -f environment.yml
 
# Activate environment
conda activate micos-2024

# Install in editable mode for development
pip install -e .
 
# Or install normally
pip install .

# Check core dependencies
kraken2 --version
humann --version
qiime --version
kneaddata --version

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    python3-dev \
    python3-pip \
    git \
    wget \
    curl
 
# Install bioinformatics tools manually
# See individual tool documentation for details

# Create virtual environment
python3 -m venv micos-env
source micos-env/bin/activate
 
# Install Python dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # For development

git clone https://github.com/BGI-MICOS/MICOS-2024.git
cd MICOS-2024
pip install -e .

# Run database download script
python scripts/download_databases.py \
  --output-dir /path/to/databases \
  --databases kraken2,kneaddata,humann

# Create database directory
mkdir -p /path/to/kraken2_db
 
# Download and build standard database (requires ~70GB)
kraken2-build --download-taxonomy --db /path/to/kraken2_db
kraken2-build --download-library bacteria --db /path/to/kraken2_db
kraken2-build --download-library archaea --db /path/to/kraken2_db
kraken2-build --build --db /path/to/kraken2_db --threads 16
 
# Or download pre-built MiniKraken (quick start, ~8GB)
wget https://genome-idx.s3.amazonaws.com/kraken/minikraken2_v2_8GB_201904_UPDATE.tgz
tar -xzf minikraken2_v2_8GB_201904_UPDATE.tgz

# Download human genome reference
kneaddata_database --download human_genome bowtie2 /path/to/kneaddata_db

# Download functional databases
humann_databases --download chocophlan full /path/to/humann_db
humann_databases --download uniref uniref90_diamond /path/to/humann_db

database_root: "/path/to/databases"
 
quality_control:
  kneaddata:
    human_genome: "${database_root}/kneaddata/human_genome"
 
taxonomy:
  kraken2:
    standard: "${database_root}/kraken2/standard"
    minikraken: "${database_root}/kraken2/minikraken"
 
functional:
  humann:
    chocophlan: "${database_root}/humann/chocophlan"
    uniref90: "${database_root}/humann/uniref90"

# Run verification script
./scripts/verify_installation.sh

✓ Python 3.9+ found
✓ Kraken2 installed
✓ HUMAnN installed
✓ QIIME2 installed
✓ Kneaddata installed
✓ All dependencies satisfied

# Download test data
python scripts/download_test_data.py --output-dir test_data
 
# Run quick test
python -m micos.cli full-run \
  --input-dir test_data \
  --results-dir test_results \
  --threads 4 \
  --kneaddata-db /path/to/kneaddata_db \
  --kraken2-db /path/to/kraken2_minikraken

# Verify outputs exist
ls test_results/
# Should show: quality_control/, taxonomic_profiling/, functional_annotation/, report.html

# Download packages
pip download \
  -r requirements.txt \
  -d ./offline_packages \
  --platform manylinux2014_x86_64
 
# Export conda environment
conda env export --no-builds > environment-offline.yml
 
# Download databases (see Database Setup section)

# Install from local packages
pip install --no-index --find-links=./offline_packages -r requirements.txt
 
# Install MICOS
pip install -e MICOS-2024/

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
 
# Verify
docker run hello-world

# Clear conda cache
conda clean --all
 
# Update conda
conda update -n base conda
 
# Try with mamba
conda install mamba -c conda-forge -n base
mamba env create -f environment.yml --force

# Use mirror sites
# For China users:
export KRAKEN2_DB_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/"
 
# Or download manually from:
# https://benlangmead.github.io/aws-indexes/k2

# Reduce threads during build
kraken2-build --build --db /path/to/db --threads 4
 
# Or use pre-built databases
wget https://genome-idx.s3.amazonaws.com/kraken/k2_standard_20231009.tar.gz