Guide - Ansible4IOM Tutorial 1.0 - 1.1

1 Introduction

Ansible4IOM is a tool of the Intershop Order Management (IOM) for automated server configuration management. Additionally, operational tasks are predefined in operational processes which can be customized by using hooks.

This guide gives a short tutorial of how to use Ansible4IOM and how to become familiar with it. The target group of this document are developers of a project as well as system administrators.

1.1 Glossary

Term
Description
Ansible4IOMAnsible4IOM is a tool of IOM for server configuration management. Additionally operation tasks are predifined and can be customized.
AzureA cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through a global network of Microsoft-managed data centers.
CIContinous integration
Configuration RepositoryIn the scope of Ansible4IOM a configuration repository is a set of configurations that describes the used machines, values of variables hooks and more. It's a descripton of how to install a custom IOM.
DBDatabase
EPELExtra Packages for Enterprise Linux is a repository of the Fedora-Project (https://fedoraproject.org/wiki/EPEL).
FSFile system
Gluster-FSA scale-out network-attached storage file system
HookHooks are part of Ansible4IOM. Hooks are a sophisticated way to customize processes. Additionally the behavior of processes can be simply customized by various variables.
IOMThe abbreviation for Intershop Order Management
IOM WatchdogA tool of IOM to monitor and manage the availablity of IOM application servers
JMSJava Message Service
OMSThe abbreviation for Order Management System, the technical name of the IOM
PGPostgreSQL
RHEL

Red Hat Enterprise Linux

SQLStructured Query Language

1.2 References

and

and

2 Foreword

The following example is not intended to work as a best practice document. This tutorial has the intention to enable users to go their first steps with Ansible4IOM done as easy as possible. Before turning this into production, you should read all the available documentation provided for Ansible (http://docs.ansible.com/ansible) and you should be familiar with Linux-administration.

To make the example as easy as possible, client machine and Ansible Control Machine are identical. Nevertheless a kind of configuration was chosen that makes it easy to split the example to different machines.

3 Requirements

You will need a Linux machine running Centos 7.3 or RedHat 7.3. with root access to this machine.
Furthermore, a regular user account is required. For the following examples use this regular user account only, except otherwise noted.

4 Setup of Ansible Control Machine

4.1 Install Ansible

Ansible has to be installed on Ansible Control Machine only, not on clients, where IOM, PostgreSQL, etc. will be installed.

Ansible is part of Extra Packages for Enterprise Linux (EPEL), which is a community repository of non-standard packages for the RHEL distribution.

  1. Install the EPEL repository.

    Install the EPEL repository
    # as root on Ansible Control Machine do
    sudo yum -y install epel-release
    sudo yum repolist
  2. Install Ansible and any required packages.

    Ansible Installation
    # as root on Ansible Control Machine do
    sudo yum -y install ansible

4.2 Install Ansible4IOM

  1. Download the latest version of Ansible4IOM from the Intershop Repository. Extract the package into home directory of the regular user on the Ansible Control Machine.

5 Prepare Client Machine for IOM Installation

5.1 Create an Ansible User

You have to create a user ansible on all client machines. Since the example combines Ansible Control Machine and client, the user has to be created locally at your machine.

This user has to be able to execute every command passwordless via sudo. To do so, add the user to group wheel and make sure wheel is able to execute sudo without entering password.

  1. Create an Ansible user.

    create ansible user
    # as root on client machine do
    # create user ansible, add the new user to group wheel
    useradd -m -G wheel -U ansible
    # set password for user ansible
    passwd ansible
  2. Ensure that the file /etc/sudoers contains the following lines.

    make sure, file /etc/sudoers contains following lines
    ## Allows people in group wheel to run all commands
    # %wheel        ALL=(ALL)       ALL
     
    ## Same thing without a password
    %wheel  ALL=(ALL)       NOPASSWD: ALL
  3. Allow passwordless sudo for group wheel.

    allow passwordless sudo for group wheel
    # as root on client machine do
    # edit /etc/sudoers using visudo only, otherwise it might be possible to lockout yourself.
    visudo

5.2 Allow passwordless Remote Access for Ansible User

To allow passwordless access from Ansible Control Machine to client machine, you have to add the public key of your regular user account on Ansible Control Machine to ~/.ssh/authorized_keys file of Ansible user on client machine.

If you don't have a ssh-key-pair for your regular user account on Ansible Control Machine yet, you have to create one.

  1. Create a key-pair.

    create key-pair
    # as regular user on Ansible Control Machine do
    ssh-keygen -t rsa

    You will be prompted for a location to save the keys, and a passphrase for the keys. Accept default location and create keys without passphrase.

  2. Transfer the public key to th account of user ansible on the client machine.

    transfer public key to Ansible user on client machine
    # as regular user on Ansible Control Machine do
    ssh-copy-id ansible@localhost

    When copying the public key, you will be asked for the password of the Ansible user. Enter the password you have chosen, when creating user ansible.

  3. Test passwordless remote access to user ansible on the client machine.

    test passwordless access to user ansible on client machine
    # as regular user on Ansible Control Machine do
    ssh ansible@localhost

For further information on key ssh key generation and installation have a look at https://help.ubuntu.com/community/SSH/OpenSSH/Keys.

5.3 Oracle JDK

IOM requires Oracle JDK 8 to run. It has to be installed before running the setup process.

Installation directory

The installation directory has to be set in the inventory file at variable OMS_JAVA_HOME.

6 Setup configuration repository

The only thing that is still missing before starting IOM installation is the configuration repository, which holds all information about the IOM setup.

6.1 Setup directory structure

In real live environments, the configuration repository should be managed in some kind of source code control system. For purpose of demonstration, it's fully sufficient to create the configuration repository locally at Ansible Control Machine.

  1. Create the following directory structure in the regular users home directory on the Ansible Control Machine.

    directory layout
    ~/config-repo/                 # base directory of configuration repositories
        plain-oms/                 # base directory for all plain IOM installations
           localdemo/              # configuration directory of demo-installation
              installation_hooks/  # directory to hold hooks to be applied in current installation only
              group_vars/          # directory to hold group specific configurations

6.2 Setup Inventory File

The inventory file is the central source of information of any installation managed by Ansible.

  1. Create the file at following location: ~/config-repos/plain-oms/localdemo/inventory

    ~/config-repos/plain-oms/localdemo/inventory
    ################################################################################
    # hosts
    ################################################################################
    localhost ansible_host=localhost ansible_port=22 ansible_user=ansible
    
    ################################################################################
    # global variables
    ################################################################################
    [all:vars]
    PG_VERSION='9.6'
    OMS_JAVA_HOME='<path to Oracle JDK>'
    OMS_VERSION=2.2.0.0
    OMS_REPO_URL=https://repository.intershop.de/oms-releases
    OMS_REPO_USER=<your account name>
    OMS_REPO_PASSWD=<your password>
    
    # control setup of PostgreSQL-server
    PGSERVER_SUPERUSER="postgres"
    PGSERVER_SUPERUSER_PASSWD="s3cr3t"
     
    # control setup of IOM DB-account
    OMSDB_HOST="localhost"
    OMSDB_SUPERUSER="{{PGSERVER_SUPERUSER}}"
    OMSDB_SUPERUSER_PASSWD="{{PGSERVER_SUPERUSER_PASSWD}}"
     
    # control setup of IOM
    is_oms_db_hostlist="localhost:5432"
    is_oms_db_name="dbname"
    is_oms_db_user="oms_user"
    is_oms_db_pass="dbpasswd"
    is_oms_jms_hostlist="127.0.0.1:8080"
    
    ################################################################################
    # groups
    ################################################################################
    [pg_server]
    localhost
    
    [oms_single_node]
    localhost

The example inventory does not contain any email configuration (smtp-server, email-addresses), hence, the email functionality of IOM will not work. For the purpose of this document, the missing email functionality of IOM, is acceptable. For any other system (developer, pre-production, production, etc.) it is of course not.

The inventory file can only hold simple variables. Complex variables, hashes, arrays or combinations of both, can only be defined in group_vars and host_vars. Since the list of trusted hosts for PostgreSQL-server is an array, it has to be defined in ~/config-repo/plain-oms/localdemo/group_vars/pg_server.

~/config-repo/plain-oms/localdemo/group_vars/pg_server
PGSERVER_TRUSTED_HOSTS: [ "::1", "127.0.0.1" ]

For more information, see description of Process - Setup Postgres Server 1.0, Process - Setup or Reconfigure Database Account 1.0 and Process - Setup OMS Node 1.0.

6.3 Setup Hook

To get a better understanding of the hook concept, the example contains a simple hook-implementation too, which extends log-messages provided by PostgreSQL-server (see process Process - Setup Postgres Server 1.0). Fill the file ~/config-repos/plain-oms/localdemo/installation_hooks/post_pgserver_configuration_hook.yml with following Ansible code:

~/config-repos/plain-oms/localdemo/installation_hooks/post_pgserver_configuration_hook.yml
- name: update postgreSQL configuration for extended logging
  ini_file:
    dest: "{{PGSERVER_DATA}}/postgresql.conf"
    section: ""
    option: "{{item.option}}"
    value: "{{item.value}}"
  with_items:
    - { option: log_destination, value: "'stderr,csvlog'" }
    - { option: log_filename, value: "'pg-{{inventory_hostname}}_{{PGSERVER_PORT}}-%Y%m%d%_%H%M.log'" }
    - { option: log_rotation_age, value: 30 }
    - { option: log_truncate_on_rotation, value: "off" }
    - { option: log_min_duration_statement, value: 250 }
  become: true
  become_user: "{{PGServerOSUser}}"

7 Install IOM

Once the configuration repository is prepared, the installation process can be started. It consists of three steps

A load-balancer is not needed, when using IOM standalone installation.

  1. Setup Postges Server.

    setup_pgserver
    ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
    ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
    ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
    ~/Ansible4IOM/processes/setup_pgserver.yml
  2. Setup OMS database.

    setup_omsdb
    ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
    ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
    ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
    ~/Ansible4IOM/processes/setup_omsdb.yml 
  3. Setup OMS node.

    setup_oms_node
    ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
    ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
    ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
    ~/Ansible4IOM/processes/setup_oms_node.yml

8 Access IOM Installation

Now the IOM installation is ready to be used. You can access the Web-GUI at http://localhost:8080/omt/app/start. Use the following credentials to log in:

  • Account: admin
  • Password: !InterShop00!

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets