Summary
The Ubersmith Installer is a command line utility that allows a system administrator to install (or upgrade) Ubersmith on a supported platform without assistance from Ubersmith Support. This can be useful when access to the Ubersmith environment is restricted, or for provisioning development/testing environments. The installer can be used to install both the Ubersmith Core (frontend) software as well as the Ubersmith Appliance.
Ensure that your host has been updated to the latest available packages as well as the latest Linux kernel. If necessary, reboot to ensure that the system is running the latest kernel.
The Ubersmith Installer requires that Docker, as well as some additional dependencies be installed prior to installing Ubersmith. The script located at:
can be helpful when installing Docker. Ensure that Docker is configured to start on boot; in many cases it may not be. Depending on the operating system used, you may be able to enable the docker service with:
# systemctl enable docker |
Ensure that Docker is up and running:
# service docker start |
The installation process will fail without these dependencies.
$ sudo yum install gcc libffi-devel python-devel openssl-devel epel-release |
Once EPEL is configured, run:
$ sudo yum install python-pip |
$ sudo apt install build-essential libssl-dev libffi-dev python-dev python-setuptools |
On the host Ubersmith is to be installed on, clone the ubersmith_installer repository.
$ git clone https://github.com/TeamUbersmith/ubersmith_installer.git |
Alternatively, you can download a tarball release of the installer from here.
As root, run ./install_ubersmith.sh to install Ubersmith Core or ./install_appliance.sh to install the Ubersmith Appliance. Ensure the path you choose can be written to by the user running the installation script, and that the user is a member of the docker group.
Follow the prompts to complete the installation.
Checking for pip... Installing Ansible... Installing Ubersmith... Choose an installation directory for Ubersmith [/usr/local/ubersmith]: Enter the address where you will be hosting Ubersmith [ubersmith.example.com]: Enter the email address of the Ubersmith administrator [admin@example.org]: |
At this point the installer will begin, and will create the directory structure and supporting files to bring Ubersmith online.
Ubersmith Core and Ubersmith Appliance should not be deployed to the same host.
Ubersmith is now listening for HTTPS connections; to load the Ubersmith installation wizard go to the address of IP of your Ubersmith host in your web browser, for example:
Walk through the steps of the Ubersmith Setup Wizard.
The Setup Wizard still has some legacy configuration steps relating to configuring Cron Tasks and Postfix aliases. These steps can be ignored, they are configured automatically during the installation process. These pages will be removed in an upcoming release. You may also encounter an error regarding a missing Zookeeper PHP module, this can also be ignored. |
When configuring the Solr search engine, use the values:
ubersmith_solr_18983/solr/collection1When prompted for license details, enter the licensing username and password provided to you by Ubersmith Support. If you do not have licensing details, please contact Ubersmith Support for assistance.
At the end of the Setup Wizard, you will be prompted to delete the setup directory. The command provided does not account for the Ubersmith webroot being located in a container, so run the following command instead:
# docker exec ubersmith_web_1 rm -rf /var/www/ubersmith_root/app/www/setup |
Before upgrading, be sure to back up your Ubersmith database.
On the host Ubersmith is to be installed on, clone the ubersmith_installer repository.
$ git clone https://github.com/TeamUbersmith/ubersmith_installer.git |
Alternatively, you can download a tarball release of the installer from here.
If you have never used the Ubersmith installation / upgrade utility before, configuration is necessary. Without running the configuration step, the upgrade utility will fail. |
As root, run configure.sh to configure the location of your existing Ubersmith installation, as well as your Ubersmith URL/address, and an email address associated with the Ubersmith administrator. Follow the steps to configure your environment:
$ ./configure.sh Configuring the Ubersmith installer for an existing installation... Current path in use by Ubersmith / Appliance [/usr/local/ubersmith]: Enter the address in use by Ubersmith / Appliance [ubersmith.example.com]: ubersmith.mydomain.com Enter the email address of the Ubersmith administrator [admin@example.org]: jsmith@mydomain.com [ output follows ] localhost : ok=3 changed=1 unreachable=0 failed=0 |
This step creates the file .ubersmith_installer.ini in the home directory of the user running the configuration utility.
If upgrading from a version of Ubersmith prior to 4.2.0, make sure to add
Failing to make this update will cause those containers not updated to default to using UTC as a timezone. |
To upgrade Ubersmith, run the ./upgrade_ubersmith.sh script. The upgrade process will complete automatically.
Troubleshooting
pip, you may need to enable the EPEL yum repository.python-setuptools will install the easy_install utility, which will allow the installer to install a more contemporary version of pip.pip will installed using the --user option, which will install to the Python user install directory for your platform; typically ~/.local/. (See the Python documentation for site.USER_BASE for full details.) This allows for the installer to be executed as a non-root user. You may want to add this directory to your PATH shell variable so that the supporting utilities (docker-compose, for example) can be run without having to specify the full path to the utility.