Run a local workspace using the .gitpod.yml

  • By Gitpod
  • Last update: Dec 22, 2022
  • Comments: 17

rungp Logo
run-gp
Run local workspaces using the .gitpod.yml

Gitpod ready-to-code Discord

run-gp is a CLI tool for running workspaces based on a .gitpod.yml file locally on your machine. Using a local working copy it produces a workspace image, and starts that workspace. This provides an experience akin to a regular Gitpod workspace.

Warning This is an experiment. When you find an issue, please report it so that we can improve this project.

Note run-gp is not the "real Gitpod experience". Gitpod offers remote development environments which sport many benefits compared to running things locally. Head over to https://www.gitpod.io to find out more.

Features

  • ✅ Image Build: run-gp produces a workspace image based on the image section in the .gitpod.yml. If no such section exists, gitpod/workspace-full:latest is used.
  • ✅ Browser Access: by default we'll start Open VS Code server to provide an experience akin to a regular Gitpod workspace. This means that a run-gp workspace is accessible from your browser.
  • ✅ SSH Access: if your user has an SSH key (~/.ssh/id_rsa.pub file) present, the run-gp workspace will sport an SSH server with an appropriate entry in authorized_keys. This means that you can just SSH into the run-gp workspace, e.g. from a terminal or using VS Code.
  • ✅ VS Code extension installation: VS Code extensions specified in the .gitpod.yml will be installed when the workspace starts up. Those extensions are downloaded from Open VSX, much like on gitpod.io.
  • ✅ Tasks configured in the .gitpod.yml will run automatically on startup.
  • ✅ Ports configured in the .gitpod.yml will be made available on startup. There is no dynamic port exposure you might expect from a Gitpod workspace.
  • ✅ Airgapped startup so that other the image that's configured for the workspace no external assets need to be downloaded. It's all in the run-gp binary.
  • ✅ Auto-Update which keeps run-gp up to date without you having to worry about it. This can be disabled - see the Config section below.
  • ⚠️ Docker-in-Docker depends on the environment you use run-gp in. It does not work yet on MacOS and when run-gp is used from within a Gitpod workspace.
  • ⚠️ JetBrains Gateway support also depends on the environment run-gp is used in. It is known NOT to work on arm64 MacOS.
  • ⏳ gp CLI is coming in a future release.
  • ❌ Gitpod Prebuilds are unsupported because this tool is completely disconnected from gitpod.io.
  • ❌ Gitpod Backups are unsupported because this tool is completely disconnected from gitpod.io.

