LabLink

Cloud-based virtual teaching lab accessible through Chrome browser.

---

📦 What's in This Repository

This repository contains the core LabLink packages, Docker images, and documentation:

Python Packages

Published to PyPI:

• lablink-allocator - VM Allocator Service

  pip install lablink-allocator-service

• lablink-client - Client Service

  pip install lablink-client-service

Not yet on PyPI — install from source:

• lablink-cli - Command-line tool to deploy and manage LabLink infrastructure

  git clone https://github.com/talmolab/lablink.git
  cd lablink && uv sync --all-packages

Docker Images (Published to GHCR)

Production images are built from the PyPI packages:

• lablink-allocator-image - Allocator service container

  docker pull ghcr.io/talmolab/lablink-allocator-image:latest

• lablink-client-base-image - Client service container

  docker pull ghcr.io/talmolab/lablink-client-base-image:latest

Available Tags:

• latest - Latest stable release
• linux-amd64-latest - Latest for specific platform
• <sha> - Specific git commit
• linux-amd64-test - Development/testing builds
• <version> (e.g., 0.1.2) - Only published when a build is triggered manually

See Docker Image Tags for complete tagging strategy.

Documentation

• LabLink Docs - Comprehensive documentation
  • Getting Started
  • Configuration
  • API Reference
  • Contributing Guide

---

🚀 Quick Start

Two Deployment Paths

	Path A — CLI (recommended)	Path B — Template fork
Install	uv sync --all-packages	Fork lablink-template
Configure	Interactive TUI (lablink configure)	Edit lablink.yaml by hand
Deploy	lablink deploy	terraform apply
Best for	Most users	Custom Terraform workflows

Using the CLI

# Install from source (see docs/cli/installation.md)
git clone https://github.com/talmolab/lablink.git
cd lablink && uv sync --all-packages
source .venv/bin/activate

# Interactive configuration wizard (Textual TUI)
lablink configure

# Validate your environment
lablink doctor

# Deploy the allocator
lablink setup   # S3 bucket + DynamoDB lock table for Terraform state (run by `configure`)
lablink deploy  # provision the allocator

# Add clients
lablink client launch --num-vms 5   # AWS: allocator provisions client VMs
lablink client register             # manual provider: register a bring-your-own box

# Monitor
lablink status  # check running infrastructure
lablink logs    # live log viewer (Textual TUI)

For Developers

Contributing to LabLink packages:

# Clone the repository
git clone https://github.com/talmolab/lablink.git
cd lablink

# Install uv (recommended Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all three packages into one shared venv at the repo root.
uv sync --all-packages --extra dev

See the Contributing Guide for detailed development instructions.

---

📚 Documentation

• Full Documentation - Complete guide
• Architecture - System design
• Configuration - Configuration options
• API Reference - Package APIs
• Contributing - Contribution guide

---

🏗️ Repository Structure

lablink/
├── packages/
│   ├── allocator/                           # Allocator Python package
│   │   ├── src/lablink_allocator_service/   # Source code
│   │   │   └── terraform/                   # Client VM Terraform (part of package)
│   │   ├── tests/                           # Unit tests including Terraform tests
│   │   ├── Dockerfile                       # Production image (from PyPI)
│   │   └── Dockerfile.dev                   # Development image (local code)
│   ├── client/                              # Client Python package
│   │   ├── src/lablink_client_service/      # Source code
│   │   ├── tests/                           # Unit tests
│   │   ├── Dockerfile                       # Production image (from PyPI)
│   │   └── Dockerfile.dev                   # Development image (local code)
│   └── cli/                                 # CLI Python package (Typer + Textual)
│       ├── src/lablink_cli/                 # Source code (commands, TUI, config)
│       └── tests/                           # Unit tests
├── docs/                                    # MkDocs documentation
└── .github/workflows/                       # CI/CD workflows
    ├── ci.yml                               # Tests, linting, Docker builds
    ├── publish-pip.yml                      # PyPI publishing
    ├── lablink-images.yml                   # Docker image builds & pushes
    └── docs.yml                             # Documentation deployment

Note: Infrastructure deployment code (allocator EC2, DNS, etc.) has been moved to lablink-template.

---

📦 Package Versioning

LabLink uses independent versioning for its packages:

• lablink-allocator-service:
• lablink-client-service:
• lablink-cli: not yet published to PyPI (install from source)

---

🤝 Contributing

We welcome contributions! Please see:

• Contributing Guide - How to contribute
• Developer Guide (CLAUDE.md) - Developer-focused overview
• Code of Conduct - Community guidelines

Quick Contributing Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run tests: cd packages/allocator && uv run pytest
5. Commit: git commit -m "feat: add my feature"
6. Push and open a Pull Request

---

🔗 Related Repositories

• LabLink Template - Infrastructure deployment template using LabLink packages

---

📝 License

BSD-2-Clause License

---

🙏 Acknowledgments

LabLink is developed by the Talmo Lab for the research community.

---

Questions? Check the FAQ or open an issue.