Installation guide

Warning

The project is currently in pre-alpha state. This setup documentation is rudimentary at best and definitely not suited for production.

Setup instructions will change in future, installation methods may come and go. Please always refer to the documentation of the version you are installing!

Help in the development is always appreciated, head over to GitHub for a list of open issues!

Chaosinventory ships as a standalone app. Therefore, you don’t need to bring your own django project. You only need to have a wsgi server such as gunicorn and a database. PostgreSQL is recommended.

Todo

The whole chapter need structural cleanup.

Docker

The docker option is currently in development, and primarily used for a demo instance.

gunicorn is serving chaosinventory on port 8000.

Warning

Make sure to persist the /data-volume, as it contains configuration and database!

$ docker run -v /opt/chaosinventory:/data -p 8000:8000 ghcr.io/chaosinventory/chaosinventory:latest # Latest Stable Version
$ docker run -v /opt/chaosinventory:/data -p 8000:8000 ghcr.io/chaosinventory/chaosinventory:main # Latest Development Version
$ docker run -v /opt/chaosinventory:/data -p 8000:8000 ghcr.io/chaosinventory/chaosinventory:pr-00 # Pull Request Version from PR 00 (replace with correct PR id)

In the example above, the data is persisted in /opt/chaosinventory on the docker host. If you need to adjust the configuration from defaults, you can do it in /opt/chaosinventory/chaosinventory.cfg and restart the container afterwards.

Todo

Verified updating guidelines

PIP/Manual

Virtual Environment Setup

Todo

Separate user

To isolate python applications and their requirements, it is highly advised to install in a so called virtual environment.

$ mkdir chaosinventory
$ cd chaosinventory
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ which python # check it is setup correctly
/path/to/chaosinventory/venv/bin/python

Install and configure Chaosinventory

Chaosinventory can currently only be installed via pip from the source code as shown below.

(venv) $ pip install https://github.com/chaosinventory/chaosinventory/archive/main.tar.gz#subdirectory=src gunicorn
...
Successfully installed Django-3.1.5 chaosinventory-0.0.0 gunicorn-20.0.4

Now we need to provide a configuration for chaosinventory. This can be located in multiple locations (in the order of preference, first found will be used):

  • The path specified in the Environment variable CHAOSINVENTORY_CONFIG_FILE (exclusively)

  • The chaosinventory.cfg in your current working directory

  • /etc/chaosinventory/chaosinventory.cfg

The last two options will be merged, if both files exist.

If there is no config file on startup, a random secret will be generated and saved in a new config file:

  • Environment Variable CHAOSINVENTORY_CONFIG_FILE (preferred)

  • chaosinventory.cfg in the current working directory, if no config file is given.

Warning

Make sure to keep the generated config file, especially the secret, persistent.

Todo

Improve documentation of the config file.

Additionally, the location of the sqlite3-File may be given using the CHAOSINVENTORY_SQLITE3_FILE-Environment Variable. If no database is present, a new one will be created.

This location will be only used if no location is configured in the configuration file. If the Environment Variable is not set, “db.sqlite3” in the current working directory is used as fallback.

Warning

Make sure to keep the sqlite3-file as it contains your application data!

The example configuration looks like this should work out of the box using a sqlite Database, however this is not recommended for production use.

[django]
secret = foobar2342
debug = True
allowed_hosts = *
cors_allow_all = False
cors_allowed_origins = http://localhost,http://127.0.0.1:8080,http://[::1]:8080
language_code = en-us
time_zone = UTC

[database]
engine = sqlite3
name = db.sqlite3
user =
password =
host =
port =

[email]
backend = filebased.EmailBackend
host =
port =
user =
password =
ssl = False
tls = False

Before the app can be started, the database structure must be created and all static files collected.

(venv) $ chaosinventory migrate
Operations to perform:
   Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  ...
  Applying sessions.0001_initial... OK

(venv) $ chaosinventory collectstatic
132 static files copied to '/path/to/chaosinventory/venv/lib/python3.9/site-packages/static'.

Todo

The statics will also be collected into the venv directory. This should also be updated once the configuration is in place.

Start gunicorn

Gunicorn will server our application for it to be accessible via http.

(venv) $ venv/bin/gunicorn chaosinventory.wsgi --name chaosinventory --bind="[::1]:8000"
[2021-01-23 20:13:45 +0100] [107596] [INFO] Starting gunicorn 20.0.4
[2021-01-23 20:13:45 +0100] [107596] [INFO] Listening at: http://[::1]:8000 (107596)
[2021-01-23 20:13:45 +0100] [107596] [INFO] Using worker: sync
[2021-01-23 20:13:45 +0100] [107597] [INFO] Booting worker with pid: 107597

When visiting http://[::1]:1234/ we will be greeted by hello world page (for now).

Todo

Systemd service

Todo

nginx configuration with ssl