Setup

The development environment is a first-class component of this system. From installation and configuration to supporting fast development feedback loops, it should strive to deliver the best developer experience to as many developers as possible. This section describes the recommended steps to configure a development environment suitable for working on Acme. Please install tools as they are mentioned in the documentation.

Decisions made in service of this goal are often loaded with tradeoffs and are documented as a Decision Record.

Quick Start

These instructions are designed to work on macOS and Ubuntu. They should also work for Windows under WSL but have not been verified.

  1. Install Homebrew

  2. Install Task

  3. Install the rest of the development tools:

    $ task env:setup

  4. Setup the 1Password CLI

  5. Install your preferred Docker Manager

  6. Install your preferred Kubernetes Manager

Docker Manager

To run containers you’ll need to install a Docker engine manager. The following products are supported by this tooling:

Rancher Desktop

Rancher Desktop is an alternative to Docker Desktop. Once installed, configure Rancher Desktop with sudo access and dockerd as the container runtime:

rancher desktop sudo
Figure 1. Administrative Access > Allow sudo access
rancher desktop docker
Figure 2. Container Runtime > dockerd (moby)

As of this writing Rancher Desktop has an issue with binding to privileged ports on Linux. The workaround is to adjust the default net.ipv4.ip_unprivileged_port_start value to 80. Run the following command and restart Rancher Desktop afterwards:

sudo sysctl net.ipv4.ip_unprivileged_port_start=80

This configuration makes it possible to access Kubernetes Ingress resources on localhost over privileged ports 80 (HTTP) and 443 (HTTPS). It also affords the user of friendly local URLs via http://nip.io/.

Kubernetes Manager

There are many tools that will run a local Kubernetes cluster The following products are supported by this tooling:

GUIs

The following products require a user to point-and-click a GUI to manage a Kubernetes cluster.

Docker Desktop

Using Docker Desktop is, arguably, the easiest way to run Kubernetes locally given its ubiquity. It is also widely supported and actively maintained for all major operating systems. The main trade-off when choosing Docker Desktop is that the version of Kubernetes cannot be changed.

Rancher Desktop

Rancher Desktop, similar to Docker Desktop, can also be used to run a local Kubernetes cluster. An advantage Rancher Desktop has over Docker Desktop is that the version of Kubernetes can be changed

When choosing the Kubernetes version, choose a version with the same minor version specified by the KUBERNETES_VERSION environment variable in Taskfile.yaml

CLIs

The following products are command-line interfaces. Subjectively, they may offer a better user-experience for developers.

minikube

minikube is a command-line tool for running Kubernetes clusters locally. Follow these instructions to install minikube.

k3d

k3d is another command-line tool for running Kubernetes clusters. Follow these instructions to install k3d.

IDEs

IntelliJ IDEA

IntelliJ IDEA is used for, but not limited to, Kotlin development and Asciidoc authoring.

Plugins

The following plugins are recommended for the best development experience:

Configuration

Ensure that IntelliJ is aware of the location of the JDK by opening the File > Project Structure menu.

intellij jdk

Additionally, ensure that IntelliJ is configured to build and run tests with Gradle. Under the Preferences menu, navigate to Build, Execution, Deployment > Build Tools > Gradle:

intellij gradle

Visual Studio Code

Visual Studio Code is primarily used for, but not limited to, TypeScript project development.

Plugins

The following plugins are recommended for the best development experience:

Configuration

Visual Studio Code does not require further configuration for this project.

Linux Users