Ubersmith Installation and Upgrade Utility Estimated Reading Time: 7 Minutes 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. This utility only supports upgrading Ubersmith installations running version 4.0 or newer. It does not support directly upgrading older versions of Ubersmith. If you would prefer to have Ubersmith perform your update or installation, please contact Ubersmith Support to discuss the scope of the project and to arrange for a quote from our Managed Services team. Installation Preparing the Host Ensure your host has been updated to the latest available packages as well as the latest Linux kernel. If necessary, reboot to ensure the system is running the latest kernel. Please ensure the system time zone is set to the time zone you will prefer to use with Ubersmith, as changing it after the installation may not be possible without encountering issues with service renewals. Installing Dependencies The installation process will fail without these dependencies: CentOS / Rocky Linux CentOS 9 Stream sudo dnf remove buildah podmansudo dnf install gcc libffi-devel python3-devel python3-PyMySQL openssl-develsudo alternatives --install /usr/bin/python python /usr/bin/python3.9 1 Rocky Linux 9 (Ubersmith 5.x+ only) sudo dnf remove buildah podmansudo dnf install gcc libffi-devel python3-devel python3-PyMySQL openssl-develsudo alternatives --install /usr/bin/python python /usr/bin/python3.9 1 Debian / Ubuntu LTS Debian 11 sudo apt install build-essential libssl-dev libffi-dev python3-dev python3-setuptools python3-pymysql python3-pip python3-venv python3-dockersudo update-alternatives --install /usr/bin/python python /usr/bin/python3.9 1 Debian 12 sudo apt install build-essential libssl-dev libffi-dev python3-dev python3-setuptools python3-pymysql python3-pip python3-venv python3-dockersudo update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1 Ubuntu 22.04 LTS sudo apt install build-essential libssl-dev libffi-dev python3-dev python3-setuptools python3-pymysql python3-pip python3-venvsudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1 If you are installing an external Percona Server for MySQL server, please follow the instructions outlined here to install the database time zone tables prior to installing Ubersmith. Installing Docker Note: If you are installing Ubersmith on Rocky Linux, you will not be able to use the script from get.docker.com described below. Instead, follow the documentation provided by the Rocky Linux project, found here. The Ubersmith Installer requires that Docker, as well as the additional dependencies outlined above, be installed prior to installing Ubersmith. The script located at https://get.docker.com/ 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 Downloading a Release On the host Ubersmith is to be installed on, download a tarball release of the installer from the Releases page on Github. The latest version of the Installation and Upgrade Utility will always install the latest version of Ubersmith and the Appliance. The version of Ubersmith and the Appliance that will be installed is noted as a comment for each Release. For example, release 3.0.0 of the Installation and Upgrade Utility will install / upgrade Ubersmith 5.0.0 and Appliance 5.0.0. Older versions of Ubersmith can be installed with older versions of the Installation and Upgrade Utility. For example, version 2.2.5 of the Installation and Upgrade Utility will install / upgrade Ubersmith 4.6.4 and Appliance 4.6.3. To determine the version of Ubersmith your installation is currently running, see the "License Details" page within "Settings". Installing As root, run ./install_ubersmith.sh to install Ubersmith Core or ./install_appliance.sh to install the Ubersmith Appliance. Ubersmith Core and Ubersmith Appliance should not be deployed to the same host. 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 hostname 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. Configuring 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: https://10.0.0.1 or, if you have a DNS record created, use that name directly: https://ubersmith.example.com Ensure you are connecting via HTTPS, and walk through the steps of the Ubersmith Setup Wizard. Database If you are using a remote database server for Ubersmith, ensure that you have configured your cluster nodes to use the sql_mode directive: NO_ENGINE_SUBSTITUTION No other directives are required or supported, and enabling them will lead to issues with Ubersmith's performance. Searching When configuring the Solr search engine, use the values: Host: solr Port: 8983 Path: /solr/collection1 Licensing When 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. During the installation process, the Python package manager pip will install the needed binaries for Ansible and Docker to ~/.local/bin. You should run: export PATH="$HOME/.local/bin:$PATH" to ensure these binaries are readily available to you from the command line. Failure to do so may cause the following commands to fail, indicating that the command cannot be found. At the end of the Setup Wizard, you will be prompted to delete the setup directory. Change to the directory you deployed Ubersmith to (by default /usr/local/ubersmith) and run: docker-compose exec web rm -rf /var/www/ubersmith_root/app/www/setup With the /setup directory removed, the Ubersmith web user interface will now load, and the login page will appear. Log in with the username and password created during the installation process. Ubersmith Appliance When the Ubersmith Appliance installation is complete, the installation utility will output the connection credentials necessary for configuration. Make a note of this username and password pair, as they will be used for the Appliance configuration in the Ubersmith user interface. Upgrading Before upgrading, be sure to backup your Ubersmith database. Before upgrading, ensure you have the latest version of the installation / upgrade utility. Downloading a Release On the host Ubersmith is to be installed on, download a tarball release of the installer from the Releases page on Github. The latest version of the Installation and Upgrade Utility will always install the latest version of Ubersmith and the Appliance. The version of Ubersmith and the Appliance that will be installed is noted as a comment for each Release. For example, release 3.0.0 of the Installation and Upgrade Utility will install Ubersmith 5.0.0 and Appliance 5.0.0. Older versions of Ubersmith can be installed with older versions of the Installation and Upgrade Utility. 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 root's home directory. If upgrading from a version of Ubersmith prior to 4.2.0, make sure to add volume entries in docker-compose.override.yml to include mount points for the appropriate time zone files in each service (web, mail, php, etc.). For example: php: volumes: - "/etc/localtime:/etc/localtime" Failing to make this update will cause those containers not updated to default to using UTC as a timezone. When upgrading from versions prior to Ubersmith 4.3.0, a change is being made to the naming convention for the database host. Prior versions had the database host defined as ubersmith_db_1, newer versions define it as simply db. Please contact support at ubersmith.com to ensure your license record is updated if you encounter issues post-upgrade. To upgrade Ubersmith, run the ./upgrade_ubersmith.sh script. The upgrade process will complete automatically. Troubleshooting When running CentOS, if the installer is unable to install pip, you may need to enable the EPEL yum repository.