8. The Tower Installation Wizard
The Tower setup process consists of two parts–an installation wizard that determines your Tower configuration and a setup playbook that uses that information to install Tower.
The Tower Installation Wizard and the Tower setup playbook do not need to be run from the system that will run Tower, although they can. The Tower Installation Wizard asks for credentials needed to access external systems where necessary.
The Tower Installation Wizard is invoked as configure from the path where you unpacked the Tower installation tarball. It writes a file called tower_setup_conf.yml which contains the configuration for Tower.
username@localhost:~$ ./configure
8.1. Installation Arguments
The wizard takes the following arguments:
-h, --help Displays a brief usage summary.
-l, --local Assumes that you are installing Tower on the
local machine where you are running configure. This implies an
internal embedded PostgreSQL database as well. This option skips some
questions in the wizard.
--no-secondary-prompt Assumes you are not installing in a
high-availability setup. This option skips some questions in the
wizard.
-A, --no-autogenerate Do not autogenerate random passwords
for PostgreSQL or Redis–prompt the user for them instead.
-o FILE, --options-file=FILE Use the file FILE as a source of answers. This can be the tower_setup_conf.yml file from a previous run of the wizard. Depending on the contents of the file, this option skips some questions in the wizard. The contents of the tower_setup_conf.yml file may look similar to the following:
admin_password: password
database: internal
munin_password: password
pg_password: cmTM4eaCpnDS54ReXGv34szoHQiXccFno3atfBij
primary_machine: localhost
redis_password: 8nG2TRpSDnpr69eWbqFwXTbryCUW64r76VjBqsKx
Once you invoke the Tower Installation Wizard, you are asked about the configuration of a few different items.
8.2. Primary Tower machine configuration
First, the Tower wizard asks about where you intend to place the primary (or only) Tower instance.
root@localhost:~$ ./configure
-------------------------------------------
Welcome to the Ansible Tower Install Wizard
-------------------------------------------
PRIMARY TOWER MACHINE
Tower can be installed (or upgraded) on this machine, or onto a remote machine
that is reachable by SSH.
Note: If using the High Availability features of Tower, you must use DNS
resolvable hostnames or IP addresses (do not use "localhost").
Enter the hostname or IP to configure Ansible Tower
(default: localhost):
If you are installing on the current machine, enter localhost or
127.0.0.1 for the current machine. If you are installing on a
different machine, enter the IP address or hostname of the machine. This
machine must be running and accessible via SSH when running the setup
playbook later.
8.2.1. Configuring the Database
Tower can be setup as an internal database installed on the primary Tower machine or as an external PostgreSQL database.
Enter i for an internal database on the same machine as Tower, or e for an external database. To run Tower in a high-availability configuration, you must use an external database.
DATABASE
Tower can use an internal database installed on the Tower machine, or an
external PostgreSQL database. An external database could be a hosted database,
such as Amazon's RDS.
An internal database is fine for most situations. However, to use the High
Availability features of Tower, an external database is required.
If using an external database, the database (but not the necessary tables) must
already exist.
Will this installation use an (i)nternal or (e)xternal database?
If you choose to use an external database, the wizard prompts you for the following additional database parameters:
- Database host to connect to
- Database name
- PostgreSQL user to use to access the database
- Password for the above PostgreSQL user
- Port to connect to the PostgreSQL database on (hit enter for the
default PostgreSQL port)
The wizard will attempt to verify these parameters if your system has
the PostgreSQL client libraries installed.
8.3. Secondary Installation (if applicable)
At this time, if you chose to setup an external database, you can configure
any neccessary secondary Tower instances.
SECONDARY MACHINES
You may optionally elect to add any number of secondary machines, on which
Ansible Tower will also be installed (in secondary mode).
Add secondary machines (y/n)?
Enter y to configure additional secondary Tower instances.
Enter the hostnames or IP addresses of machines you want to configure as
secondary Tower instances, one at a time. Enter a blank line to end the
list. These machines must be running and accessible via SSH when running
the setup playbook later.
8.4. Passwords
You are then prompted for the passwords you need for various Tower
services.
PASSWORDS
For security reasons, since this is a new install, you must specify the
following application passwords.
The installation wizard prompts you to provide an Admin Password. This ‘admin’ password is used for the first user (and superuser) created upon installation. You must have this password for your initial login to Tower.
If you passed the -A or --no-autogenerate parameters to the Installation Wizard, you are prompted for a PostgreSQL password and a Redis password. These are used internally to Tower and are not needed by the admin at runtime. These additional passwords are normally auto-generated as a random value.
Note
Once Tower setup has been completed, you can log into the instance via SSH and it will provide the default admin password in the prompt. The admin password can be changed with the following command (as root or as AWX user): tower-manage changepassword admin
After that, the password you’ve entered will work as the admin password in the web UI.
8.4.1. Password Strength Configuration
This feature allows you to define minimum strengths for passwords. Password strength configuration for Tower specifies policies and security mechanisms for providing rules to specify user passwords.
To make use of this feature, set your preferred password strength configuration options in a local_settings.json file.
Next, set the password_* variables to true/false based on the rules you want to enforce.
The password strength configuration feature allows you to create passwords of any combination of upper and lowercase characters, numbers, and special characters that include “!”, “@”, “#”, “$”, “%”,“^”, “&”, “*”, “(“, and “)”.
You can also set the password’s minimum (1) and maximum (64) length. The recommended minimum password length is eight (8) characters.
8.6. Review and Confirm
You are then asked to review the settings you entered. An example would
be:
REVIEW
You selected the following options:
The primary Tower machine is: tower.example.com
Tower will operate on an EXTERNAL database.
host: database.example.com
database: mydb
user: db_admin
password: ********
port: 5432
Additional secondary machines:
- tower-backup.example.com
- tower-backup2.example.com
Using SSH user: jdoe
Are these settings correct (y/n)?
Select y, and you will then be given some information on running the
setup playbook.
FINISHED!
You have completed the setup wizard. You may execute the installation of
Ansible Tower by issuing the following command:
# Add your SSH key to SSH agent.
# You may be asked to enter your SSH unlock key password to do this.
ssh-agent bash
ssh-add ~/.ssh/id_my-example-key
./setup.sh -s
8.7. Reviewing the Tower Configuration
The Tower configuration is written into two files by the Tower
Installation Wizard.
tower_setup_conf.yml This Tower configuration file contains
needed Tower passwords, database connection information, and machine
connection information.inventory This includes the machines that the setup playbook will
operate on, grouped into the primary and secondary groups of
nodes.
8.8. The Setup Playbook
The Tower setup playbook is invoked as setup.sh from the path where
you unpacked the Tower installer tarball. It uses the
tower_setup_conf.yml and inventory files written by the Tower
Installation Wizard. The setup script takes the following arguments:
-h, --help Displays a brief usage summary.-c FILE Use the specified FILE as the Tower configuration file rather than tower_setup_conf.yml in the current directory.-i FILE Use the specified FILE as the inventory for the setup playbook rather than inventory in the current directory.-p Set ansible to prompt for a SSH password when connecting to remote machines-s Set ansible to prompt for a sudo password on remote machines when installing Tower.-u Set ansible to prompt for a su password on remote machines when installing Tower.-e Set additional ansible variables for the playbook to use either in key=value or YAML/JSON form. This should not be needed in normal operation.-b Perform a database backup in lieu of installing.-r BACKUP_FILE Perform a database restore in lieu of installing.
Depending on the configuration you entered when running the Tower
Installation Wizard, it may have prompted you to run the setup playbook
with some combination of -p, -s, or -u.
After calling setup.sh with the appropriate parameters, Tower is installed on the appropriate machines as has been configured.
Once installed, if you log into the Tower instance via SSH, the default admin password is provided in the prompt. You can then change it with the following command (as root or as AWX user):
tower-manage changepassword admin
After that, the password you have entered will work as the admin password in the web UI.
