Linux development environment

This guide explains how to prepare a native Linux machine to run SPLENT. The development environment relies on Docker Engine, GNU Make, and access to the git forge (SSH or token).

---

Table of contents

1. Install Docker Engine
   1. Run Docker without sudo
2. Install GNU Make
3. Configure Git
4. Configure forge access (optional)
   1. SSH key
   2. API token
5. Verify your environment

---

Install Docker Engine

Install Docker Engine and the Compose v2 plugin following the official guide for your distribution.

https://docs.docker.com/engine/install/

After installing, make sure the daemon is running and that Compose v2 is available.

sudo systemctl enable --now docker
docker --version
docker compose version

SPLENT requires Compose v2 (the docker compose subcommand), not the legacy docker-compose binary.

Run Docker without sudo

So that the CLI can talk to the Docker daemon, add your user to the docker group and re-log.

sudo usermod -aG docker $USER
newgrp docker        # or log out and back in
docker ps            # should work without sudo

---

Install GNU Make

Most distributions ship Make in their base build tools.

# Debian / Ubuntu
sudo apt update && sudo apt install -y make git

# Fedora
sudo dnf install -y make git

# Arch
sudo pacman -S --needed make git

---

Configure Git

Before running SPLENT, ensure that your Git configuration file exists as a file in your home directory.

The CLI container bind-mounts ~/.gitconfig (and ~/.ssh) from the host. If ~/.gitconfig does not exist, Docker silently creates it as an empty directory, which makes Git fail inside the container. This is the usual cause of feature:clone / feature:install errors.

To avoid this, create the file and configure your identity.

touch ~/.gitconfig
git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

Verify that ~/.gitconfig is a regular file, not a directory.

ls -l ~/.gitconfig

If ls shows it as a directory (it starts with d), remove it first.

rm -rf ~/.gitconfig
touch ~/.gitconfig
git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

---

Configure forge access (optional)

Features, the framework and the CLI live on git.splent.io, and every repository there is public. The CLI clones over SSH when your key is registered on the forge and falls back to anonymous HTTPS otherwise, so you can follow the whole installation and the first tutorials without an account.

You need forge access only to push your own repositories and publish features for real, which Tutorial 5 makes optional (its rehearsal needs no account). Registration on git.splent.io is closed, so ask the SPLENT maintainers for an account if you want one.

SSH key

Make sure ~/.ssh exists and contains a key registered with the forge.

ls -ld ~/.ssh                 # must exist as a directory
ssh-keygen -t ed25519 -C "your_email@example.com"   # if you have no key
cat ~/.ssh/id_ed25519.pub     # add it on git.splent.io → Settings → SSH / GPG Keys
ssh -T -p 2223 git@git.splent.io

The forge answers SSH on port 2223, not 22.

If ~/.ssh does not exist on the host, Docker mounts an empty directory and SSH clones will not work. The CLI will then fall back to HTTPS.

API token

Releasing also needs a forge token. Create one on git.splent.io under Settings → Applications → Access Tokens with the scopes write:repository and write:organization, and set SPLENT_FORGE_USER (your username) and SPLENT_FORGE_TOKEN in the workspace .env (the file make setup creates next to splent_cli/). Inside the container, splent tokens:setup walks you through it and splent check:forge verifies it.

---

Verify your environment

Once splent_cli is cloned (see the installation guide), you can run the host pre-flight from splent_cli at any time.

make preflight

It checks that Docker is installed and running, that Compose v2 is available, and that ~/.gitconfig / ~/.ssh are in a sane state for the container. On a new workspace it also reports that the workspace .env does not exist yet; make setup creates it.

Once everything passes, continue with the SPLENT installation guide.