Installation

Install a SIDRE instance
Tags:
Categories:

Installation / Update

A SIDRE instance can be installed fully automatically via Ansible scripts. The latest stable version of the scripts is available in the stable branch of the specific setup repository, for example oersi-setup for OERSI. Every derived SIDRE instance has its own setup-repository that is used for the installation.

The installation processes will install all components that are necessary to run sidre (elasticsearch, tomcat, nginx, etc). To avoid conflicts, it is recommended that no other applications / processes are running on the target system.

Depending on the scenario, there are different possibilities to install sidre. To test the index a little with minimal effort, you can use a local installation in the local VirtualBox VM via vargant. The other installation methods are suitable for installing the index on an existing system that is accessible via ansible. Of these, the installation via gitlab-ci is clearly recommended for production use.

Note that all installations (especially the initial one) will take some time (depending on your download speed), because all necessary components will be downloaded.

Requirements

  • OS: Debian - tested with Bullseye (11) and Bookworm (12)
  • Recommended min resources: 6GB RAM, 2 CPUs
  • Ansible - tested with Ansible 2.16

Automatic installation via gitlab ci

Scenario: Install sidre on an existing system. Can be controlled via the UI of gitlab and can even be started on a scheduled basis. In addition, the environment from which the installation is performed is always the same, since this is done via docker containers, and you don’t run into conflicts due to different versions of Ansible on the installation host. This makes it more suitable for installations on production systems, as the installation becomes more stable. This process is the integration of the “direct” installation process (via ansible-playbook) into the CI of gitlab.

  • Create a new private gitlab project that will contain the configuration for your specific sidre-systems
  • Assure your gitlab-project is able to connect to your sidre-systems via ssh
    • Create an ssh-key for the automatic installation via gitlab
    • Your public ssh-key needs to be added to the authorized_keys file on your sidre-systems 
      vi ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
    • go to Settings -> CI / CD -> Variables of your project in gitlab and add variables
      • SSH_KNOWN_HOSTS - contains entries for your sidre-systems
      • SSH_PRIVATE_KEY - your private ssh-key
  • Use .gitlab-ci.yml and prerequisites.yml from the gitlab-config-example
  • Create your own inventory-files and config-files with help of inventory_DEV.yml, config_DEV.yml, inventory_TEST.yml and config_TEST.yml
    • When you adjust the filenames of your files, please assure to also adjust the filenames in .gitlab-ci.yml
    • Assure root access via ansible connection variables like ansible_become_password.
  • Now you should be able to update your systems via your gitlab-project
    • Call: CI / CD -> Pipelines -> Latest
    • Click the “Play”-Button for the system you want to update
  • Optionally you can activate Continuous Delivery
    • Create a Gitlab-Schedule in your project CI / CD -> Schedules
    • uncomment “scheduled deployment” section in .gitlab-ci.yml and adjust to your inventory-filename

Run it locally with VirtualBox

Scenario: To test the index a little bit with minimal effort, you can use a local installation in the local VirtualBox VM via vargant. This is also suitable for developers to perform “system tests” for their changes.

Prerequisites

Perform the following steps in the terminal (Linux / macOS) or in the GitBash (Windows).

  1. Clone your setup repo
  2. Change into the directory of your setup repo
  3. Start the virtual machine with 
    vagrant up

When the installation is complete (a few minutes, depending on the download speed), the index can be opened in the browser. The IP address of your Vagrant machine can be found in the Vagrantfile of your setup-repository.

You can stop the virtual machine with

vagrant halt

… and start again with

vagrant up

If you want to reload the configuration (including the import from the oer sources), perform

vagrant reload --provision

The VM can then simply be thrown away at any time with vagrant destroy.

Direct installation

Scenario: Install sidre on an existing system directly via the ansible-playbook. Can be used if installation via gitlab is not possible (e.g. because no internal gitlab instance exists and the sidre system is not accessible from gitlab.com). Note for developers: this method is also suitable for installations on the VirtualBox VM. Since you can work with your own inventory file, you can test the complete custumizations of your production environment on the VM without having to make changes in the group_vars of the Vagrant Box.

  • requirements:
    • ansible installed on the local computer
    • Install your version via pip for example: pip3 install ansible-core==2.16.10
  • clone setup-project
  • install ansible galaxy dependencies:
    • ansible-galaxy install -r requirements.yml
  • create ansible inventory and config files (see gitlab-config-example for an example) and adjust all variables to your installation (see variables in ansible/playbooks/group_vars)
    • For Ansible-installations on the target system itself, just use a local connection in the inventory.yml: 
      searchindex:
  hosts:
    localhost:
      ansible_connection: local
      ansible_become_method: su
      ansible_become_password: changeme
  • run ansible-playbook -v -i inventory.yml --extra-vars @default-config.yml --extra-vars @config.yml search_index.setup.system
    • you can also install single modules via ansible-playbook -v -i inventory.yml --extra-vars @default-config.yml --extra-vars @config.yml search_index.setup.<MODULE>