Codespaces - otwcode/otwarchive GitHub Wiki

GitHub codespaces enable developers to create development environments in the cloud (AKA someone else's computers). The codespaces configuration in this repository uses the Docker Compose setup under the hood, so that wiki page may also be helpful – in particular the sections starting with "Troubleshooting".

[!NOTE] GitHub allows a certain amount of Codespaces usage, both in terms of time and storage for prebuilds, per month. This will be associated with your own account. After that budget is exhausted, you will not be able to create new Codespaces/prebuilds until the next billing cycle (or you can pay for more time/space).

Prerequisites

Cloud development environments have fewer prerequisites than local development. All you need to do is fork the otwarchive repository.

Getting Started

Go to your fork of the repository (something like https://github.com/brianjaustin/otwarchive but replace brianjaustin with your GitHub username). Make sure it is synced with this repository. Then, click the "Code" button and switch to the "Codespaces" tab. Here, you can see a list of codespaces you have for the repository. Since there won't be any yet, click the "Create a codespace on master" button to create one.

By default, codespaces will launch a version of VS Code in your browser, but that is configurable if you wish to use another IDE like locally-installed VS Code or RubyMine. Once the page loads, it will run the Docker initialization script automatically to set up your environment. This will take quite a few minutes the first time during the Running postCreateCommand stage. (To speed up creating new codespaces, refer to the section below on prebuilds.) After this, the same codespace should be ready after a minute or two. Once it is complete, the codespace will show a popup near the bottom right asking to open port 3000 (NOT port 3306) in a browser. You can do that now, or go to the "Ports" tab to open it later.

  • If this tab is still blank after the codespace has finished setting up, you either need to run sh script/docker/init.sh or delete/re-create the codespace.
  • There are also several ports besides 3000; these are for various supporting services (like the database and search) -- you can ignore these.

Congratulations, you have your own copy of the Archive to play around with! :tada: You can change the files in the codespace, reload the Archive page, and watch as your change is reflected. (Note: some changes require the application to be restarted, which is documented in the Docker wiki page.) Make sure to check out a new branch before you start working on your changes, and commit to it often!

Prebuilds

To speed up launching a new codespace, you can set up prebuilds to do the initial setup work behind the scenes. Refer to the GitHub docs for more information. Important: this is configured on your fork, not on the main otwarchive repository.