Getting Started

  1. Download the [latest release](https://github.com/gitpod-io/run-gp/releases/latest).
    If you're on MacOS you'll need to jump through hoops because the run-gp releases are not signed. MacOS requires that binaries downloaded using a browser must be [signed and notarized](https://developer.apple.com/developer-id/). Otherwise you won't be able to just execute the `run-gp` command. If you download the release using `curl` in a terminal, MacOS will just let you execute the binary. Alternatively, you can head over to the `Security` system settings and allow the binary to run once MacOS denied this on the first attempt.

  2. In a terminal navigate to a directory containing a .gitpod.yml file, e.g. a Git working copy of a repository, then execute run-gp.

    git clone https://github.com/gitpod-io/go-gin-app
cd go-gin-app
run-gp

    Note: The run-gp command will use the current working directory as context. To point it to a different directory, use the -w option.

  3. Once the workspace is ready, open the URL displayed in the terminal.

Configuration

run-gp does not have a lot of configuration settings, as most thinsg are determined by the .gitpod.yml. You can find the location of the configuration file using

run-gp config path

Auto Update behaviour

By default run-gp will automatically update itself to the latest version. It does that by checking the GitHub releases of the run-gp repository for a new release. To disable this behaviour run:

run-gp config set autoUpdate.enabled false

Telemetry

By default run-gp will send anonymous telemetry. We never send identifiable details such as usernames, URLs or the like. You can review all data ever being transmitted in the sources. To disable telemetry run:

run-gp config set telemetry.enabled false

run-gp respects Console Do Not Track, i.e. export DO_NOT_TRACK=1 will also disable telemetry.

Frequently Asked Questions

  • This readme refers to run-gp as experiment. What does that mean?

    This means that run-gp is not a polished product. Instead it's an attempt to ship a 🛹 , i.e. an MVP that explores how local Gitpod-like workspaces would look like. This repository is not backed by a regular product team, but instead a product exploration effort.

  • The performacne on my M1 Mac is terrible, what can I do?

    Until the release of MacOS 13, Docker Desktop (and any other Linux VM) will be rather slow on arm64 hardware. It's unlikely we'll produce an arm64 version of Gitpod before (if ever) MacOS 13 comes out. Your best chance is to find an x86 machine, or wait for the release of MacOS 13.

Download

run-gp.zip

Comments(17)

  • 1

    Messy but effective option to just build the image.

    Description

    Added CLI option to not start the image once built.

    Related Issue(s)

    use the tool to allow automated creation of docker images which can then be transfered into an airgapped environment.

    Fixes #

    How to test

    use the badge to start run-gp in gitpod ./run-gp run --do-not-run docker images see that the image was created but that you are still in your original gitpod environment.

    Release Notes

    ```CLI Option --do-not-start created to stop after image creation

    
## Documentation
<!--
Does this PR require updates to the documentation at www.gitpod.io/docs?
* No
  • 2

    Getting started fails on Windows 11

    Describe the bug

    Following Getting Started with v0.1.5 on Windows 11 output the following error message

     ❯  .\run-gp_0.1.5_Windows_amd64.exe

    _______  ______     ____ _____
   / ___/ / / / __ \   / __ `/ __ \
  / /  / /_/ / / / /  / /_/ / /_/ /
 /_/   \__,_/_/ /_/   \__, / .___/
                     /____/_/

  FAILURE  [building] workspace image (4.311s)
           workspace image build failed
                chown -R 33333:33333 /workspace
        ENV EDITOR="/ide/bin/remote-cli/gitpod-code"
 ENV VISUAL="/ide/bin/remote-cli/gitpod-code"
 ENV GP_OPEN_EDITOR="/ide/bin/remote-cli/gitpod-code"
 ENV GIT_EDITOR="/ide/bin/remote-cli/gitpod-code --wait"
 ENV GP_PREVIEW_BROWSER="/ide/bin/remote-cli/gitpod-code --preview"
 ENV GP_EXTERNAL_BROWSER="/ide/bin/remote-cli/gitpod-code --openExternal"
 invalid argument "local\\workspace-image:latest" for "-t, --tag" flag: invalid reference format
 See 'docker build --help'.

 Press q to quit
segment 2022/06/22 20:45:08 ERROR: sending request - Post "https://api.segment.io/v1/batch": dial tcp: lookup api.segment.io: getaddrinfow: The requested name is valid, but no data of the requested type was found.
segment 2022/06/22 20:45:08 ERROR: 1 messages dropped because they failed to be sent and the client was closed

    To Reproduce Steps to reproduce the behavior:

    1. Clone run-gp repository to have .gitpod.yml
    2. Download and copy run-gp_0.1.5_Windows_amd64.exe from the release page
    3. Copy run-gp_0.1.5_Windows_amd64.exe in the local clone folder
    4. From powershell navigate to the clone directory and execute run-gp_0.1.5_Windows_amd64.exe

    Expected behavior Once the workspace is ready, a URL should be displayed in the terminal.

    Desktop (please complete the following information):

    • OS: Windows 11 Pro
    • CPU: amd64
    • Version: 21H2, 22000.739

    Additional context Docker version 20.10.16, build aa7e414

  • 3

    Make MacOS binaries easier to execute

    Is your feature request related to a problem? Please describe. The run-gp binary isn't signed which means that users need to go through several steps (which they need to discover themselves) before run-gp works for them. That's far from smooth.

    Describe the solution you'd like Several ways we could solve this (ordered by expected effort):

    1. update the readme to point this problem our, promote curlin the binary to circumvent the issue, and offering a loom on how to navigate the security settings.
    2. provide a homebrew installation which also circumvents this issue
    3. notarize the released binaries which is considerable effort
  • 4

    [Experimental] Improvements on docker + logs

    Description

    This PR adds:

    • [x] terminates previosuly created rungp containers when running preflight, this is useful when the go program fails to stop the docker container
    • [x] re-introduce the bubble logs for preflight but with some differences (e.g Docker logs are streamed to stdout to keep the native progress animations)
    • [x] make sure to catch when the go program exists and try to kill the docker container

    Related Issue(s)

    Fixes #

    How to test

    Release Notes

    Documentation

  • 5

    Make auto-update behaviour clearer

    Description

    Related Issue(s)

    Fixes #25

    How to test

    Release Notes

    Documentation

  • 6

    Post auto-update behaviour is unclear

    Describe the bug I.e. if the new version is used right away, or if a restart is required.

    Expected behavior The new version should be used right away.

  • 7

    Remove local/ suffix from docker tag name

    Description

    local/ suffix fails on Windows with invalid argument "local\workspace-image:latest" for "-t, --tag" flag: invalid reference format

    Related Issue(s)

    Fixes #22

    How to test

    Follow Getting started from the README on a Windows 11 machine

    Release Notes

    * Fix building docker image for Windows 11

    Documentation

  • 8

    Support starting a workspace from directories without a .gitpod.yml

    Is your feature request related to a problem? Please describe. Today the workdir needs to have a .gitpod.yml for run-gp to work.

    Describe the solution you'd like Calling run-gp on a directory without a .gitpod.yml could search up the directory tree for such a file. If it doesn't find one, we'd start with an "empty" default config.

  • 9

    [docs] The workdir flag may be confusing

    Is your feature request related to a problem? Please describe. Today one needs to know of the workdir concept, and that run-gp implicitly uses the current directory - much like yarn or go. If that workdir needs to be changed, one can do that with -w. This is not always clear to users as exemplified here:

    Would it make sense to not require the -w flag for specifying the working dir? It took a while for me to realize it from the help message. I was initially expecting it to be like run-gp <dir>. I think this design is present in most CLIs where the PATH is mandatory(does not explicitly require an arg to define it) and others(options/switches) are optional. However, run-gp takes the current dir as the workdir, which is nice if you're already inside the project dir

    Describe the solution you'd like We should provide clear documentation as to the behaviour of run-gp. Considering that the directory is not mandatory, it makes sense to keep it as a flag.

  • 10

    Wrong workspace folder when no `checkoutLocation` is specified

    Describe the bug Logged workspace location of run-gp is not correct (always http://localhost:8080/?folder=/workspace, but we need http://localhost:8080/?folder=/workspace/<folder_name>

    To Reproduce Steps to reproduce the behaviour:

    1. Open this repo in run-gp
    2. Proposed URL should end with /workspace/run-gp instead of /workspace
  • 11

    Write a readme

    which explains

    • what run-gp is for, and what it isn't
    • how to install run-gp
    • how we do telemetry and how to disable it,
    • how we do auto-updating and how to disable it.
  • 12

    Fix #40

    Description

    This keeps track of the allocated host ports in the docker run command and reports conflicts with (as best it can) where they came from. Related to that, in actually checks that the port: value in .gitpod.yml is in fact an int rather than just assuming it so. Finally, it also stops swallowing err from the actual Start Workspace invocation

    Related Issue(s)

    Fixes #40

    How to test

    • checkout main
    • build
    • run with the cited example repo's .gitpod.yml
    • observe the failure to launch
    • checkout this branch
    • repeat that exercise and observe there is now a helpful message showing the conflict

    Release Notes

    Documentation

  • 13

    lax port management causes confusing error messages

    Describe the bug

    Because the docker run uses multiple host ports, including potentially user-declared ones from .gitpod.yml, it can easily get into a situation where they conflict. However, the reported error to the user is

    time="2022-12-16T18:57:57-08:00" level=error msg="[starting] workspace image done" duration=357.860717ms failure="docker: Error response from daemon: driver failed programming external connectivity on endpoint rungp-1671245876866762152 (1d3b07052b0809dc49d4a0ae7dcdb3bfc017f706ae675a091e640ad068034768): Bind for 0.0.0.0:8080 failed: port is already allocated."

    without any context of why that happened or what action the user can take to resolve it

    To Reproduce Steps to reproduce the behavior:

    1. Download or build run-gp v0.1.7
    2. Change into the suggested go-gin-app directory containing an existing .gitpod.yml
    3. Execute run-gp (optionally with a bunch of --verbose to see what's up)
    4. Observe the bad outcome because "--ide-port int port to expose open vs code server (default 8080)" and the 8080 port in .gitpod.yml collide in the docker run -p 8080:22999 ... -p 8080:8080 workspace-image:latest (it could have happened with the SSHPort, also, it just happened that the getting-started repo and the default IDEPort collided

    Expected behavior

    My patched version emits:

    time="2022-12-16T19:08:08-08:00" level=warning msg="unable to Start Workspace: PortForwarding collision on 8080 (originally 8080) with opts.IDEPort"

    because:

    • the StartWorkspace func keeps track of host port allocation and asserts they do not collide
    • the RunE go func stops swallowing err
    • I had to patch run-gp to log the docker run command to even start to investigate this bug

    Screenshots If applicable, add screenshots to help explain your problem.

    Desktop (please complete the following information):

    • OS: Linux
    • CPU: amd64
    • Browser N/A
    • Version v0.1.7

    Additional context As mentioned, I have a potential fix for this, and will try to open a PR for it later but wanted to type this up while I had all the context in front of me

  • 14

    Add shell script for easy install

    Description

    Adds a POSIX compliant shell script to be used from terminal in combination with curl and wget pipe to easily install run-gp. Porting over from this bash script 😛

    • [ ] TODO: Detect OS and CPU-arch
    • [ ] TODO: Check whether curl or wget is available
    • [ ] TODO: Finally download the binary

    Related Issue(s)

    Fixes #

    How to test

    Release Notes

    Documentation

  • 15

    Clarification needed on plans to support D-in-D & IntelliJ on Macs (incl arm64)

    Hi,

    This FR is about the following two known limitations:

    ⚠️ Docker-in-Docker depends on the environment you use run-gp in. It does not work yet on MacOS and when run-gp is used from within a Gitpod workspace. ⚠️ JetBrains Gateway support also depends on the environment run-gp is used in. It is known NOT to work on arm64 MacOS.

    Can you please help us better understand the reasons of these limitations, as well as future plans to overcome / fix them?

    Update: I ran a project with "run-gp" and I see all processes are running with QEMU x86-64, which makes things slower and I guess the IntelliJ agent is incompatible. I also saw the Docker-in-Docker issue, docker cli in the workspace cannot connect to the host's docker socket.

    Asking since these limitations affect almost 100% of our use-cases:

    • all our devs are on Macs, with a fast increasing portion using arm64
    • the vast majority of our devs using IntelliJ
  • 16

    Is there a way to have git user name/email automatically set?

    Every time we open a new instance of run-gp, git config user.name and git config user.email are empty, preventing us from committing changes before setting them up.

    Is there currently a way to have them set automatically?

    If not, it could do one of these things:

    • pick automatically from the host machine during the container startup.
    • make use of env vars like in https://www.gitpod.io/docs/environment-variables/ by:
      • allowing us to load environment variables from a .env file (path provided via argument or found in $(run-gp config path)).
      • allowing us to pass env vars as an argument to run-gp.
      • picking from the host machine based on when the env var starts with GITPOD_ENV_SET_.
  • 17

    Feature Request: Allow passing a repository with dotfiles

    Is your feature request related to a problem? Please describe the solution you'd like.

    It would be great to have dotfiles installed automatically like we can do on gitpod.io.

    Screenshot from https://gitpod.io/preferences: image

    Maybe we could pass the repo as an argument for run-gp.

    Describe alternatives you've considered

    We can manually clone the dotfiles repo and execute the install script once we're in the environment. But if we could automate it and save some time, run-gp would be even better!

Popular Tag

Related