System Initiative

This is a monolithic repository containing the System Initiative software.

About

System Initiative is a collaborative power tool designed to remove the papercuts from DevOps work. To learn more, read our "Second Wave DevOps" blog post.

Quickstart

If you would like to get System Initiative (SI) up and running, navigate to the installation page on our website to get started. If you would like to develop locally, follow the Local Development Setup instructions below.

Local Development Setup

Running the System Initiative software locally can be done in a variety of ways, but this abbreviated section will focus on a single method for getting your environment ready to run the stack. For more information and options on running SI locally, see the development environment documentation.

(1) Choose a Supported Platform

Let's start by choosing an officially supported platform.

Architecture	Operating System
x86_64 (amd64)	macOS, Linux, WSL2 (Windows 10/11)
aarch64 (arm64)	macOS, Linux, WSL2 (Windows 10/11)

Platform Notes:

• On Apple Silicon systems (i.e. macOS aarch64 (arm64)), Rosetta 2 must be installed (install it with softwareupdate --install-rosetta)
• NixOS and Linux with MUSL instead of GNU (e.g. Alpine Linux) will not likely work at this time
• Systemd may need to be enabled on WSL2

(2) Install Dependencies

Install dependencies on your chosen platform.

• 1) nix with flakes enabled
• 2) docker from Docker Desktop or Docker Engine
• 3a) direnv version >= 2.30 installed
• 3b) direnv hooked into your shell

For nix, we highly recommend using the Determinate Nix Installer.

For docker, the Docker Desktop version corresponding to your native architecture should be used. WSL2 users should be able to use either Docker Desktop for WSL2 or Docker Engine inside the WSL2 VM.

For direnv, you can install it with your package manager of choice. However, if you're unsure which installation method to use or your package manager does not provide a compatible version, you can use nix itself (e.g. nix profile install nixpkgs#direnv).

We recommend using the upstream docs for hooking direnv into your shell, but here is an example on how to do it on a system where zsh is the default shell. In this example, the following is added to the end of ~/.zshrc.

if [ $(command -v direnv) ]; then
   eval "$(direnv hook zsh)"
fi

(3) Enter the Repository Directory

All commands need to be run from the nix environment. Since direnv is installed and hooked into your shell, you can cd into the repository and nix will boostrap the environment for you using the flake.

Please note: you may notice a large download of dependencies when entering the repository for the first time.

(4) Configure Providers

Configuring providers is optional for using the System Initiative software, but may be required depending on the types of assets used.

If you are using AWS assets, authentication with the aws CLI is required to deploy and manage your infrastructure.

aws configure

Docker Hub authentication is not strictly needed if you only access public docker images, but to avoid being rate-limited when qualifying images, we recommend authenticating with the docker CLI.

docker login

(5) Running the Stack

We use buck2 to run the stack, run and build individual services and libraries, perform lints and tests, etc.

Before continuing, you should stop any locally running services to avoid conflicting ports with the stack. Some of the services that will run include, but are not limited to the following: PostgreSQL, NATS, Jaeger and OpenTelemetry.

Check if you are ready to run the stack before continuing.

buck2 run dev:healthcheck

You may notice some checks related to resource limits. On macOS and in WSL2 in particular, we recommend significantly increasing the file descriptor limit for buck2 to work as intended (e.g. ulimit -n 10240). Please note: the new file descriptor limit may not persist to future sessions.

Once ready, we can build relevant services and run the entire stack locally.

Please note: if you have used SI before, the following command will delete all contents of the database. Reach out to us on Discord if you have any questions.

buck2 run dev:up

Once Tilt starts, you can check on the status of all services by accessing the UI through the given port on your local host (e.g. http://localhost:10350/). Every service should eventually have a green checkmark next to them, which ensures that they are in "ready" states.

Please note: database migrations may take some time to complete.

If you would like to learn more on what's running, check out the Architecture section.

(6) Troubleshooting in Tilt

If some services failed to start, you can restart them on the Tilt dashboard.

• A backend service fails (e.g. sdf): restart them in the following order: veritech, council, pinga, sdf
• A frontend service fails (e.g. web): restart the service individually
• A dependent service fails (e.g. PostgreSQL): tear down the stack and restart

(7) Tearing Down the Stack

The following command will stop all running services and containers. It will also remove the containers and, consequentially, the data held in them.

buck2 run dev:down

Alternatively, if you wish to keep your data for later use, you can stop the containers without removing them.

buck2 run dev:stop

Where Do I Learn More?

For more information on how to use and develop the System Initiative software, talk to us on our Discord and see the docs directory.

How Can I Contribute?

To start, we recommend reading the Open Source and Contributing sources below. They provide information on licensing, contributor rights, and more.

Afterwards, navigate to the contributing guide to get started.

Open Source

This repository contains the System Initiative software, covered under the Apache License 2.0, except where noted (any System Initiative logos or trademarks are not covered under the Apache License, and should be explicitly noted by a LICENSE file.)

System Initiative is a product produced from this open source software, exclusively by System Initiative, Inc. It is distributed under our commercial terms.

Others are allowed to make their own distribution of the software, but they cannot use any of the System Initiative trademarks, cloud services, etc.

We explicitly grant permission for you to make a build that includes our trademarks while developing the System Initiative software itself. You may not publish or share the build, and you may not use that build to run System Initiative software for any other purpose.

You can learn more about the System Initiative software and Open Source in our FAQ.

Contributing

The System Initiative software is Open Source under the Apache License 2.0, and is the copyright of its contributors. If you would like to contribute to the software, you must:

1. Read the Contributors file.
2. Agree to the terms by having a commit in your pull request "signing" the file by adding your name and GitHub handle on a new line at the bottom of the file.
3. Make sure your commits Author metadata matches the name and handle you added to the file.

This ensures that users, distributors, and other contributors can rely on all the software related to System Initiative being contributed under the terms of the License. No contributions will be accepted without following this process.