Developer Getting Started Guide

This guide explains how to set up the recommended developer setup on a Linux machine. Other development setups are possible, but this one provides a good starting point.

  • Install VS Code and Inmanta extension.

  • Setting up Python virtual environments.

  • Setting up a project.

  • Set project sources

  • Setting up a module

  • Run tests

  • Module developers guide

  • Required environment variables

The examples below are using pip your system might require you to use pip3.

Install VS Code and Inmanta extension

The developer setup is based on VSCode with the Inmanta extension.

In order to install VS Code, you can refer to this page.

Inmanta’s extension in VS Code marketplace can be found here.

Further information about Inmanta VS Code extension is available on this page.

Setting up Python virtual environments

For every project that you work on, we recommend using a new virtual environment. If you are unfamiliar with venv’s, you can check out this page.

To create a virtual environment:

python3 -m venv ~/.virtualenvs/my_project

Then activate it by running:

source ~/.virtualenvs/my_project/bin/activate

Upgrading your ``pip`` will save you a lot of time and troubleshooting.

You can do so by running:

pip install --upgrade pip wheel

Setting up a project

At the time of this writing, linting and code navigation in IDEs work only if you have a project, so even if you only work on a single module, it is best to have a project.

There are two scenarios:

  1. Working on a New Project.

  2. Working on an Existing Project.

Working on a New Project

To create a new project:

pip install cookiecutter

cookiecutter https://github.com/inmanta/inmanta-project-template.git

For more details go here.

You need to install some essential packages as follows:

pip install inmanta-core pytest-inmanta

Once you are done with creating a project, you can cd into that directory and open VS Code by running:

cd <project_name>

code .

Upon opening your vs code, and the main.cf file, you should see modules downloading in libs directory.

Working on an Existing Project

When working on an existing project, you need to clone them first:

git clone <project_url>

They also come with requirements.txt or requirements.dev.txt to install the required modules:

pip install -r requirements.txt

pip install -r requirements.dev.txt

Set project sources

When starting a new project, the next step is to set the sources of your project so that it knows where to get its required modules from.

If you only use opensource modules as provided by Inmanta, you can skip below step.

  1. Find the module you want to work on

  2. Copy the SSH URL of the repo

  3. In your VS code, open the project.yml file and under repo:, add the copied line there but keep in mind to replace the name of a specific module with a place holder, like below example:

code project.yml
repo:
    - git@code.inmanta.com:example/my_module.git

Becomes:

repo:
    - git@code.inmanta.com:example/{}.git
  • Now, in your main.cf file, if you import a module like, import <my_module> and save the file, you can get code completion. If you are working on an existing project with a populated main.cf file, code completion will work as expected.

Please note, code completion and navigation work on modules that are imported in the main.cf file.

Setting up a module

Like projects, there are also two scenarios:

  1. Working on a New Module.

  2. Working on an Existing Module.

Working on a New Module

Same as Working on a New Project part, modules can also be created like:

pip install cookiecutter

cookiecutter --checkout v1 https://github.com/inmanta/inmanta-module-template.git

There are also guides here and here that help you get up and running.

Working on an Existing Module

Modules that you want to work on, have to be imported in the main.cf file that is located in your main project directory. For instance:

import vyos

To download the imported modules in your main.cf file run:

inmanta compile

When starting to work on an existing module, it is recommended to check the readme.md file that comes with the module to see the instructions on how to install and use them.

Running Test

To run test on modules, it is recommended to set the INMANTA_TEST_ENV environment variable to speed up your tests and avoid creating virtual environments at each test run.

  1. Create a temp directory and export the path:

export INMANTA_TEST_ENV=$(mktemp -d)
  1. Install required dependencies

pip install -r requirements.txt -r requirements.dev.txt
  1. Run the test

python -m pytest tests