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: github_pat_xxxxx (if repository is private)

  4. 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

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