Documentation around installation + running is not working well for Debian 12 setup

[realkinetix]

Howdy,

I'm following the documentation in HTML format at https://rseichter.github.io/automx2/

I've followed the steps in getting automx2 installed - last step of "pip install automx2" is successful.

I've created a configuration file at ~/.automx2.conf as per the next section.

The next section, 7.3, has one redirecting in the documentation to find out how to run automx2, so off to section 9 I go. I can see that both the OpenRC script and the Systemd scripts would fail as written, since there is no system-wide flask, it was just installed in the user's account as a dependency for automx2. So, other installation work would have to be done to make either init script type function as written.

However, to try and test running it manually as the user, it is suggested to:

.venv/scripts/flask.sh run --host=127.0.0.1 --port=4243

First, there is no .venv/scripts/flask.sh.

There is, however, .venv/bin/flask. So let's try that:

$ which flask
/home/automx/.venv/bin/flask

$flask run --host=127.0.0.1 --port=4243
sage: flask run [OPTIONS]
Try 'flask run --help' for help.

Error: Could not locate a Flask application. Use the 'flask --app' option, 'FLASK_APP' environment variable, or a 'wsgi.py' or 'app.py' file in the current directory.

So.... what are we supposed to be doing here to get it to run?

[realkinetix]

pip install doesn't seem to install flask.sh or anything else from the source contrib folder.

[rseichter]

The parts of the documentation you mentioned precede Debian 12 by years, and I have not tested automx2 on Debian 12 myself. Before I set up the necessary testing environment, can you please specify the Debian variant you are using (e.g. server, minimal server, desktop) and how you installed Python 3 (which version?). I assume you have used automx2 version 2024.01?

[rseichter]

From what I could gather so far, I suspect that the observed behaviour is an unintended side effect of my introducing support for PEP 517 style build environments. That was done to make it easier to package automx2 for modern Linux distributions, but I guess no good deed goes unpunished. 😉 For the time being, the recommended workaround is manually downloading the flask.sh utility script:

cd /path/to/your/.venv/bin
wget https://raw.githubusercontent.com/rseichter/automx2/master/contrib/flask.sh
chmod 0755 flask.sh

[realkinetix]

I am not sure which debian install method was done initially... the server's been around for more than a few years and been through at least 3 major debian stable upgrades. It was probably minimal when installed, but it was created as a VPS and I can't be sure what they built their Debian setup from.

Python 3.11 is what's on the system these days.

I did wind up cloning the git repository and saw things in contrib (which has several of the missing pieces referenced from the documentation), so I did get flask.sh in place, setup a systemd script and it's up and running.

I am a little concerned that the OpenRC and SystemD scripts presented in the documentation would fail as presented as well, as they don't follow the rest of the install documentation.

[rseichter]

Both the systemd and OpenRC services were successfully tested, way back in the early days of automx2. OpenRC indeed requires a system-wide installation of flask, as is available on Gentoo Linux, but that is all being handled by the Gentoo package I wrote.

As noted in the docs, the service files are merely meant as examples. If you want production ready, try the AUR package or Gentoo ebuild. That said, The absence of flask.sh after a pip based installation is a mistake.

[rseichter]

I have updated the documentation, describing how flask.sh can be manually downloaded. It should suffice as a workaround, until I can provide a fix via PyPI.

[rseichter]

A fix for PyPI may be more involved than I thought, so I decided to create an install.sh script. See the documentation for details. I would appreciate you giving it a try.

[rseichter]

I'll call this one done, because the installation script I added seems like the most convenient way for end users to me. Feel free to comment if you have additional thoughts or experience any issues with the new script.