How to Install Deviant

The deviant client can be installed using one of the following sources:

The deb package repository for Debian and Ubuntu.
The tarball download for other systems.

# Ubuntu/Debian

Prerequisite: Ensure You've Installed Auxon's Deb Package Repo

This section assumes you already have Auxon's deb package repo enabled on your system, which, if you've installed the modality package, you have and can continue.

If not, first, download Auxon's setup package for Debian/Ubuntu (opens new window), install it, and update your apt repositories:

$ sudo apt install ./auxon.deb
$ sudo apt update

deviant can be installed using the standard apt package manager:

$ sudo apt install deviant

# Configuration

Set the modalityd daemon URL for deviant to connect to with the deviant config command. If you are running modalityd on the same machine where you are installing deviant you may be able to omit this step and use the default.

$ deviant config --modalityd "http://my-modalityd-host:14181/v1/"

Note

Deviant operates on data stored in the Modality database, which is managed by modalityd. deviant needs to be informed of where to connect to your modalityd instance to be able to operate on the data it holds. If you do not have modalityd running anywhere, go to the Modality installation guide (opens new window) for instructions to install and run it.

Install a user auth token with the allow-http-api privilege and the allow-mutation privilege, generated with the modality user mint-auth-token command (opens new window), to the default location.

$ cp <your-auth-token-file> ~/.config/modality_cli/.user-auth-token

# Verify the Installation

To check that everything is installed correctly and ready to go, run:

$ deviant mutator list

You may or may not see some mutators listed, depending on if you or others have connected mutators to this modality instance. As long as you don't see errors your install is ready to use.

# Next steps:

If you plan on using Deviant's characterization JupyterLab notebooks, copy the *.ipynb files in the /usr/share/doc/deviant/notebooks directory to a location convenient for your editing and execution.
To get an idea of how to use Deviant, see the tutorial.

# Tarball

Tarball contents

The tarball contains the Deviant CLI along with a variety of Modality (opens new window) infrastructure, example systems, and more. In particular, the Modality CLI (opens new window) is almost always useful alongside Deviant to manage your data. The file structure is as follows:

.
├── bin
│   ├── deviant
│   ├── modality
│   ├── modalityd
│   ├── modality-reflector
│   └── modality-probe
├── CHANGELOG.md
├── cmake
├── completions
├── examples
│   ├── c-example
│   └── rust-example
├── include
│   └── modality
├── lib
├── LICENSE
├── man1
├── modality-reflector-config.toml
├── modality-reflector-plugins
│   ├── collectors
│   └── importers
├── notebooks
├── python
├── rust
└── VERSION

Download the tarball for your system's architecture from Auxon's download page (opens new window).

Extract the downloaded tarball and add the bin directory to your path (you will likely want to update your relevant shell configuration to always set this):

$ export PATH=$PATH:/path/to/modality_x.y.z/bin

Set the modalityd daemon URL for Deviant to connect to with the deviant config command. If you are running modalityd on the same machine where you are installing Deviant you may be able to omit this step and use the default.

$ deviant config --modalityd "http://my-modalityd-host:14181/v1/"

Note

$ cp <your-auth-token-file> ~/.config/modality_cli/.user-auth-token

# Verify the Installation

To check that everything is installed correctly and ready to go, run:

$ deviant mutator list

You may see some mutators listed or nothing at all depending on if you or others have connected mutators to this modality instance. As long as you don't see errors your install is ready to use.

# Next steps:

If you plan on using Deviant's characterization JupyterLab notebooks, copy the *.ipynb files in the extracted tarball's notebooks directory to a location convenient for your editing and execution.
To get an idea of how to use Deviant, see the tutorial.

# Notebooks

Deviant's JupyterLab notebooks provide advanced system characterization and experiment summarization. In addition to the notebook files, you'll have to install Python and a few python libraries.

# Notebook Files

Copy over the notebooks themselves from their source location to your workspace. The notebook source location depends on the method of deviant installation used earlier.

If you used the tarball approach, you can find the notebooks in the extracted tarball's notebooks directory.
If you used the debian approach, you can find the notebooks in the /usr/share/doc/deviant/notebooks directory.

# Python Itself

Every environment has its own unique layers of hells for each of the ways to get Python half-working. Good luck.

A reasonable point to start is the official Python Setup and Usage guide (opens new window).

Beyond bare-bones Python, you need to reach the point where you can use pip to install libraries. Consider following Python's Installing Packages (opens new window) tutorial.

# Prerequisite Libraries

Once Python and pip are available, install the following libraries.

pip install -U modality jupyterlab

# Verify the Installation

As with running deviant directly, a modalityd instance needs to be running and available for which you have a user and their auth token file.

If you need to set up a user and their auth token, in a terminal, do the following:

modality user create notebook-user --use
modality user mint-auth-token --allow-ingest --allow-http-api --allow-mutation .modality-auth-token
mv .modality-auth-token ~/.config/modality_cli/.user-auth-token

Then you can start jupyter-lab:

export MODALITY_AUTH_TOKEN=`cat  ~/.config/modality_cli/.user-auth-token`
jupyter-lab

Then, navigate to http://localhost:8888 in a web browser window, open and run any of the *.ipynb notebook files to explore the results of your experiments and other system characterization.

← Deviant Concepts Server →