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

[[run]]
== Running automx2

Running automx2 requires to start automx2 as service and serve its output via a web server to the public.
You should not run automx2 with superuser privileges.
Use a dedicated user instead.

The following examples assume you have created a user and group `automx2`
and have granted appropriate rights to this user:

- Read permissions for the `automx2.conf` configuration file.
- Read and access permissions for the virtual Python environment.
- Read and access permissions for the SQLite database.

=== As a OpenRC service

The following is an example for a OpenRC run script `/etc/init.d/automx2` which I use for Gentoo Linux:

[source,bash]
----
include::../contrib/OpenRC/init_d[]
----

If you wish to override any of the settings, copy the following to `/etc/conf.d/automx2` and uncomment/change variables according to your needs.
This is purely optional.

[source,bash]
----
include::../contrib/OpenRC/conf_d[]
----

=== As a systemd service

If your system uses _systemd_ you may want to deploy the following xref:../contrib/automx2.service[automx2.service] unit file from the contrib section and place it in `/etc/systemd/system/automx2.service`. Starting with version 2025.1, automx2 will auto-detect the presence of the `NOTIFY_SOCKET` environment variable and signal service readiness to systemd.

[source,ini]
----
include::../contrib/automx2.service[]
----

Once you have installed the service you need to tell systemd to reload its list of available services:

[source,bash]
[.small]
----
sudo systemctl daemon-reload
----

It should now be able to tell you about a service named automx2:

[source,bash]
[.small]
----
sudo systemctl status automx2
● automx2.service - MUA configuration service
     Loaded: loaded (/etc/systemd/system/automx2.service; disabled; vendor preset: enabled)
     Active: inactive (dead)
----

Next enable and start automx2 using the following command:

[source,bash]
[.small]
----
sudo systemctl enable automx2 --now
Created symlink /etc/systemd/system/multi-user.target.wants/automx2.service → /etc/systemd/system/automx2.service.
----

You should see automx2 enabled and running:

[source,bash]
[.small]
----
sudo systemctl status automx2
● automx2.service - MUA configuration service
     Loaded: loaded (/etc/systemd/system/automx2.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-03-01 12:54:31 CET; 19s ago
   Main PID: 126966 (python)
      Tasks: 1 (limit: 4620)
     Memory: 46.1M
     CGroup: /system.slice/automx2.service
             └─126966 /srv/www/automx2/bin/flask run --host=127.0.0.1 --port=4243
[...]
Mar 01 12:54:32 mail python[126966]: Reading /etc/automx2.conf
Mar 01 12:54:32 mail python[126966]: Config.get: loglevel = WARNING
Mar 01 12:54:32 mail python[126966]:  * Running on http://127.0.0.1:4243/ (Press CTRL+C to quit)
----

You are now ready to start testing automx2, as described <<localtest,below>>.

=== Manually from a shell

While logged in as an unprivileged user, change into the installation directory and start the `.venv/bin/flask.sh` launch script:

[source,bash]
----
cd /srv/www/automx2
.venv/bin/flask.sh run --host=127.0.0.1 --port=4243
----

[NOTE]
.Handling terminal output
====
The launch script will deliberately keep automx2 running in the foreground, and log data will be displayed in the terminal.
If you press Ctrl-C or close the shell session, the application will terminate.
To run automx2 in the background, you can use a window manager like link:https://www.gnu.org/software/screen/[GNU
Screen] or link:https://en.wikipedia.org/wiki/Tmux[tmux].
====

Now that automx2 is up and running, you need to configure the web server proxy that will receive requests from the outside and forwards them to automx2.

[[localtest]]
== Testing automx2 locally

You can use _curl_ in a command shell to send a GET request to your local automx2-instance.
The following example assumes your service runs on localhost on port 4243. The exact output depends on your database content, but should look similar.

[source,bash]
----
curl 'http://127.0.0.1:4243/mail/config-v1.1.xml?emailaddress=user@example.com'
----

[source,xml]
[.small]
----
<clientConfig version="1.1">
    <emailProvider id="automx2-100">
        <identity/>
        <domain>example.com</domain>
        <displayName>Example Inc.</displayName>
        <displayShortName>Example</displayShortName>
        <incomingServer type="imap">
            <hostname>mail.example.com</hostname>
            <port>993</port>
            <socketType>SSL</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </incomingServer>
        <incomingServer type="pop3">
            <hostname>mail.example.com</hostname>
            <port>110</port>
            <socketType>STARTTLS</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </incomingServer>
        <outgoingServer type="smtp">
            <hostname>mail.example.com</hostname>
            <port>587</port>
            <socketType>STARTTLS</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </outgoingServer>
        <!-- ... -->
    </emailProvider>
</clientConfig>
----

Having verified that automx2 returns configuration data, you should make the service available using a web server as a proxy.
