// vim: ts=4 sw=4 et ft=asciidoc

[[install]]
== Installing automx2

automx2 requires Python version 3.7 or greater, ideally in the form of a virtual Python environment, to run.
Check the python3 version like this:

[source,bash]
----
$ python3 --version
Python 3.12.3
----

[IMPORTANT]
.Don't run as root
====
If you use a port number greater than 1024 (I suggest port 4243), the application does not require superuser privileges when running.
Doing so would pose a security risk and is therefore strongly discouraged.
I recommend creating a fresh user account called `automx2`.
====

=== Package based installation

There are packages available for link:https://aur.archlinux.org/packages/automx2[Arch Linux], link:https://packages.gentoo.org/packages/net-mail/automx2[Gentoo Linux] and link:https://search.nixos.org/packages?type=packages&query=automx[NixOS].
Note that these packages may not alway be up-to-date, because Linux distributions have their own release schedules.
Please make sure to check the version numbers if you decide to go this route.

=== Pip based installation

This is the method which should always provide you with the latest release.
The path `/srv/www/automx2` will be used as an example throughout this documentation.
The BASH shell commands below should work with any modern Linux distribution.

[source,bash]
----
# Best practice: Create a fresh user account.
sudo useradd --home-dir /srv/www/automx2 --create-home automx2

# Alternative: If the user account already exists.
# sudo bash -c 'mkdir -p /srv/www/automx2 && chown automx2 /srv/www/automx2'
----

Next, make sure to either login as the user created above, or change to this user via the 'su' command.
This is important to ensure the correct file permissions.
Now download the script that will install your automx2 service.
Installation requires BASH plus either curl or wget to download additional data.
The script will abort if neither of the latter two can be found.

[source,bash]
----
cd /srv/www/automx2
wget https://raw.githubusercontent.com/rseichter/automx2/master/contrib/install.sh
# Alternative: curl -O https://raw.githubusercontent.com/rseichter/automx2/master/contrib/install.sh
bash install.sh
----

Executing the setup script will create a Python virtual environment called `.venv` in the current directory.
You may pass a custom directory path as an argument to install.sh, if necessary.
To ensure a clean slate, installation will abort if the destination path already exists.

[source,bash]
----
# Example of how to pass a custom directory
bash install.sh /path/to/your/venv
----

The script will automatically download the automx2 Python module and place it inside the newly created virtual environment.
It will also create a launch script `.venv/bin/flask.sh`, which can run automx2 after you prepared the configuration.

=== Updating

If you use pre-built packages, please consult the documentation for your specific Linux distribution.
The following applies only to pip based installations:

Change to the directory where automx2 has been installed previously.
Activate the virtual environment as usual and use pip's `--upgrade` option:

[source,bash]
----
cd /srv/www/automx2
.venv/bin/pip install --upgrade automx2
----
