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:
# -*- 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:
- 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
Vagrantfile to use new playbook during provisioning:
Vagrant.configure("2") do |config| # ... config.vm.provision "ansible" do |ansible| ansible.playbook = "playbooks/vagrant.yml" ansible.verbose = "v" end end