Getting started

This section explains how to set up the SPLENT work environment from scratch: create the workspace, configure Linux (or a VM if you use Windows/macOS), clone the ecosystem repositories, set up the Docker environment, and create your first product. In just a few steps, you will have a functional environment ready to develop with SPLENT.

Table of contents

  1. Workspace
  2. Linux environment
  3. Clone repositories
  4. Setting up the Docker environment
  5. Create a sample product
  6. Synchronize features
  7. Generate environment variables
  8. Launch product and features
  9. Start product

Workspace

SPLENT is not a single repository, but rather an ecosystem composed of two basic components: the SPLENT Framework and the SPLENT CLI . For everything to work coherently, it is necessary to have a single root directory where all repositories are placed and where the products and functions that are created are also stored.

That root directory is the workspace.

First, create it:

mkdir splent_workspace
cd splent_workspace

Linux environment

SPLENT is designed to run in a real Linux environment. The CLI, containers, internal paths, and integration with Docker are designed to behave predictably only on Linux systems.

If you work on Windows or macOS, the most stable option is to create a Linux virtual machine within the workspace itself to ensure that SPLENT works as it should. The easiest way to do this is with Vagrant.

At the root of the workspace, download the official Vagrantfile:

curl -fsSL https://docs.splent.io/assets/Vagrantfile -o Vagrantfile

Now run the machine:

vagrant up
vagrant ssh

The machine automatically includes:

  • Ubuntu 22.04 LTS
  • Docker + Docker Compose plugin
  • Git configured with your SSH keys (if any)
  • /workspace synchronized with your project
  • Environment prepared to run SPLENT identically to native Linux

Clone repositories

SPLENT is divided into two separate repositories. Each one plays a different role within the ecosystem, and all of them must be present in the workspace for the SPLENT CLI and SPLENT Framework to function correctly.

Clone them into the workspace:

git clone https://github.com/diverso-lab/splent_framework.git
git clone https://github.com/diverso-lab/splent_cli.git

If you are an authorized SPLENT developer and have SSH access to the repositories, clone them using SSH instead of HTTPS:

git clone git@github.com:diverso-lab/splent_framework.git
git clone git@github.com:diverso-lab/splent_cli.git

Once cloned, your workspace will have this minimal structure:

splent_workspace/
  splent_framework/
  splent_cli/

Setting up the Docker environment

The SPLENT ecosystem uses its own Docker environment to run the SPLENT CLI and products in an isolated and consistent manner. To activate it for the first time, enter the splent_cli repository and run:

cd splent_cli
make setup

These actions set up the entire SPLENT ecosystem in Docker and take us to the SPLENT CLI . Once inside, you will see a prompt similar to:

(detached) /workspace$

At that point, you are already working within the official SPLENT environment, with Python, Docker, and all paths configured correctly. From there, you can create products, features, and run any SPLENT command.

Create a sample product

When you first enter the SPLENT CLI , you will see that it appears in detached mode. This simply means that the SPLENT CLI is not yet associated with any product within the workspace.

To create a test product called sample_splent_app, run:

splent product:create sample_splent_app

This command generates the basic scaffolding for the product within the workspace:

  • Standard folder structure
  • Product pyproject.toml file
  • Initial templates
  • Empty feature registry
  • Minimum configuration for the product to run

Once created, you must tell the SPLENT CLI that this will be the active product:

splent product:select sample_splent_app

From that moment on, the prompt will change to reflect that you are working within the product:

(sample_splent_app) /workspace$

Everything you do with the SPLENT CLI (create features, configure the product, generate builds, etc.) will now apply to sample_splent_app. If you want to switch products in the future, you just need to use splent product:select <product_name> again.

Synchronize features 

splent product:sync

This command downloads the features declared in pyproject.toml using their namespace and stores them in .splent_cache.

Generate environment variables

Each feature can provide a .env.example.dev, and the product also has its own. For development work, SPLENT allows you to generate and unify all these variables into a single .env.

splent product:env --generate --all --dev

This creates (or updates) the .env.example.dev files generated from all features and the product.

splent product:env --merge --dev

This creates the final .env file for development by combining all variables, respecting the correct order (product > features).

Launch product and features

Both the product and features can have associated docker-compose.yml files. The following command launches everything:

splent product:up --dev

Start product

Finally, we must start the product’s Docker container.

splent product:run --dev

To find out which port our product is running on, we launch:

splent product:port

We open the browser and navigate to localhost:<port>.

When running inside the Vagrant development environment, SPLENT automatically uses the fixed host IP 10.10.10.10. You don’t need to look it up or configure anything.