Installer#

Installer is implemented as Ansible collection. You need Ansible 2.9 or newer to run it. We recommend users to create disposable virtual environment and install Ansible from PyPI, so it’s generally fine to support only latest released version of Ansible.

Preparing development environment#

Create virtual environment and install Ansible:

python3 -m venv ~/kustosz-ansible-venv/
. ~/kustosz-ansible-venv/bin/activate
pip install --upgrade pip
pip install ansible

You have to put installer files in a place where Ansible can find them. You can either clone directly to Ansible directory, or clone anywhere and bind-mount to Ansible directory:

# Option 1: Clone directly to Ansible directory
mkdir -p ~/.ansible/collections/ansible_collections/kustosz/install
git clone https://github.com/KustoszApp/kustosz-installer.git ~/.ansible/collections/ansible_collections/kustosz/install/

# Option 2: Clone anywhere and bind-mount
mkdir -p ~/.ansible/collections/ansible_collections/kustosz/install
git clone https://github.com/KustoszApp/kustosz-installer.git
sudo mount --bind ./kustosz-installer/ ~/.ansible/collections/ansible_collections/kustosz/install/

Setting up Vagrant#

You need a machine you can test installer on. We suggest using Vagrant, which provides easy way to manage local virtual machines.

You need Vagrant and plugin to virtual machine provider. vagrant-libvirt is included in most distributions, making it one of the easiest to set up - just install vagrant and vagrant-libvirt packages, make sure libvirt system service is started, add your user to libvirt group and you are good to go. When in doubt, consult your distribution documentation.

In root directory of installer, create file named Vagrantfile with following content:

Vagrantfile#

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  config.vm.define "centos8", autostart: false do |centos8|
    centos8.vm.box = "generic/centos8"
    centos8.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1"
  end
  config.vm.define "ubuntu2004", autostart: false do |ubuntu2004|
    ubuntu2004.vm.box = "generic/ubuntu2004"
    ubuntu2004.vm.network "forwarded_port", guest: 80, host: 8081, host_ip: "127.0.0.1"
  end
  config.vm.define "ubuntu2204", autostart: true do |ubuntu2204|
    ubuntu2204.vm.box = "generic/ubuntu2204"
    ubuntu2204.vm.network "forwarded_port", guest: 80, host: 8082, host_ip: "127.0.0.1"
  end

  config.vm.provision "ansible" do |ansible|
    ansible.playbook = "playbooks/playbook.yml"
    ansible.verbose = "v"
  end
end

Running current development version#

Now you can use following commands:

vagrant up centos8 - create new CentOS machine, start it and run installer against it
vagrant provision centos8 - re-run installer against started virtual machine; useful for testing failure scenarios
vagrant ssh centos8 - ssh into started virtual machine
vagrant delete -f centos8 - stop and remove running virtual machine

Vagrant will automatically route network traffic from host: port to virtual machine. For example, you can access Kustosz running on Ubuntu 20.04 by opening localhost:8081/ui.

Changing development version configuration#

If you want to test impact of various configuration variables, the best way is to create new file playbooks/vagrant.yml with following content:

playbooks/vagrant.yml#

- name: "Install Kustosz on Vagrant"
  import_playbook: kustosz.install.playbook
  vars:
    use_system_python: true
    kustosz_nginx_server_name: "127.0.0.1 localhost"
    web_user_name: kustosz
    web_user_password: kustosz
    opml_local_path: /tmp/opmls

Change Vagrantfile to use new playbook during provisioning:

Vagrantfile#

Vagrant.configure("2") do |config|
  # ...
  config.vm.provision "ansible" do |ansible|
    ansible.playbook = "playbooks/vagrant.yml"
    ansible.verbose = "v"
  end
end