Installer wizard

This repository hosts the code used to generate wizards when using the installer feature of Packager.io.

How it works

The design is inspired from the debconf tool, used on debian-based systems, but works on all distributions supported by Packager.io (Debian, Ubuntu, CentOS, RHEL, Fedora, SUSE).

It is a simple collection of bash scripts used to iteratively launch the configure, preinstall, and postinstall steps of wizard addons.

Addons do what's needed to configure and install specific system dependencies for the package that is currently being configured. For instance, a GitLab package may use an installer that depends on an apache2 and mysql wizard addons.

The installer provides shell functions that abstract the setting/retrieval of configuration entries, and also displays interactive questions to the user.

Environment variables of note

• CURRENT_ADDON: folder name of the current addon being executed.
• WIZ_RECONFIGURE: if set to yes, all questions will be asked, whether they have already been answered or not.
• INSTALLER_DEBUG: if set to yes, all debug messages will be output on STDERR.

Main functions

wizard

Entry point of the installer wizard. Will call a state_machine function with the given argument (the starting "state"). The state_machine function must be defined in your addon, and must return 0 when the current state has been completed, as well as setting the next state to call using the global STATE environment variable.

Going back between states is automatically handled by the wizard function.

wizard "ask_for_db_info"

wiz_ask

Asks all the questions in the queue, delegating to wiz_dialog for each type of question. Returns 1 if wiz_dialog fails (i.e. the user chooses to "Exit" the question, or goes back).

if wiz_ask ; then
  # proceed to next set of questions
else
  # ask previous set of questions
fi

wiz_check_package

Checks whether a given package already exists on the system. Handles .deb and .rpm based systems.

Returns 0 if the package is already installed. Returns 1 if the package does not exist.

if wiz_check_package "mysql-server" ; then
	# proceed with database creation
else
	apt-get install mysql-server -y
fi

wiz_clear

Clears the buffer of questions to be asked. Mostly for internal use.

wiz_clear

wiz_debug

Will output the given message on STDERR if INSTALLER_DEBUG is set to yes.

wiz_debug "some message here"

wiz_dialog

Triggers the display of a new dialog box for a specific question. Questions are defined in a templates file at the root of each addon. The user answer will be stored in the database using wiz_set.

Returns 0 if the user's answer has been correctly stored.
Returns non-zero code if the user chooses to exit or cancel.
Returns non-zero code if the dialog type is unknown.

Supports the following dialog types:

• select (menu)
• string (text field)
• password (password field)
• boolean (yes/no question)

wiz_dialog "mysql/db_host"

wiz_fact

Returns facts about the underlying OS.

Supported facts:

• osfamily: returns the system's s family (debian, redhat, suse).

wiz_fact "osfamily" # => debian

wiz_get

Fetch the answer currently stored for a given question. Returns 0 if a value exists (including empty strings), and outputs it on STDOUT. Returns 1 if no value has been set yet.

if wiz_get "mysql/db_host" ; then
	db_host="$(wiz_get "mysql/db_host")"
	# do something with it
else
	# mysql/db_host is not set
fi

wiz_meta

Fetch a question's property from the corresponding templates file. Outputs the result on STDOUT.

wiz_meta "mysql/db_host" "description" # => MySQL IP or hostname
wiz_meta "mysql/db_host" "default" # => 127.0.0.1
wiz_meta "mysql/db_host" "type" # => string

It's possible to override a template based on the value of the key. For instance, if the user has already set the value skip for mysql/autoinstall, then the template mysql/autoinstall=skip will be looked up first, and then mysql/autoinstall will be looked up. This allows for more dynamic templates based on the previous user's input.

wiz_put

Adds a question to the buffer of questions to be asked. The question itself will be displayed to the user when wiz_ask is called.

A question will be displayed to the user if and only if:

• WIZ_RECONFIGURE is set to yes, or
• the question has not been answered yet, or
• the question has been marked as "unseen", using wiz_unseen method.

wiz_random_password

Generates a random password. Defaults to 32 characters long.

wiz_random_password 64 # => generates a 64 character random string

wiz_set

Sets a configuration variable in the database. Always suceeds, unless the database file is absent.

wiz_set "key" "value"

wiz_template

Returns the path to the current addon's templates file.

wiz_template # => mysql/templates

wiz_unseen

Manually sets the given question as unseen, meaning it will be displayed to the user even if it has already been answered.

wiz_unseen "mysql/db_host"

Helper functions

wiz_join

Helper function to join multiple strings, using a custom delimiter.

wiz_join ", " a b c d # => a, b, c, d

wiz_urlencode

Helper function used to URL encode a given string.

wiz_urlencode "mysql://user:pass@host:port/dbname?hello=world"

Available addons

• https://github.com/pkgr/addon-rails4 - General addon for Rails4 apps.
• https://github.com/pkgr/addon-mysql - Addon for configuring a MySQL server and database.
• https://github.com/pkgr/addon-smtp - Addon for configuring SMTP settings or sendmail.
• https://github.com/pkgr/addon-memcached - Addon for setting up a memcached server.
• https://github.com/pkgr/addon-apache2 - Addon for setting up an Apache2 server, including SSL.

Testing

Tests are located in the test folder. To run them:

test/wiz_get.sh
test/wiz_meta.sh

Set DEBUG=1 to have a more verbose output.