Skip to content

Install¤

The Virtual Secretary has 4 parts:

  1. the Python 3.11 interpreter (aka the runtime),
  2. the Python packages upon which it depends (aka the libraries),
  3. the Virtual Secretary application source code (aka the application), located in the src/ folder of the source code,
  4. the user filters (aka the implementation), typically installed in a config/ folder.

The Python interpreter is pretty standard in Linux distributions and easy to install on Windows and Mac. However, Linux distributions may have older versions than 3.11. If you plan on using the Virtual Secretary on a shared hosting server, you will not have access to a shell giving you rights to install or update Python. For those cases where you can’t install or update the Python interpreter to version 3.11, download the Python 3.11 AppImage. See below how to deploy Python 3.11 to a server where you don’t have sudo rights.

Getting the source code¤

The easiest way is to get and update the source code through Git (installation instructions).

Once Git is installed, in a terminal, run:

git clone https://github.com/aurelienpierreeng/VirtualSecretary.git
cd VirtualSecretary

To update in the future, run:

cd VirtualSecretary
git pull

Python interpreter¤

If you have access to a package manager and you are able to simply install Python 3.11, do it. Otherwise, here is how to deploy the AppImage on a server:

  1. We assume here you are already in VirtualSecretary folder, after the cd VirtualSecretary command at the previous step.

  2. Download the AppImage package: 

    wget https://github.com/niess/python-appimage/releases/download/python3.11/python3.11.4-cp311-cp311-manylinux2014_x86_64.AppImage

  3. Rename it python3.11.AppImage for convenience: 

    mv python3.11.4-cp311-cp311-manylinux2014_x86_64.AppImage python3.11.AppImage

  4. Give it execution permissions: 

    chmod +x python3.11.AppImage

  5. Run the test command: 

    ./python3.11.AppImage --version
    If it returns: 
    dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.
    then you need to extract the AppImage because the system can’t do it. Luckily, the AppImage package is self-extractable, so just run: 
    ./python3.11.AppImage --appimage-extract && mv squashfs-root python3.11

From there, to execute a Python script (.py), you have to use one of the following methods:

  1. python3.11 script.py if you have multiple versions of Python installed,
  2. python script.py if you have only Python 3.11 installed,
  3. ./python3.11.AppImage script.py from within the VirtualSecretary folder if you can use the non-extracted AppImage
  4. python3.11/AppRun script.py from within the VirtualSecretary folder if you had to extract the AppImage

In the rest of this document, we will write PYTHON as a generic way of calling the interpreter that will need to be replaced by one of the above commands depending on your case.

Installing the dependencies¤

From the VirtualSecretary/ folder, run: 

PYTHON -m pip install -r recipe/requirements.txt

Notes on servers¤

Note

This installation procedure was tested on Ubuntu Server 20.04 using an Amazon Elastic Cloud 2 instance, on Fedora Desktop 37 and 38, and on a CPanel-based shared hosting (Debian).

If you use a private or shared hosting, you have access to a server where you may run applications, host websites and mailboxes. It is very desirable to install the Virtual Secretary on the same server hosting your mailbox, as it will be able to filter those email in-place. In that case, for security purposes, it is better to put the application code outside of the HTTP server directories (var_html, or /var-www, or any directory accessible through a web browser).

CPanel-based shared hostings have limited resources, but my tests show they can still be used for a single user with a couple email addresses. Nowadays, they provide a web terminal allowing to launch command lines, even though they still don’t come with sudo rights to install software.

If your hosting does not have a web terminal interface, nor SSH access, and is basically just a piece of harddrive connected to the internet with some way to define Cron jobs, you will have to prepare the VirtualSecretary folder with the source code and the extracted Python AppImage locally, on your computer, and then to dump it all on the server through FTP.