How to: Install InterWorx Control Panel
=======================================
.. contents::
.. note::
Minimum server requirements, supported VPS systems, and supported operating system
information can be found :doc:`here `.
.. warning::
InterWorx does not support containerized environments, including Docker or LXC.
.. note::
While InterWorx will install and work on both Digital Ocean and Azure, both of those services block port 25, which
is the port that the mail service included with InterWorx (Qmail) uses. An outside mail provider will be
required in those environments.
Prerequisites
-------------
#. A server or supported VPS system, with at least the minimum supported
hardware configuration
#. A clean install of one of the supported operating systems. Please note: for
new installs, the most up-to-date version of each OS is required
#. :doc:`A valid active InterWorx Control Panel license key `
#. UIDs 102 → 107 and GIDs 102 and 103 must be free for use. The build of the
qmail MTA the InterWorx Control Panel uses requires these UID/GIDs to be
available
**If using Red Hat Enterprise Linux 7 (RHEL 7)** the following commands must also be run to enable the required
dependency repos:
.. code-block::
subscription-manager repos --enable rhel-7-optional-rpms
subscription-manager repos --enable rhel-7-extras-rpms
subscription-manager repos --enable rhel-ha-for-rhel-7-server-rpms
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
**If using Red Hat Enterprise Linux 8 (RHEL8)** the follow commands may need to be run to enable the required
dependency repos:
.. code-block::
subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
InterWorx Install Script Overview
---------------------------------
The current list of installed
packages can always be found on the updates.interworx.com RPM repository,
located at \ `http://updates.interworx.com/iworx/RPMS/
`__. The repository is
indexed by distribution.
Supplemental software packages are
also available as SRPMS, which are located at \
`http://updates.interworx.com/iworx/SRPMS/
`__
InterWorx is installed via a bash script which makes the following
changes to the server:
#. Deactivates SELINUX
#. Moves ``/home/`` to /``chroot/home/``, if ``/home`` is not on its own
partition. It then symlinks ``/chroot/home/`` to ``/home``
#. Uninstalls any conflicting RPM packages that are initially installed on the
server, using yum
#. Installs InterWorx and its supporting software, using yum
**Due to the change to the XFS filesystem, quotas must be enabled manually, and it is not part of the
InterWorx installation script.**
**Instructions on how to enable quotas can be found** :doc:`here `
#. As of InterWorx version 6.3.21, the installation script also updates the
server PHP and MySQL or MariaDB versions to the latest versions available.
This can be changed using the ``-m`` or\ ``-p`` flag when running the
install script. More detailed information is found below
The install script has a few optional parameters that can be useful for
installation in advanced environments, including specifying MySQL and
PHP versions, and installation repo. Those options can be found using
the ``-h``\ flag with the installation script:
.. code-block::
[root@server ~]# sh <((curl -sL updates.interworx.com/interworx/7/install.sh)) -h
Usage: iworx-cp-install.sh [-s rpm/ks server hostname] [-s server] [-d] [-f] [-u] [-k] [-l] [-i] [-h]
-s RPM server
Specify a different rpm host to grab src.rpm/rpms from
(default: updates.interworx.com).
-d Turn debugging on (you'll have to hit enter sometimes.
to keep things moving, output is halted so you can see it).
-f FORCE installation even if the distro isn't supported.
-u Perform a "yum update" prior to installation of
InterWorx-CP.
-k Force the removal of any conflicting packages that will
interrupt the InterWorx-CP install.
-l Run in headless mode. No prompting will occur.
-r Choose an interworx repository to enable. default: release.
(release,alpha,beta,release-candidate,stable)
-i Install all packages *except* InterWorx-CP itself.
-m Maria DB version to use. Specify "system" to use the version available via yum
-p PHP version to use. Specify "system" to use the version available via yum
-v Verbose output.
-h Show this help message."
[root@server ~]#
.. note::
Running the InterWorx installation script within a Linux screen session is
recommended. Screen creates a shell session that continues to stay active, even
if there is network disruption. Detailed information on using screen can be
found `here `__.
- To determine whether screen is installed on the system, run ``which screen``.
- If screen is installed, the system will return \ ``/usr/bin/screen``
- If screen is not already installed, it can be installed by running ``yum install screen``
To run the InterWorx script from within a screen session, type the word ``screen`` at the command line.
Then, run the InterWorx installation command.
If the session disconnects, log back in at the command line and
type\ ``screen -r``. This will reconnect the screen session.
How to install InterWorx 7
--------------------------
Links to interactive previews of NodeWorx and SiteWorx in
InterWorx 7 can be found `here `__
**If setting up a node for an existing Interworx cluster, it is highly
recommended to use same version as the rest of the servers in the cluster.**
.. warning::
In September of 2021, Let's Encrypt updated their certificate authority. A side effect of this is that some servers
with older ca certificates are unable to verify the certificates on the InterWorx repos. This issue normally
presents as there not being any output after running the install command, or an error stating "cannot verify
updates.interworx.com's certificate".
It is recommended to run either ``yum update``, or ``yum reinstall ca-certificates`` before running the install
script.
To install InterWorx 7:
#. Log in to the server at the command line as root, either via SSH or
from the terminal
#. Download and run the installer:
``sh <((curl -sL updates.interworx.com/interworx/7/install.sh))``
#. Alternatively, download and run the installer with no prompting:
``sh <((curl -sL updates.interworx.com/interworx/7/install.sh)) -l``
Next Steps
----------
After installing InterWorx, the next step is to activate the license. The license activation script
also sets up the master NodeWorx user account. Instructions on how to activate the InterWorx license can
be found :doc:`here `.
Troubleshooting
---------------
Conflicting Packages
^^^^^^^^^^^^^^^^^^^^
If package conflicts between the packages being installed and those that are already on the system occurs, keep an
eye on the output for conflict errors, and remove any conflicting packages that
are reported. After the conflicts are removed, simply re-run the installer and
it will continue where it left off.
The installer will try to remove packages preemptively, as well, (and prompt
where necessary before it removes anything).
No Output After Running Install Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In September of 2021, Let's Encrypt updated their certificate authority. A side effect of this is that some servers
with older ca certificates are unable to verify the certificates on the InterWorx repos. This issue normally
presents as there not being any output after running the install command, or an error stating "cannot verify
updates.interworx.com's certificate".
To resolve this issue, run either ``yum update``, or ``yum reinstall ca-certificates`` before running the
install script.