Getting started with Slivka-Bio

Pick the role that matches how you work to see the most relevant tasks, tools, and documentation.

Preview content. We are consolidating quick-start guidance across the Slivka ecosystem; expect refinements as we finish the rollout. Full guides remain available via the Documentation menu above, including the Slivka documentation, Slivka on GitHub, Slivka-Bio on GitHub, installer repos, and the Slivka-Bio Docker Hub images.

Most users should start with Jalview and the Slivka-Bio Docker stack. Use the Python/Jupyter guide if you want to script jobs.

Run workflows locally with Jalview and the Slivka-Bio Docker stack

recommended

The Slivka-Bio Docker stack is the quickest way to run Slivka-Bio workflows on your own machine and access them from Jalview Develop. It starts Slivka-Bio and MongoDB with Docker Compose and exposes the API at http://localhost:4040.

Start the Slivka-Bio Docker stack

# Get the Docker Compose setup
git clone https://github.com/bartongroup/slivka-bio-docker.git
cd slivka-bio-docker

# Start Slivka-Bio and MongoDB
docker compose up -d

Connect Jalview Develop

Install Jalview Develop, then add http://localhost:4040/ as a Slivka service URL.

On macOS: Settings > Slivka Services > New Service URL
On Windows: Tools > Preferences > Slivka Services > New Service URL

Local services will then appear under Web Service > Slivka. You can configure more than one Slivka URL, so Jalview can show both the public DRSASP server and your local Docker server.

Private local workflows: for sensitive data, remove the public Slivka URL from Jalview and keep only your local http://localhost:4040/ server. The public default can be restored later with Reset Services in the Slivka Services panel.

Access Slivka from Python or Jupyter

Use the slivka-client package to script jobs, stream status, and pull results into data pipelines. Install from conda, PyPI, or directly from GitHub, then follow the quick workflow below (mirroring our Colab demo).

Step 1: Install the client

Conda

conda install -c slivka -c conda-forge slivka-client

Pip (from PyPI)

pip install slivka-client

Pip (Latest from GitHub)

pip install git+https://github.com/bartongroup/slivka-python-client.git

Step 2: Point the client at a Slivka server

Connect to the Dundee-hosted services by default, or swap in your own deployment URL.

from slivka_client import SlivkaClient

slivka_server_url = "https://www.compbio.dundee.ac.uk/slivka/"
client = SlivkaClient(slivka_server_url)
service = client["clustalo"]
print(f"Connected to {client.url}")

Step 3: Submit a job with an input FASTA

Download a sample alignment file, then submit it to the Clustal Omega service.

from pathlib import Path
from urllib.request import urlretrieve

data_dir = Path("data")
data_dir.mkdir(exist_ok=True)
fasta_path = data_dir / "fam83b-pandda-chains-for-align-test.fa"
urlretrieve(
    "https://raw.githubusercontent.com/bartongroup/slivka-bio-docker/main/demo/data/fam83b-pandda-chains-for-align-test.fa",
    fasta_path,
)

with open(fasta_path, "rb") as handle:
    job = service.submit_job(
        data={
            "iterations": 1,
            "max-guidetree-iterations": 1,
            "max-hmm-iterations": 1,
        },
        files={"input": handle},
    )
print(f"Submitted job: {job.id}")

Step 4: Poll status and download results

Refresh the job until it finishes, save each output, and print the multiple sequence alignment.

import time

from pathlib import Path

while job.status not in ("COMPLETED", "FAILED"):
    print(f"Status: {job.status}")
    time.sleep(3)

downloads = Path("downloads") / job.id
downloads.mkdir(exist_ok=True)

for result_file in job.files:
    target_path = Path("downloads") / result_file.id
    result_file.dump(f"{target_path}")
    print(f"Saved {result_file.label} to {target_path}")
    if result_file.label == "alignment":
        print(target_path.read_text())

Explore examples and API helpers in the slivka-python-client repository, then point your code at https://www.compbio.dundee.ac.uk/slivka/.

Start with the Docker stack for the quickest full-stack evaluation. Use slivka-bio-installer when you want a curated system-style installation with selected services. The old Conda metapackage route is kept as a lower-level alternative for linux-64 systems.

Set up the Slivka-Bio Docker stack

preferred quick start

