12  Installing an Operator

Once your operator is tested and documented, the final step is making it available to users through Tercen’s library system. This chapter covers the installation process, library management, and best practices for deploying operators to production environments.

NoteWhat You’ll Learn
  • Understanding Tercen’s library system
  • Creating and managing custom libraries
  • Installing operators from Git repositories
  • Library access control and permissions
  • Operator versioning and updates

12.1 Understanding Tercen Libraries

Tercen uses a library system to organize and distribute computational modules. Libraries provide a structured way to manage operators, templates, apps, and datasets while controlling access and maintaining quality standards.

12.1.1 Library Types

Library Type Description Use Case Access
Tercen Library Official curated collection Production-ready operators Public
Custom Libraries Team or organization specific Internal/specialized operators Controlled
Personal Libraries Individual developer libraries Development and testing Private
ImportantLibrary Architecture

Libraries in Tercen are implemented as specialized teams where: - The team itself represents the library - Projects within the team become available operators - Team permissions control library access - Git integration enables automated updates

12.2 Setting Up a Custom Library

12.2.1 Library Creation Process

  1. Create a New Team
    • Navigate to your Tercen account dashboard
    • Click “Teams” → “Create New Team”
    • Choose a descriptive name (e.g., “MyOrganization Operators”)
  2. Configure as Library Team
    • Go to team settings
    • Enable “Library team” option
    • Configure team visibility and permissions
  3. Set Access Permissions
    • Add team members as needed
    • Configure read/write permissions
    • Set up approval workflows if required
TipLibrary Naming Best Practices
  • Use organization or project names for clarity
  • Include purpose in the name (e.g., “BioinformaticsLab Operators”)
  • Avoid generic names like “MyLibrary” or “TestLib”
  • Consider future growth and additional content types

12.3 Installing Operators

12.3.1 Git Integration Method

Tercen’s preferred method for operator installation uses direct Git integration:

  1. Navigate to Your Library

    • Access your custom library (team)
    • Ensure you have appropriate permissions

  2. Add New Project

    • Click “New Project”
    • Select “From Git”

  3. Configure Repository Details

    Name:       my_analysis_operator
URL:        https://github.com/myorg/my_analysis_operator
Tag:        1.0.0 (optional - for specific versions)
Auth Token: ghp_xxxxx (classic PAT, only if repository is private)
ImportantPrivate repos: use a classic token here

The Auth Token is used by the Tercen server to download the repo’s zipball from github.com. That endpoint accepts classic tokens (ghp_..., repo scope) but rejects fine-grained tokens (github_pat_...) — a fine-grained token fails with a 404 even when its permissions are correct.

ImportantPrivate image? Bring your own registry credential

A private container image needs a second credential, separate from the Auth Token above — and Tercen never provisions one. The user mints their own classic PAT with read:packages (SSO-authorize for the org) and attaches it at install — nothing Tercen-side. In detail:

  • Classic token, read:packages — pull access to the image’s ghcr namespace. The username attached alongside it must be the token’s owner.
  • SSO authorization — if the image’s GitHub organization uses SSO, authorize the token for that org; an SSO-unauthorized token cannot pull even with correct scopes.
  • Attached at install, task-scoped — the credential rides the install task, is used by Tercen’s worker to pull the image, and is cleared when the install task finishes. Nothing is kept for reuse between installs.
  • ghcr.io only — the proven registry for private-image installs. Docker Hub credentials are a separate, not-yet-supported lane.
  • Trust boundary unchanged — the credential enables the pull; it does not widen it. The image must still live in a trusted registry namespace (see the CI chapter).

Attachment surface today: the credential, the declared registry host, and the username ride the install task’s registry metadata through the install API; a dedicated field in the install dialog is tracked as follow-up work.

  1. Complete Installation
    • Review settings
    • Click “Create Project”
    • Wait for repository cloning and validation
WarningAuthentication Requirements

For private repositories, you’ll need: - Personal Access Token (PAT) for GitHub - Appropriate repository permissions - Token with repo scope for full access

For private images, additionally attach your own classic PAT with read:packages (+ org SSO) at install — see the Private image? Bring your own registry credential callout above.

ImportantTrusted Organization Requirement

On managed Tercen instances, the repository must live in a trusted GitHub organization (ask your Tercen admin which — commonly github.com/tercen/ and github.com/pamgene/). Repositories under personal accounts or untrusted organizations are rejected with tercen.forbidden.untrusted.git. The myorg placeholder above must be a trusted organization on such instances.

Note also that “From Git” only installs a searchable operator when the repository name ends in _operator, is lowercase, and the container image is pullable. Otherwise the files are copied but the operator will not appear in the picker — see My operator doesn’t appear in the picker.

12.4 Operator Availability and Testing

12.4.1 Verification Steps

After installation, verify your operator is working correctly:

  1. Check Library Listing
    • Confirm operator appears in library
    • Verify metadata is displayed correctly
  2. Test in Workflow
    • Create a new workflow
    • Add a data step
    • Search for your operator
    • Test with sample data
  3. Validate Functionality
    • Run with different input configurations
    • Verify output correctness
    • Check error handling

12.5 Version Management

12.5.1 Operator Updates

To update an installed operator:

  1. Push changes to Git repository
  2. Tag new version (recommended)
  3. Trigger library refresh in Tercen

12.5.2 Version Control Best Practices

  • Use semantic versioning (e.g., 1.0.1)
  • Tag stable releases in Git

12.6 Next Steps

With your operator successfully installed and available to users, consider:

  • Monitoring usage patterns and feedback
  • Planning feature enhancements based on user needs
  • Exploring advanced deployment automation