Skip to main content
Waypoint is an easy-to-setup development environment for Penn Labs products that simplifies onboarding and cross-team collaboration.

​
What is Waypoint?

Waypoint solves the common problems with traditional development setups:
  • Time-consuming initial configuration
  • Inconsistent environments across teams and devices
  • Hard to reproduce when issues arise
Waypoint creates a standardized development environment that:
  • Works across all teams and roles
  • Speeds up onboarding for new developers
  • Makes it easier to switch between projects

​
Features

FeatureDescription
Easy SetupSimple one-liner install to get started quickly
Consistent EnvironmentSame setup for all products, no more “works on my machine” issues
Docker-BasedRun all services in a containerized environment
Cross-PlatformWorks on Mac, Linux, and Windows (with WSL)
Secret ManagementSecrets are mounted securely and persist after container updates
Product SwitchingInstantly switch between product environments

​
Installation

1
Prerequisites
2
Ensure you have the following installed:
3
  • Docker (or OrbStack for Mac)
  • WSL (Windows only, Ubuntu 22.04+)
  • VSCode or Cursor
  • Python 3.11+
    • 4
    Waypoint requires 6-7 GB of free disk space.
    5
    Install waypoint-client
    6
    Install the waypoint-client CLI on your local machine:
    7
    curl -sSL https://raw.githubusercontent.com/pennlabs/infrastructure/refs/heads/add-waypoint/docker/waypoint/install.sh | sudo bash
    8
    Configure Waypoint
    9
    Run the configuration command:
    10
    waypoint-client configure
    11
    This sets up the necessary directories and paths for code, secrets, and SSH keys.
    12
    Start the container
    13
    Launch the Waypoint container:
    14
    waypoint-client start

    ​
    Getting Started

    1
    Attach to the Container
    2
  • Install the VSCode Dev Containers extension
  • Open Command Palette (⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows)
  • Select Dev Containers: Attach to Running Container
    • 3
    Set Up a Product
    4
    Inside the container, initialize your product:
    5
    waypoint services
waypoint init [product] # or just 'waypoint init'
waypoint switch [product]
    6
    Penn-Courses requires a special SQL file for setup.
    7
    Supported Products
    8
    ProductSHAoffice-hours-queue524282d029a330b59158e80299e3be23988f1765penn-clubsd2e5758f1498b17cd3f20d08c37969d3e8c9c7bdpenn-mobileb1a8bfa53a35496c972b880f7e3ab9d93845b614penn-courses723640b1dbb815877c24bb1bc8b729c15e12c87aplatform42c56ff509f60de5389262a9de5e38faf1d9aac2
    9
    Start Developing
    10
    Code and secrets are mounted to your local machine. Any changes made inside /labs will persist after container updates.

    ​
    CLI Commands

    The waypoint-client CLI runs on your local machine and manages the Waypoint container.
    CommandDescription
    waypoint-client configureSet up Waypoint on your local machine
    waypoint-client startStart the container and attach to VSCode
    waypoint-client start --rebuildForce a container rebuild
    waypoint-client spawnOpen a new bash terminal inside the container

    ​
    Dependency Management

    Waypoint uses uv for fast dependency installation and shared dependency management:
    • Dependencies are pinned at build time for consistency
    • Backends are synced with specific Git SHAs (e.g., OHQ → 524282d029a330b59158e80299e3be23988f1765)

    ​
    Updating Dependencies

    1. Bump version by submitting a PR to Waypoint
    2. Run waypoint sync [product] to refresh dependencies

    ​
    Secret Management

    Secrets can be managed like normal with .env files in each project. You can also use the mounted secrets folder to assist with file transfers.

    ​
    Updating Waypoint

    ​
    Update waypoint-client

    Re-run the install command: 
    curl -sSL https://raw.githubusercontent.com/pennlabs/infrastructure/refs/heads/add-waypoint/docker/waypoint/install.sh | sudo bash

    ​
    Update the Container

    Rebuild the container: 
    waypoint-client start --rebuild
    Old containers may need to be deleted manually. Mounted files will persist.

    ​
    Mounted Paths

    Configured with waypoint-client configure:
    PathConfigurationNotes
    /root/.sshMounted from [CONFIG_DIR]/.sshSSH keys
    /root/.gnupgMounted from [CONFIG_DIR]/.gnupgGPG keys
    /labsMounted from [CODE_DIR]Stores repos
    /opt/waypoint/secretsMounted from [SECRETS_DIR]Stores secrets

    ​
    Common Questions

    Changes to mounted folders (code, secrets) will persist. Other local changes (e.g., installing new packages) won’t persist after an update unless you push them.

    ​
    Pro Tips

    Use OrbStack instead of Docker on Mac for better performance.
    Waypoint files are stored at /opt/waypoint. You can go to /cli and modify the .waypoint-bashrc if needed.
    Use waypoint switch [product] to quickly switch environments without reconfiguring.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us