Setup

Background

If this is your first contact with developing MaMpf: a warm welcome from the team and thanks for being part of it ❤ Here is how to get started. For development, we use Dev Containers:

A development container (or dev container for short) allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase [...]. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.

The goal is to reduce annoying onboarding "setup pain". No need to install Node.js, Ruby on Rails, Postgres, (and more) manually. Instead, use a pre-configured environment that you (or the Cloud) builds by making use of Docker.

Developing in a DevContainer

There are a few possible choices for how you can make use of the DevContainer:

• Dev Container hosted locally (recommended if your PC is powerful enough)
  • Code editor installed locally
• Dev Container hosted in the cloud
  • Code editor installed locally (recommended to get started the quickest & to develop on multiple devices)
  • Code editor in the browser (not recommended)

For the "Cloud" option, you can use GitHub Codespaces (or an open-source tool like DevPod). This is especially useful if your PC doesn't have more than 20 GB of RAM or is in general not powerful enough to smoothly run MaMpf. GitHub offers you a certain quota of free Codespace minutes (per month). Later, you can still decide if you want to host the Dev Containers locally instead. The cloud option is also useful if you want to develop on multiple devices. With the cloud option, as the name suggests, it is not possible to develop without an Internet connection.

Pre-requisites

• Host Dev Container locally
  • Install the Docker Desktop app. And in VSCode, install the Dev Containers extension.
• Host Dev Container on GitHub Codespaces
  • In VSCode, install the GitHub Codespaces extension.

_{For other IDEs, please refer to their documentation on Dev Containers. Note that we highly recommend VSCode as the majority of the team uses it and therefore you can be sure that things like testing, debugging etc. work out of the box (since due to us using VSCode, we have strong incentives to make this work 😄). We don't guarantee the setup to work out of the box for other IDEs. Reach out to us in case you want to use another IDE.}

Build Dev Container & connect to it

• Host Dev Container locally
  • Clone the MaMpf Git repo locally. Make sure to also include the pdfcomprezzor submodule by using git clone --recurse-submodules. If you've already cloned the repo without the --recurse-submodules flag, run git submodule update --init --recursive.
    If you're working on Windows, we highly recommend to use WSL (with the latest Ubuntu LTS, at the time of writing 24.04 Noble). This will result in a much faster performance of the Dev Containers.
  • Open VSCode. In the bottom-left corner, click on the flash symbol, then on Reopen in Container.
• Host Dev Container on GitHub Codespaces
  • In this scenario, you simply go to the MaMpf repo, click on the Code button, then on the + button to create a new dev container.
    Alternatively, go to this page and follow the guide.
  • Usually, you won't have to create multiple codespaces. Instead, save some resources and only use one. Inside the container, you can use git, git pull, git switch etc. just like you're used to, so you can easily switch to other branches and commits.
  • If asked, click on Open in Visual Studio Code, and not Open in Browser. The Open in Visual Studio Code option should open a new browser tab that requests permission to open the codespace in your locally running VSCode.
  • What about your code changes in the cloud? See this section. In summary, use Git as usual and commit frequently:

    Your work will be saved on a virtual machine in the cloud. You can close and stop a codespace and return to the saved work later. If you have unsaved changes, your editor will prompt you to save them before exiting. However, if your codespace is deleted, then your work will be deleted too. To persist your work, you will need to commit your changes and push them to your remote repository [...].

  • The container will time out. See here:

    If you leave your codespace running without interaction, or if you exit your codespace without explicitly stopping it, the codespace will timeout after a period of inactivity and stop running. By default, a codespace will timeout after 30 minutes of inactivity, but you can customize the duration of the timeout period for new codespaces that you create.

  • To see statistics about your Codespace usage, go to the billing page in your profile.
  • (optional) If you want to understand how Codespaces are created on GitHub servers, see this deep dive.

In either case, this will build the complete environment by using Docker, which will take around 10-15 minutes (once for the initial setup, without any caching). Prepare some tea and let's see you on the Developing page afterwards.

Tip

If something doesn't work, take a look at the help section.

If you're new to Rails, this might be a good moment to look into the Rails Getting Started Guide. To work through it, you will have to locally install Ruby. We recommend rbenv as environment manager. In the Docker container itself, you don't have to worry about this, but if you followed this wiki until here, it will take some time until the Docker build is finished. And it's never a harm to have some local Ruby version outside of a Docker container anyways :)