The Slivka-Bio Docker stack is the preferred way to evaluate Slivka-Bio locally. It starts the Slivka-Bio application container and MongoDB together with Docker Compose, exposes the API on http://localhost:4040, and avoids the platform-specific dependency resolution issues of the full Conda metapackage.

Step 1: Get the Slivka-Bio Docker stack

Clone repository

# Get the Docker Compose setup
git clone https://github.com/bartongroup/slivka-bio-docker.git
cd slivka-bio-docker

Step 2: Start the stack

Docker Compose

# Start Slivka-Bio and MongoDB
docker compose up -d

Step 3: Verify services

Check that service endpoints are exposed, then run the packaged service tests inside the Slivka-Bio container:

Smoke test

# List available service endpoints
curl -s http://localhost:4040/api/services | jq -r '.services[]."@url"'

# Run packaged service tests
docker compose exec slivka-bio bash -lc '
  eval "$(micromamba shell hook --shell bash)"
  micromamba activate slivka-installer
  slivka test-services
'

A healthy Docker setup should list Slivka-Bio services such as clustalo, muscle, aacon, jronn, and rnaalifold. A qsub failure from the GridEngine example runner can be ignored on systems that do not provide Grid Engine.

Step 4: Stop the stack

Shutdown

# Stop containers but keep named volumes
docker compose down

# Optional: also remove stored MongoDB/media volumes
docker compose down -v

Use the Conda guide below when you need to inspect or customise the packaged environment directly, or when Docker is not available.

Install selected services with slivka-bio-installer

preferred custom install

Use slivka-bio-installer when you want to build a custom Slivka-Bio project rather than run the prebuilt Docker stack. This pathway lets you select the services to install, avoid heavyweight optional components, and build platform-compatible subsets, including on Apple Silicon.

Step 1: Create an installer environment

Installer tools

# Create and activate an environment for the installer CLI
micromamba create -n slivka-installer \
  -c conda-forge -c slivka \
  python click ruamel.yaml slivka git curl jq
micromamba activate slivka-installer

The examples use micromamba, but the installer can use other conda-compatible tools when supplied with --conda-exe.

Step 2: Clone the installer

Repository checkout

# Clone the installer repository
git clone https://github.com/proteinverse/slivka-bio-installer.git
cd slivka-bio-installer

Some services require extra source trees or large downloads. For example, ProteinMPNN-based workflows use an additional submodule. Do not initialise all submodules unless you intend to install those services.

Step 3: Install selected services

Install a curated set of services into a new Slivka project. Repeat -s for each service prefix you want to include. Without -s, the installer will try to install every service definition, which may pull large optional downloads or hit stale package pins.

Selected-service install

# Install selected services into a new Slivka project
python install_cli.py \
  --conda-exe autodetect \
  -s msaprobs-0.9.7 \
  -s muscle-5.1 \
  -s aacon-1.1 \
  -s clustalo-1.2.4 \
  -s probcons-1.12 \
  -s clustalw-2.1 \
  -s muscle-3.8.1551 \
  -s rnaalifold-2.6.4 \
  -s jronn-3.1b \
  /tmp/slivka-bio-project

The installer is interactive by default. Choose the conda backend for services you want to install, and skip services you do not need.

Step 4: Start MongoDB

Slivka needs MongoDB for job state. For local testing, start MongoDB against a writable data directory inside the generated project.

Local MongoDB for installer project

# Create a separate environment for local MongoDB
micromamba create -n slivka-mongodb -c conda-forge mongodb
micromamba activate slivka-mongodb

# Start MongoDB with a project-local data directory
mkdir -p /tmp/slivka-bio-project/data/db
mongod \
  --dbpath /tmp/slivka-bio-project/data/db \
  --bind_ip 127.0.0.1 \
  --logpath /tmp/slivka-bio-project/data/mongod.log \
  --fork

Step 5: Launch Slivka

Start generated project

# Start Slivka from the generated project directory
micromamba activate slivka-installer
cd /tmp/slivka-bio-project

# Start server, scheduler, and local queue in the background
slivka start server &
slivka start scheduler &
slivka start local-queue &

Step 6: Verify services

Smoke test

# List installed service endpoints
curl -s http://localhost:4040/api/services | jq -r '.services[]."@url"'

# Run service tests
slivka test-services

The installer-generated project exposes the API at http://localhost:4040. The queue socket is configured separately and may use a neighbouring port such as 4041.

