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 GitHub access (SSH or token).

---

Table of contents

1. Install Docker Engine
   1. Run Docker without sudo
2. Install GNU Make
3. Configure Git
4. Configure GitHub access
   1. Option A — SSH (recommended)
   2. Option B — HTTPS 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 — 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 GitHub access

Features are cloned from GitHub. The CLI tries SSH first and falls back to HTTPS with a token. Set up at least one of the two.

Option A — SSH (recommended)

Make sure ~/.ssh exists and contains a key registered with GitHub:

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 this to GitHub → Settings → SSH keys
ssh -T git@github.com         # should say "successfully authenticated"

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.

Option B — HTTPS token

Set GITHUB_USER and GITHUB_TOKEN in your workspace .env. Run splent tokens:setup for step-by-step instructions, then verify with splent check:github.

---

Verify your environment

From splent_cli, you can run the host pre-flight 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.

Once everything passes, continue with the SPLENT installation guide.