How to Install Deviant
The deviant
client can be installed using one of the following sources:
# 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
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 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'snotebooks
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.