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. 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 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.