Use this pathway when you need a custom, service-selected installation. Use the Docker stack when you want the fastest full-stack evaluation.

Legacy alternative: set up the Conda metapackage

linux-64 / amd64 only

This older pathway installs the full slivka-bio Conda metapackage directly. It is useful for inspecting the packaged environment, but is less flexible than slivka-bio-installer and depends on every bundled service dependency being available for the target platform.

Platform note: this Conda quick-start is intended for linux-64 / amd64 systems. It is not currently a supported Apple Silicon pathway: the full slivka-bio metapackage will not install if any bundled service dependency is unavailable for the target platform, and running the amd64 stack under Apple Silicon emulation can break Slivka's ZeroMQ messaging. Slivka itself is compatible with Apple Silicon, but this full bundled service installation should be tested on linux-64 or replaced with a native/custom Slivka setup containing only services available on your platform.

Step 1: Install Slivka-Bio

Create a fresh conda environment with the Slivka-Bio metapackage and openjdk. The metapackage installs the Slivka framework, bundled bioinformatics tools, and the pre-configured Slivka-Bio project; openjdk is needed for Java-backed services such as AACon and JRonn. Activate the environment later when you launch or test the server:

Conda installation

# Create the Slivka-Bio application environment
conda create -n slivka-bio \
  -c slivka -c bartongroup -c bioconda -c conda-forge \
  slivka-bio openjdk

The packaged project is installed at $CONDA_PREFIX/var/slivka-bio/. Start Slivka from that directory to load the bundled Slivka-Bio services. Running slivka init elsewhere creates a clean example project, which is useful for learning the framework but only exposes the tutorial service until you add real service definitions.

Custom deployments: install slivka alone, run slivka init, or clone the Slivka-Bio configuration repo if you want to build your own service stack rather than use the packaged project.

Step 2: Start MongoDB

For local testing, install MongoDB from conda-forge into a separate lightweight environment and run it against a writable data directory inside the Slivka-Bio project. This keeps the application environment unchanged while providing a disposable local database for evaluation. In production, use your organisation's normal MongoDB package, storage, and service-management approach.

Local MongoDB for testing

# Create a separate environment for local MongoDB
conda create -n slivka-mongodb -c conda-forge mongodb
conda activate slivka-mongodb

# Use a writable data directory inside the packaged Slivka-Bio project
SLIVKA_BIO_HOME=$(conda run -n slivka-bio python -c 'import os, sys; print(os.path.join(sys.prefix, "var", "slivka-bio"))')
mkdir -p "$SLIVKA_BIO_HOME/data/db"

# Start MongoDB for this test instance
mongod --dbpath "$SLIVKA_BIO_HOME/data/db" --fork --syslog

Step 3: Launch Slivka

Switch back to the Slivka-Bio environment and start the server, scheduler, and local queue from the packaged project directory. Review $CONDA_PREFIX/var/slivka-bio/settings.yml first if you need to change the server address, queue address, or MongoDB database name:

Start Slivka services

# Activate the Slivka-Bio environment and packaged project
conda activate slivka-bio
cd $CONDA_PREFIX/var/slivka-bio

# Start the Slivka stack
slivka start server &
slivka start scheduler &
slivka start local-queue &

Step 4: Verify the service set

Query the API to confirm that the bundled Slivka-Bio services are visible, then run the packaged service tests:

Verify services

# List available service endpoints
curl -s http://localhost:8000/api/services | jq -r '.services[]."@url"'

# Run packaged service tests
slivka test-services

A healthy Slivka-Bio installation should list services such as clustalo, mafft, muscle, jpred, disembl, and tcoffee. If you only see /api/services/example, check that you started Slivka from $CONDA_PREFIX/var/slivka-bio/ rather than from a newly initialised scaffold.

Proxy note: if your shell or container inherits institutional proxy settings, local requests to localhost or 127.0.0.1 may be sent through the proxy. Add --noproxy '*' to the curl command, or set NO_PROXY=localhost,127.0.0.1.

Optional services: some service definitions expect tools that are not bundled with the conda package. For example, IUPred is not included. If you provide it yourself, place the built executable where the packaged service expects it: $CONDA_PREFIX/var/slivka-bio/bin/iupred/. If it is absent, the IUPred service test will fail even though the Slivka server, scheduler, queue, and bundled tools are working.

