Moving to Coder OSS

Coder OSS is Coder's open core remote development platform first launched in June 2022. This document shares best practices for moving your workflows from Coder v1 to Coder OSS.

If you are current a Coder v1 customer and would like to try Coder OSS, we'd like to hear from you to help inform our roadmap and migration strategy.

High-level concepts

Coder OSS introduces a number of new paradigms. We recommend reading the comparison table before you proceed.

Keep reading for an in-depth feature comparison. Also see the Coder OSS documentation

Migration Strategy

A separate control plane is necessary to run Coder OSS. A direct upgrade via Helm is not possible since Coder OSS redefines some concepts (e.g. templates, provisioners) and other features are still being developed (e.g. audit log, organization support).

Short term, we recommend keeping your Coder v1 control plane and inviting a pilot group to your Coder OSS control plane to reproduce their workflows and try new features (e.g. Windows support, dynamic secrets, faster builds).

Feature list key

Each of the following features have open issues on coder/coder - if they're a priority for your team, please chime in on the GitHub issue.

✅ = Complete

⌛ = WIP/planned on a roadmap

🤔 = Still considering

❌ = No current plans for feature

Infrastructure

For small "proof-of-concept" deployments, you can use Coder's built-in database and tunnel on a VM to avoid setting up a database, reverse proxy, and TLS.

For production use, we recommend running Coder with an external PostgresSQL database and a reverse proxy for TLS.

• Installing Coder OSS

Something missing, or have feedback? Let us know

CLI

Coder OSS uses a separate command line utility. To use both CLIs on the same machine, you can install the Coder OSS CLI under a different name (e.g. codeross):

curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=codeross > /dev/null

# Coder v1 CLI
coder workspaces list

# Coder OSS CLI
codeross list

Users

Like Coder v1, you can enable SSO via OpenID Connect so that any user in your federation can log in. Coder OSS optionally supports GitHub (Enterprise) and username/password authentication.

If you are interested in a bulk user and/or workspace migration utility, we'd like to hear from you.

Something missing, or have feedback? Let us know

User-wide settings (e.g. shell, autostart times, dotfiles URL) are not currently supported in Coder OSS (#3506).

Workspaces

If you are interested in a bulk user and/or workspace migration utility, we'd like to hear from you.

To migrate Coder v1 workspaces, you'll need at least one template in your Coder OSS deployment, specifically with the image(s) you support in Coder v1.

• Docs: Adding templates

We recommend manually creating a new workspace in Coder OSS and using a utility such as scp or rsync to copy the home directory from your v1 workspace.

Inside a v1 workspace, run the following commands to:

1. Download the Coder OSS CLI
2. Create a Coder OSS workspace
3. rsync your files to the new workspace

# Download the Coder OSS CLI (alias "codeross")
curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=codeross > /dev/null

# Log in to the Coder OSS deployment (e.g. coder-v2.example.com)
codeross login https://coder-v2.example.com

# Create a workspace
codeross create <workspace-name>

# Gain SSH access to v2 workspaces
codeross config-ssh -y

# Copy your home directory into the new Coder OSS workspace
rsync \
    --recursive \
    --itemize-changes \
    --info=progress2 \
    --links \
    --exclude='.cache/' \
    $HOME/. coder.$CODER_WORKSPACE_NAME:/home/coder/.

Some workspace-level features are different in Coder OSS. Refer to this comparison:

Something missing, or have feedback? Let us know

Developer experience

Some developer experience features are different, or still being worked on in Coder OSS. Refer to this table:

Something missing, or have feedback? Let us know

Enterprise/management

Some enterprise features are different, or still being worked on in Coder OSS. Refer to this table:

Something missing, or have feedback? Let us know