Moving to Coder v2

Coder v2 is Coder's open core remote development platform first launched in June 2022. Coder v2 has an open-source "OSS" and an Enterprise paid edition. This document shares best practices for moving your workflows from Coder v1 to Coder v2.

If you are current a Coder v1 customer and would like to try Coder v2, contact your account executive or contact us.

High-level concepts

Coder v2 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 v2 documentation

Migration Strategy

A separate control plane is necessary to run Coder v2. A direct upgrade via Helm is not possible since Coder v2 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 v2 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 v2

CLI

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

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

# Coder v1 CLI
coder workspaces list

# Coder v2 CLI
coderv2 list

Users

Like Coder v1, you can enable SSO via OpenID Connect so that any user in your federation can log in. Coder v2 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.

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

Workspaces

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

• Docs: Adding templates

We recommend manually creating a new workspace in Coder v2 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 v2 CLI
2. Create a Coder v2 workspace
3. rsync your files to the new workspace

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

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

# Create a workspace
coderv2 create <workspace-name>

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

# Copy your home directory into the new Coder v2 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 v2. Refer to this comparison:

Developer experience

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

Enterprise/management

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

See the v1 sunset frequently asked questions for more information.