hackdoc:// HSCloud Docs

Checking out hscloud

This codelab will introduce you to the basics of working with hscloud - including what it it, how to use it, and what next steps can you take afterwards. It’s strongly recommended for everyone who wants to interact with hscloud, k0, or any of the ‘new style’ Warsaw Hackerspace infrastructure.

By the end, you’ll have a hscloud checkout and general understanding of what’s where and what tools are available to interact with hscloud.

Background

Welcome to hscloud! This is a repository of code and set of infrastructure born around the Warsaw Hackerspace. It started off as a monorepo for infrastructure-as-code for a set of cloud-like infrastructure at the hackerspace, but has since grown to accumulate a bunch of semi-related code: everything from Nix machine definitions to game servers.

What do I use it for?

If you’ve been pointed towards hscloud, it’s probably due to one of the below reasons:

  • You want to deploy something for the Hackerspace
  • You want to fix/patch some software already running
  • You want to run some of your personal projects on our compute cluster

All of these are first-class functionality within hscloud, and they should be as straightforward to use as possible. If anything doesn’t make immediate sense, or you are confused by something that seems unclear - contact q3k and he will make sure to help you out and update the documentation so that the next person doesn’t have this issue.

This documentation, by the way, is also kept within hscloud!

What is hackdoc?

If you’re viewing this on https://hackdoc.hackerspace.pl/doc/codelabs/getting-started/checking-out.md - you’re using Hackdoc! Hackdoc renders some of the code within hscloud as more prose-oriented documentation, like these codelabs. Somewhere on the right hand side of this page you should be able to click a View Source button to see what document this was rendered from.

You could instead also be reading this from cs.hackerspace.pl, our code browser view or gerrit.hackerspace.pl, our code review tool. Both of these will show you the same content as the hackdoc view, but less richly rendered and linked. We highly recommend viewing this via Hackdoc as linked above for the best possible experience.

Local requirements & Git clone

First, you need to make a local clone of hscloud on your development machine - ie., the computer/laptop you want to work on. We support generic glibc-based Linux distributions (eg. Ubuntu, Debian, Fedora), NixOS and to a certain degree, macOS.

Unless you’re running something different from the above, we highly recommend not working on hscloud from within a container or VM, as our build system already takes care of hermetic builds and reproducibility - and containers/VMs will only get in the way.

Once you’ve found a machine and cd’d to a directory where you want to clone hscloud, do the following:

$ git clone https://gerrit.hackerspace.pl/hscloud.git
[...]
$ cd hscloud
$ head -n 4 doc/codelabs/getting-started/checking-out.md

and you should see the source for this document, proving that you’ve succesfully gotten hold of a copy of hscloud.

Code organization

hscloud is a branchless monorepo. If you’ve never worked with such a setup before, you might find it slightly odd and coutnerintuitive. Here’s what we mean by branchless monorepo:

  • There is only a single branch we work on: master. Any time you want to introduce a change to hscloud, you always start off master at the newest possible HEAD, add some changes on top, and then get these reviewed and merged. We do not do feature branches, release trains, or release versions.
  • There are no personal branches. Instead, if you want to commit some stuff for personal/experimental use, just drop it into a //personal/$your-username, and you will be able to land things there without review.
  • There is a single repository. All projects and code lives within hscloud. This allows you to make a single change that alters, for examplle, client and server side code of an application simultaneously, without having to coordinate this change across multiple repositories.

What’s up with //these/paths?

These paths, sometimes called depot paths, are a convention to refer to paths within hscloud. For example, //foo/bar means a file or directory named bar within a directory named foo in the root of the hscloud repository.

These paths are notably used by Bazel, our build system, which extends the syntax slightly: //foo/bar:baz means a file or build target named baz within a directory bar within a diredctory foo inside hscloud.

What are changes?

Changes, or Change Requests, or Change Lists (all used interchangably) are modifications to the hscloud repository. Each change corresponds to a single Git commit that has been reviewed on gerrit, our code review tool. Each change can be identified by:

  • The git commit hash when it got merged into master (eg. 146c99e58e46f3c026e170794326521de6bf13e1)
  • The ChangeId hash within the git commit message (eg. I8b64103cb87d8b185ff35165695a18cb19fea523)
  • The Change number on gerrit (eg. https://gerrit.hackerspace.pl/841)

Going from Change number to git commit hash or ChangeId is easy - gerrit will show these to you when you visit the page for any given Change number. Going the otherway is currently not super intuitive - you have to use Gerrit’s web interface to search for either git commit hash or ChangeId.

Viewing hscloud online

We have a code search tool/web interface available on https://cs.hackerspace.pl/hscloud, which is probably the most convenient way to browse hscloud online, and link it to others. Gerrit also has its own built-in code viewer (Gitiles), but its use is being phased out.

So what’s in hscloud? Where do I start?

If you want to modify something, you’ll first have to figure out where is it in hscloud. For that, either use codesearch, or ask any of the people who work on hscloud for guidance. There is also a somewhat up-to-date directory of interesting top-level things at //README.md.

Once you have that, look at other codelabs for guidance on working with specific technologies within hscloud. If something’s missing - ask someone knowledgeable to either document it, or help you document it!

Where do we report and track issues?

We have an issue tracker at https://issues.hackerspace.pl/. It’s a Redmine instance so it’s not super friendly, so we made some shorthand links:

File issues often, file issues early, ask for forgiveness later! It’s much easier to keep track of things on there than to chat up people. Don’t worry about categorizing, and feel free to assign q3k for anything.

You can naturally also ask on #members:hackerspace.pl or even #general:hackerspace.pl - but if you encounter an problem, we highly recommend filing issues instead of chatting people up :).

Further steps

Now that you have a local hscloud checkout and mostly know why it exists and how it’s laid out, there’s a few next steps you can take:

  • Your first hscloud Change will guide you through using Gerrit to send your first contribution to hscloud - a small file change in your personal directory.
  • TODO will guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own.
  • TODO will guide you through accessing our production Kubernetes cluster and running some code on it.