.. _ap-appendix-g:

######################################################
Appendix G – Installing Activation Pro on Ubuntu 26.04
######################################################

This appendix walks through installing RLM Activation Pro on a native LAMP stack (Apache,
MariaDB/MySQL, PHP) running on Ubuntu 26.04. This is a production-suitable install; for a
quick, disposable test environment instead, see :ref:`Appendix H <ap-appendix-h>`.

------

*****************
Install Updates
*****************

.. code-block::
	text

	sudo apt update && sudo apt upgrade -y

*********************
Install a LAMP Stack
*********************

**Apache:**

.. code-block::
	text

	sudo apt install -y apache2
	sudo systemctl enable --now apache2

**Database (MariaDB, recommended):**

.. code-block::
	text

	sudo apt install -y mariadb-server
	sudo systemctl enable --now mariadb

.. note:: The steps below assume you will add your own database user and create their
   credentials. Alternatively, you can use the following:

.. code-block::
	text

	sudo mysql
	CREATE USER 'actprouser'@'%' IDENTIFIED BY 'actprouserpassword';
	GRANT ALL PRIVILEGES ON *.* TO 'actprouser'@'%' WITH GRANT OPTION;
	FLUSH PRIVILEGES;
	EXIT;

No further authentication configuration is needed. Ubuntu 26.04's MariaDB defaults a plain
``CREATE USER ... IDENTIFIED BY`` to the ``mysql_native_password`` plugin automatically,
which is what the Activation Pro license generator binary (statically linked against MariaDB
Connector/C) expects.

Using MySQL instead of MariaDB
===============================

Ubuntu 26.04's ``mysql-server`` package defaults new user accounts to the
``caching_sha2_password`` authentication plugin. The Activation Pro license generator binary
is statically linked against MariaDB Connector/C and cannot load that plugin, which causes
license generation to fail with ``-1010 Can't read Activation database`` even though the
setup wizard itself completes successfully (the wizard's own PHP database connection is
unaffected: only the compiled generator binary's connection fails).

.. code-block::
	text

	sudo apt install -y mysql-server
	sudo systemctl enable --now mysql

To fix, enable the legacy ``mysql_native_password`` plugin and create the account with it
explicitly. This can only be turned on via a startup option, not a runtime ``SET GLOBAL``:

.. code-block::
	text

	sudo tee /etc/mysql/mysql.conf.d/actpro-auth.cnf > /dev/null <<'EOF'
	[mysqld]
	mysql_native_password=ON
	EOF
	sudo systemctl restart mysql

.. code-block::
	text

	sudo mysql
	CREATE USER 'actprouser'@'%' IDENTIFIED WITH mysql_native_password BY 'actprouserpassword';
	GRANT ALL PRIVILEGES ON *.* TO 'actprouser'@'%' WITH GRANT OPTION;
	FLUSH PRIVILEGES;
	EXIT;

Do this **before** running the setup wizard. If an account was already created with the
default plugin, fix it in place with:

.. code-block::
	text

	ALTER USER 'actprouser'@'%' IDENTIFIED WITH mysql_native_password BY 'actprouserpassword';

**PHP:**

.. code-block::
	text

	sudo apt install -y php libapache2-mod-php php-mysql php-gd php-curl php-mbstring
	sudo a2enmod cgid
	sudo systemctl restart apache2

.. note:: Installing ``libapache2-mod-php`` automatically switches Apache from ``mpm_event``
   to ``mpm_prefork`` (mod_php isn't thread-safe), and enabling ``cgid`` is required for
   Activation Pro's CGI license generator binary to run.

**Open the firewall:**

.. code-block::
	text

	sudo ufw allow 'Apache Full'

If ``ufw`` is inactive on your host, this step is a no-op. Check with ``sudo ufw status
verbose`` first.

**Verify everything is running:**

.. code-block::
	text

	sudo systemctl status apache2
	sudo systemctl status mariadb   # or: sudo systemctl status mysql
	php -v

***********************
Activation Pro Prep
***********************

Copy the v17.1 Activation Pro kit to ``/var/www/html``, using whatever file-transfer method
fits your environment (scp, sftp, etc.). Then extract the Activation Pro kit:

.. code-block::
	text

	cd /var/www/html/
	sudo tar -xvzf actpro.v17.1BL1-x64_l1.tar.gz

Copy the setup folder to ``/var/www/html``:

.. code-block::
	text

	sudo cp -r /var/www/html/actpro.x64_l1/actpro_setup /var/www/html/actpro_setup

Set ownership of ``/var/www`` so Apache can read and write all files. Ubuntu's Apache runs
as ``www-data``, not ``apache``:

.. code-block::
	text

	sudo chown -R www-data:www-data /var/www/

***********************************************
CGI Configuration for Activation Pro on Ubuntu
***********************************************

Ubuntu's ``apache2.service`` is sandboxed by systemd (specifically ``ProtectSystem=full``),
which makes ``/usr`` read-only to Apache regardless of ordinary file ownership. Ubuntu's
default cgi-bin directory (``/usr/lib/cgi-bin``) lives under ``/usr``, so copies into it
during setup will fail silently even after ``chown``.

**Relocate cgi-bin to** ``/var/www/cgi-bin``, which isn't affected by this restriction and is
already covered by the ``chown`` above:

.. code-block::
	text

	sudo a2disconf serve-cgi-bin
	sudo mkdir -p /var/www/cgi-bin
	sudo chown www-data:www-data /var/www/cgi-bin
	sudo tee /etc/apache2/conf-available/actpro-cgi-bin.conf > /dev/null <<'EOF'
	<IfModule mod_alias.c>
	    ScriptAlias /cgi-bin/ /var/www/cgi-bin/
	    <Directory "/var/www/cgi-bin">
	        AllowOverride None
	        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
	        Require all granted
	    </Directory>
	</IfModule>
	EOF
	sudo a2enconf actpro-cgi-bin
	sudo systemctl restart apache2

No further configuration is needed for outbound HTTP or MySQL/MariaDB connectivity from PHP.
Both work out of the box on Ubuntu once the database user exists.

***************************
Activation Pro Installation
***************************

1. In a browser navigate to: ``http://[IP address or domain name]/actpro_setup/setup.php``

   **Note:** Be sure to update the database user/password, and the Admin account
   name/password to the correct values for your environment.

   **Important:** the ``webserver cgi-bin directory`` field will autodetect
   ``/usr/lib/cgi-bin``. Override this to ``/var/www/cgi-bin`` (see previous section) or
   license generation will fail later even though setup appears to succeed.

2. Click "Setup Activation database".

   You can ignore this warning: ``WARNING: chmod 0444 of RLM_Activation_Pro.pdf failed.
   Please change permission by hand.``

3. Click "Next - Clean up Installation Files"
4. Click "Done - Start RLC"

No post-setup permissions step is needed here: once the license generator binary lands in
``/var/www/cgi-bin`` with its executable bit set, Apache's ``mod_cgid`` will run it.

*****************************
Activation Pro Configuration
*****************************

1. Log into Activation Pro
2. Navigate to Admin > ActPro License
3. Choose and upload your Activation Pro license file
4. Navigate to Admin > Generator Settings
5. Choose and upload your generator settings file (.gen)