Cli

<p align="center"> <img src="https://user-images.githubusercontent.com/1233275/172015327-7234ec48-fe57-4a7b-b48e-baf5e6d67aab.png" alt="recode" width="180" height="180" /> </p> <p align="center"> <h1 align="center">Recode</h1> <p align="center">Remote development environments defined as code. Running in your cloud provider account.<br/> Currently available on <a href="https://github.com/recode-sh/aws-cloud-provider">Amazon Web Services</a> and Visual Studio Code.</p> </p> <blockquote align="left"> ... you can think of it as a desktop version of Gitpod / Coder / GitHub Codespaces less polished and with less features but 100% free, 100% open-source and 100% community-driven </blockquote>

recode aws start recode-sh/workspace --instance-type t2.medium

https://user-images.githubusercontent.com/1233275/172346442-d6fef09c-2ef0-4633-8d72-e20bef8fc1a9.mp4

<img width="1136" alt="vscode" src="https://user-images.githubusercontent.com/1233275/172015213-0ba516b6-fe24-4bd4-8ad4-d876c6188f3c.png"> <blockquote align="left"> ... see the <a href="https://github.com/recode-sh/workspace">recode-sh/workspace</a> repository for an example of development environment configuration </blockquote>

Table of contents

• Requirements
• Installation
• Usage
  • Login
  • Start
  • Stop
  • Remove
  • Uninstall
• Development environments configuration
  • Tip: the --rebuild flag
  • Tip: Docker & Docker compose
  • User configuration
  • Project configuration
    • What if I don't have an user configuration?
  • Recode configuration
    • Base image (recode-sh/base-dev-env)
    • Visual Studio Code extensions
    • Multiple repositories
    • Build arguments (RECODE_INSTANCE_OS and RECODE_INSTANCE_ARCH)
    • Hooks
• Frequently asked questions
  • How does it compare with GitPod / Coder / Codespaces / X?
  • How does it compare with Vagrant / VSCode remote SSH / Container extensions?
  • Why using Docker as a VM and not something like NixOS, for example?
  • Given that my dev env will run in a container does it mean that it will be limited?
• The future
• License

Requirements

The Recode binary has been tested on Linux and Mac. Support for Windows is theoretical (testers needed 💙).

Before using Recode, the following dependencies need to be installed:

• Visual Studio Code (currently the sole editor supported).

• OpenSSH Client (used to access your development environments).

Installation

The easiest way to install Recode is by running the following command in your terminal:

curl -sf https://raw.githubusercontent.com/recode-sh/cli/main/install.sh | sh -s -- -b /usr/local/bin latest

This command could be run as-is or by changing:

• The installation directory by replacing /usr/local/bin with your preferred path.

• The version installed by replacing latest with a specific version.

Once done, you could confirm that Recode is installed by running the recode command:

recode --help

Usage

To begin, run the command "recode login" to connect your GitHub account.	

From there, the most common workflow is:

  - recode <cloud_provider> start <repository>  : to start a development environment for a specific GitHub repository
  - recode <cloud_provider> stop <repository>   : to stop a development environment (without removing your data)
  - recode <cloud_provider> remove <repository> : to remove a development environment AND your data
  
<repository> may be relative to your personal GitHub account (eg: cli) or fully qualified (eg: my-organization/api).

Usage:
  recode [command]

Available Commands:
  aws         Use Recode on Amazon Web Services
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  login       Connect a GitHub account to use with Recode

Flags:
  -h, --help    help for recode
  -v, --version version for recode

Use "recode [command] --help" for more information about a command.

Login

recode login

To begin, you need to run the login command to connect your GitHub account.

Recode requires the following permissions:

• "Public SSH keys" and "Repositories" to let you access your repositories from your development environments.

• "GPG Keys" and "Personal user data" to configure Git and sign your commits (verified badge).

All your data (including the OAuth access token) are only stored locally in ~/.config/recode/recode.yml (or in XDG_CONFIG_HOME if set).

The source code that implements the GitHub OAuth flow is located in the recode-sh/api repository.

Start

recode <cloud_provider> start <repository>

The start command creates and starts a development environment for a specific GitHub repository.

If a development environment is stopped, it will only be started. If a development environment is already started, only your code editor will be opened.

An --instance-type flag could be passed to specify the instance type that will power your development environment. (See the corresponding cloud provider repository for default / valid values).

Examples

recode aws start recode-sh/workspace

recode aws start recode-sh/workspace --instance-type t2.medium

Stop

recode <cloud_provider> stop <repository>

The stop command stops a started development environment.

Stopping means that the underlying instance will be stopped but <ins>your data will be conserved</ins>. You may want to use this command to save costs when the development environment is not used.

Example

recode aws stop recode-sh/workspace

Remove

recode <cloud_provider> remove <repository>

The remove command removes an existing development environment.

Removing means that the underlying instance <ins>and all your data</ins> will be <ins>permanently removed</ins>.

Example

recode aws remove recode-sh/workspace

Uninstall

recode <cloud_provider> uninstall

The uninstall command removes all the infrastructure components used by Recode from your cloud provider account. (See the corresponding cloud provider repository for details).

Before running this command, all development environments need to be removed.

Example

recode aws uninstall

Development environments configuration

If you think about all the projects you've worked on, you may notice that you've:

• a set of configuration / tools used for all your projects (eg: a preferred timezone / locale, a specific shell...);

• a set of configuration / tools specific for each project (eg: docker compose, go >= 1.18 or node.js >= 14).

This is what Recode has tried to mimic with user and project configuration.

💡 Tip: the --rebuild flag

recode aws start recode-sh/workspace --rebuild

If you update the configuration of an existing development environment, you could use the --rebuild flag of the start command to rebuild it without having to delete it first.

💡 Tip: Docker & Docker compose

Docker and Docker compose are already preinstalled in all development environments so you don't have to install them.

User configuration

User configuration corresponds to the set of configuration / tools used for all your projects. To create an user configuration, all you need to do is to:

1. Create a <ins>repository</ins> named .recode in your personal GitHub account.

2. Add a file named dev_env.Dockerfile in it.

The file dev_env.Dockerfile is a regular Dockerfile except that:

• it must derive from recode-sh/base-dev-env (more below);

• the user configuration needs to be applied to the user recode.

Otherwise, you are free to do what you want with this file and this repository. You could see an example with dotfiles in recode-sh/.recode and use it as a GitHub repository template:

# User's dev env image must derive from recodesh/base-dev-env.
# See https://github.com/recode-sh/base-dev-env/blob/main/Dockerfile for source.
FROM recodesh/base-dev-env:latest

# Set timezone
ENV TZ=America/Los_Angeles

# Set locale
RUN sudo locale-gen en_US.UTF-8
ENV LANG=en_US.UTF-8
ENV LANGUAGE=en_US:en 
ENV LC_ALL=en_US.UTF-8

# Install Zsh
RUN set -euo pipefail \
  && sudo apt-get --assume-yes --quiet --quiet update \
  && sudo apt-get --assume-yes --quiet --quiet install zsh \
  && sudo rm --recursive --force /var/lib/apt/lists/*

# Install OhMyZSH and some plugins
RUN set -euo pipefail \
  && sh -c "$(curl --fail --silent --show-error --location https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" \
  && git clone --quiet https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions \
  && git clone --quiet https