starbase: Database and Toolkit for Exploration of Starship Elements in Fungi

Overview

starbase is a web-based application that provides various analytical and visualization tools for exploring large eukaryotic transposable elements known as Starships.

Access starbase here.

What is a Starship?

Starships are extremely large (~20-700 kb) DNA transposons that can constitute up to 2% of fungal genomes. These novel class II DNA transposons are endemic to Pezizomycotina and can significantly impact the architecture of fungal genomes. They replicate within the host genome via tyrosine recombinases (captain genes) and can carry significant genetic 'cargo', such as:

• Genes for metal resistance in Paecilomyces
• Cheese-making genes in Penicillium
• Formaldehyde resistance genes in Aspergillus nidulans and Penicillium chrysogenum

Usage

• Explore existing Starship sequences: Browse and select individual or collections of Starship sequences for download. View detailed information about Starship Families and their general characteristics.
• Search for Starships: Utilize the BLAST/HMMER search functions to analyze sequences against the existing database. Runs a classification workflow to compare identify if the sequence is within an existing family/navis/haplotype.
• Submit a Sequence: Use the submission tab to upload new Starship sequences for curation and inclusion in the database.

Features Under Development

• starfish webserver
• Starship `Browser/Comparison: Visualize and compare Starships and their gene annotations.

Contributions

Contributions to the development of starbase are welcome! If you have suggestions or improvements, please feel free to submit an issue or pull request.

Building and running from the Docker image

• Note: Currently, starbase will not run without database files (src/database/db/), which need to be mounted into the container.

Versions of the database are stored in a Zenodo repository.

Local Development

Mimicking Serve Production Environment (Recommended)

The SciLifeLab Serve platform uses a single-pod kubernetes environment for each app.

Quick Start

# Option 1: Simple setup (recommended)
./setup-dev.sh

# Option 2: Direct setup
bash ./dev/scripts/setup-local-pod.sh

This will:

• Detect your local IP address
• Create the environment configuration
• Build the Docker image
• Create required directories
• Start the single-pod environment
• Verify the application is healthy

Manual Setup

If you prefer manual setup or need to customize the configuration:

# 1. Create environment configuration
cp dev/config/env.template .env

# 2. Update .env with your local IP (optional - will be auto-detected)
# Edit AUTH_DOMAIN, HOST_IP, POD_IP, KUBERNETES_SERVICE_HOST

# 3. Create required directories
mkdir -p src/database/cache src/database/logs src/database/db

# 4. Build the Docker image
docker build -f dev/docker/local.Dockerfile -t starbase:local-pod .

# 5. Start the environment
docker compose -f dev/docker/docker-compose.local.yaml up -d

Access Your Application

Once running, access your Dash app at:

• Local: http://localhost:8080
• Network: http://YOUR_LOCAL_IP:8080
• Domain: http://studio.YOUR_LOCAL_IP.nip.io:8080

Development Workflow

# View application logs
docker logs starbase-local-pod -f

# Access container shell
docker exec -it starbase-local-pod /bin/bash

# Restart the application
docker compose -f dev/docker/docker-compose.local.yaml restart

# Stop the environment
docker compose -f dev/docker/docker-compose.local.yaml down

# Rebuild and restart (after dependency changes)
docker compose -f dev/docker/docker-compose.local.yaml down
docker build -f dev/docker/local.Dockerfile -t starbase:local-pod .
docker compose -f dev/docker/docker-compose.local.yaml up -d

Features

This environment provides:

• Single Pod Simulation: Mimics a Kubernetes pod deployment
• Resource Constraints: 2GB memory, 1 CPU core limits
• Volume Mounts: Database files properly mounted and persistent
• Health Checks: Application health monitoring
• Development Mode: Hot reloading enabled for code changes
• Security Context: Runs as non-root user (UID 1000)
• Network Isolation: Custom bridge network

Legacy Development Methods

Docker Compose (Original)

# Build and run the application
docker compose up app --build

# Run with verbose logging and hot reload
docker compose up app --build && docker exec starbase_app ./start-script.sh --dev

Direct Docker

# Find the most recent version under the "Packages" tab
docker pull ghcr.io/fungage/starbase:[tag]

# Run Starbase locally with Docker
docker build -t starbase .
docker run -it --rm -p 8000:8000 starbase ./start-script.sh

You can reach the app in your local browser by visiting localhost:8000 (legacy) or localhost:8080 (single-pod environment).

Debug Mode

Enable debug logging in your .env file:

LOG_LEVEL=DEBUG
DEV_MODE=true

Unit tests

Run the default unit test suite (no database files required):

conda activate starbase
pytest

This runs tests under tests/ and skips @pytest.mark.integration tests (database, BLAST/HMMER, submission DB).

# Include integration tests (requires src/database/db/ mounted)
pytest -m integration

# Run everything
pytest -m ""

BLAST pipeline helpers have focused coverage in tests/test_blast_pipeline.py.

Legacy tests under src/database/cleanup* are excluded via testpaths = tests in pytest.ini.

Run Pytest in a Docker container:

# Run tests (will build image if needed)
docker compose --profile testing up unit-tests

# Or run tests against existing image
docker compose run --rm unit-tests

Tear down

# Stop all services and remove volumes
docker compose down --volumes

# Remove built images (optional)
docker rmi starbase:latest