You're ready for local testing. For more detail, see the Slivka-Bio README and the complete Slivka documentation.

Start a local Docker test stack, make services visible in Jalview when relevant, then use the service configuration guide for implementation details.

Use the Slivka-Bio Docker stack for local testing

Developers can use the Slivka-Bio Docker stack as a fast local target while building clients, notebooks, or new service definitions. It exposes the Slivka API at http://localhost:4040 and keeps the application and MongoDB services together with Docker Compose.

Start the Slivka-Bio Docker stack

# Get the Docker Compose setup
git clone https://github.com/bartongroup/slivka-bio-docker.git
cd slivka-bio-docker

# Start Slivka-Bio and MongoDB
docker compose up -d

# List available service endpoints
curl -s http://localhost:4040/api/services | jq -r '.services[]."@url"'

Point local clients at http://localhost:4040, then use docker compose down when you are finished.

Add Jalview-compatible Slivka services

This is the route for making your own alignment service appear directly in Jalview menus. Jalview Develop can discover suitable Slivka services and list them under Web Service > Slivka > Alignment. For alignment workflows, the service definition needs metadata that identifies the operation, an input that accepts FASTA, and an alignment output that Jalview can open.

Step 1: Install your tool alongside Slivka

Install your command-line application inside the same environment or container as the Slivka server, or make it available on the Slivka server's PATH. Then add a service YAML file that maps Slivka inputs and outputs onto the command. You can use the existing Slivka-Bio installer service definitions as templates.

Step 2: Add Jalview-recognisable metadata

For a multiple sequence alignment service, include the sequence-analysis classifiers, declare the input as FASTA, and declare the main alignment output as either Clustal or FASTA:

Jalview-compatible service fields

classifiers:
- 'Topic :: Computational biology :: Sequence analysis'
- 'Operation :: Analysis :: Sequence analysis :: Sequence alignment :: Multiple
  sequence alignment'

parameters:
  input:
    type: file
    media-type: application/fasta

outputs:
  alignment:
    path: output.aln
    media-type: application/clustal  # or application/fasta

See the production-style ClustalO and MUSCLE 5.1 service definitions for complete examples.

Step 3: Connect Jalview to your server

Start your Slivka server, then add its URL in Jalview Develop under Slivka Services. On macOS use Settings > Slivka Services > New Service URL; on Windows use Tools > Preferences > Slivka Services > New Service URL.

For the full Slivka service schema, see Configure new services below. This section focuses only on the metadata and media types Jalview needs to recognise alignment services.

Configure new services

Service YAML files start with metadata such as slivka-version, name, description, author, version, license, and any classifiers. Slivka reads these fields to publish the service identity consistently across the UI, REST schema, and job logs.

The parameters section defines each input by key, covering type (for example file, boolean, int, text[]), display name, description, and validation such as required, default, min, or max. Slivka uses this block to generate forms, client validators, and OpenAPI schemas. Combine it with command and args to map inputs onto the underlying executable, including helpers like symlink, join, constants, or direct substitution for arguments.

Below is an excerpt of the production clustalo.service.yaml showing how those sections line up in a real deployment.

ClustalO service excerpt

---
slivka-version: 0.8.3
name: ClustalO
description: Clustal Omega is the latest addition to the Clustal family.
author: Fabian Sievers et al.
version: "1.2.4"

parameters:
  input:
    name: Input file
    type: file
    required: true
    media-type: application/fasta
  full-distance:
    name: Full distance matrix
    type: boolean
    default: false

command:
- clustalo

args:
  input:
    arg: --infile=$(value)
    symlink: input.txt
  _const0:
    arg: --outfile=output.txt
    default: present

outputs:
  alignment:
    path: output.txt
    media-type: application/clustal

execution:
  runners:
    default:
      type: SlivkaQueueRunner

tests:
- applicable-runners: ["default"]
  parameters:
    input: ${SLIVKA_HOME}/testdata/uniref50.fa

Declare produced files in outputs (paths and optional media types), select runners through the execution section, and capture quick regression checks under tests. Start by cloning the Slivka-Bio services directory, compare real configs like clustalo.service.yaml with the mock tutorial service, then adapt one to your environment. Need deeper guidance? Refer back to the framework overview or jump straight to the full Slivka documentation.