Using Gitpod to start a new project

Using Gitpod to start a new project

Ever since I used Gitpod as part of some early access with GitLab I've wanted to use the platform more. The trouble is, I don't have a lot of projects which justify the time setting up a full config just for development. Normally everything I do small scale stuff, like my password validator.

Now I have a project I want to work on which is bigger in scale, I figured it was a great opportunity to use it from the ground up.

What is Gitpod?

Gitpod is an open source developer platform automating the provisioning of ready-to-code development environments. It streamlines developer workflows by providing prebuilt, collaborative development environments in your browser.
Designed for applications running in the cloud, Gitpod frees engineering teams from the friction of manually setting-up local dev environments, saving dozens of hours and enabling a new level of collaboration to create applications much more quickly than ever before.

Natively integrated with GitLab, GitHub, and Bitbucket, Gitpod automatically and continuously prebuilds dev environments for all your branches. As a result team members can instantly start coding with fresh dev environments for each new task - no matter if you are building a new feature, want to fix a bug, or work on a code review.

Gitpod's IDE window

Getting Started

Because I use GitLab as my source control, this article will be based on interactions from within GitLab. It should be fairly adaptable for Github or Bitbucket, if either of those are your preferred source control platform.

As this is a Greenfield project, the first step is to create a repository for it. Within GitLab, I chose to initialise it with a README.md file to allow cloning. From this point, the steps should be the same for new or existing projects wanting to get started with Gitpod.

Launching a Gitpod instance from within GitLab

From the Project Overview "details" page, click on the Gitpod button. This will open the repository's default branch within a new Gitpod workspace. When this opens, Theia (Gitpod's IDE), will detect that there is no .gitpod.yml file, and offer to help you create one.

Gitpod offering assistance creating the .gitpod.yml

Clicking Setup Project will open a side panel which acts as the guide to start the process.

Gitpod side panel for setting up the project

Because Gitpod uses Docker to serve the content for testing and debugging, some level of Docker knowledge is advisable. Or, at the very least, a willingness to learn. Fortunately, learning docker is one of my goals for 2021. You need to be prepared for fiddling round with a Dockerfile (.gitpod.Dockerfile) or accepting the full Gitpod base one to work with. There's more information on configuring this for Gitpod within the official documentation.

When setting up the Dockerfile for the first time, be aware that Gitpod recommend committing the change to a new branch and opening that as a new workspace. If the Dockerfile fails, then the workspace won't open. It will give the option to open using the default Docker image, but doing this on a new branch will not break the branch for others if you are working on an existing project and using Gitpod only as an IDE.

Gitpod error when the Dockerfile can't successfully build

Be aware that if you're using a Debian base image, you may get stuck on configuring tzdata. This is a common issue with Debian based Docker images, and I've covered it before as part of my GitLab CI/CD series.

If you do run into issues with the Dockerfile on a new branch:

  • change the .gitpod.Dockerfile on a different workspace (which is why you should do this part on a different branch)
  • commit the changes
  • refresh the workspace with the Dockerfile errors.

This will restart the workspace and try to build the environment from the Dockerfile. If it is successful, you'll get the IDE screen and be able to build.

From there you can start building your project to your liking. Create your folder structure, and work with your own dependencies.

Additional configuration

If you have additional services as part of your workspace which you need to expose, you will need to configure the ports to expose as part of the configuration. These don't need to be setup as part of an elaborate Docker compose file. Instead you can treat the whole instance as a single server. Just remember to start each service in the .gitpod.yml file under tasks.

The editor itself works a lot like VS Code, which will suit a lot of people out there. Your normal VS Code extensions can be added to the workspace on startup by adding them to the .gitpod.yml file. For instance

vscode:
  extensions:
    - MehediDracula.php-namespace-resolver@1.1.8
    - vscode.php-language-features@1.52.1
    - felixfbecker.php-pack@1.02

You can find the available extensions at the Open VSX Registry.

If you have specific VS Code settings for a language or project they can be brought straight over into Gitpod, as Theia (the IDE) can be configured using the .vscode/settings.json file (which can also be located at .theia/settings.json). This makes it easier to get up and running if you already use VS Code as your IDE.

Things to be aware of

  • If you click on the Gitpod button within your repository, this will always create a new workspace within Gitpod (unless you have a workspace for that branch already open).
  • If you want to open an existing workspace (because there are data there you want to utilise, or any other reason), you need to open the Gitpod workspace dashboard.

Early Conclusion

I've still not done a lot with Gitpod in the grand scheme of things. But getting up and running with it as an IDE and environment isn't that bad so long as you try to strip away the complicated parts. You don't need to think of it as being full-on Docker where you should have separate containers for each service. Pull them all together and use them as one single container.

There are some things which need to be considered, such as getting Apache up and running. When I tried using the service apache2 start command as part of the .gitpod.yml task, it wouldn't start properly and use the envvars file I had set it to use. I needed to set the task to be command: apache2ctl start. Small things like that will catch you out, and cause a bit of frustration.

My main problem is entirely my own. I've used PhpStorm for so long that the editor simply not working in the way I've built my way of working around slows me down a lot. That's something which will only be resolved with time and with using it. I need to work out (or reconfigure) the shortcuts to be what I am used to, and learn other shortcuts to build my productivity. Simple things like being able to generate any getters and setters, or implement methods from interfaces or abstract classes are things I miss.

If you are just getting started with coding, or are already a VS Code user, this is absolutely something you should try. It will help people contribute to projects in a way which fosters consistency and reliability. Everyone has the same tooling regardless of their background. It lowers the barrier of entry to contributions, as people don't need a high-spec machine to be able to contribute due to the entire stack being within the browser window for them. Most importantly, new contributors don't need to spend hours setting up an environment to allow them to contribute. Just let Gitpod set the environment up, and they can start making changes.

I'll more than likely split between Gitpod and PhpStorm for my development going forward. I need to give it more of a chance than a few evenings of getting set up and starting a project. I imagine it will be a lot easier when a project has a little more maturity than just a README.md file in the repository.

Special Thanks

A big special thanks this week to Christin at GitPod for providing the generic screenshots and text to explain what Gitpod is.