How to: Install InterWorx Control Panel¶
Contents
Note
Minimum server requirements, supported VPS systems, and supported operating system information can be found 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
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:
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:
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 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:
[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
typescreen -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 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.