Installation for System Administrators

This guide provides a concise overview of how to do a manual server installation of ErbslandFORMER for system administrators. It focuses on the key elements without detailing the execution of each task. For a more detailed guide, refer to the Installation, Step by Step.

Requirements

  • Python 3.12+

    The application requires Python 3.12 or newer and the packages listed in requirements.txt or requirements.in.

  • Apache or nginx: Web Server to Run a WSGI Application

    A web server or proxy, like Apache or nginx, is required to run the frontend application.

  • Redis: Message Broker for Celery and the Frontend

    Redis is necessary as a message broker for Celery to handle background tasks.

  • MariaDB/MySQL/PostgreSQL Database

    A database such as MySQL, MariaDB, or PostgreSQL is needed to store all application data.

  • MySQL Database Client for Python

    A MySQL database client for Python, such as mysqlclient, is required. This client is not part of the requirements.txt and should be installed from the distribution.

Application User

Create a system user for the application, e.g., erbsland_former, with a group and a shell. A home directory is not required.

Application Directory Structure

Preferably in /var/www/erbsland-former, create the following directory structure:

├───◆ /var/www/erbsland-former
    ├───◆ app            # Application files / Configuration (via git clone)
    ├───◆ static         # Static files served by the web server.
    ├───◆ venv           # Python virtual environment.
    ├───◆ working_dir    # Directory for temporary files.

drwxr-xr-x | erbsland_former erbsland_former | app/
drwxr-xr-x | erbsland_former erbsland_former | static/
drwxr-xr-x | erbsland_former erbsland_former | venv/
drwx------ | erbsland_former erbsland_former | working_dir/

Create the directories and set the appropriate permissions:

test@erbsland-former:~$ sudo mkdir /var/www/erbsland-former
test@erbsland-former:~$ sudo chown erbsland_former:erbsland_former /var/www/erbsland-former
test@erbsland-former:~$ sudo chmod 755 /var/www/erbsland-former
test@erbsland-former:~$ sudo mkdir /var/www/erbsland-former/static
test@erbsland-former:~$ sudo chown erbsland_former:erbsland_former /var/www/erbsland-former/static
test@erbsland-former:~$ sudo chmod 755 /var/www/erbsland-former/static
test@erbsland-former:~$ sudo mkdir /var/www/erbsland-former/working_dir
test@erbsland-former:~$ sudo chown erbsland_former:erbsland_former /var/www/erbsland-former/working_dir
test@erbsland-former:~$ sudo chmod 700 /var/www/erbsland-former/working_dir

Clone the application repository and set up the virtual environment:

test@erbsland-former:~$ sudo su erbsland_former
erbsland_former@erbsland-former:/home/test$ cd /var/www/erbsland-former
erbsland_former@erbsland-former:/var/www/erbsland-former$ git clone https://github.com/erbsland-dev/erbsland-former.git app
erbsland_former@erbsland-former:/var/www/erbsland-former$ python3 -m venv --system-site-packages venv
erbsland_former@erbsland-former:/var/www/erbsland-former$ source venv/bin/activate
(venv) erbsland_former@erbsland-former:/var/www/erbsland-former$ pip install -r app/requirements.txt

Setup Redis and MariaDB

Activate Redis:

test@erbsland-former:~$ sudo systemctl enable redis-server
test@erbsland-former:~$ sudo systemctl start redis-server
test@erbsland-former:~$

Set up MySQL:

test@erbsland-former:~$ sudo systemctl enable mariadb
test@erbsland-former:~$ sudo systemctl start mariadb
test@erbsland-former:~$ sudo mariadb
MariaDB [(none)]> CREATE DATABASE erbsland_former CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
MariaDB [(none)]> CREATE USER erbsland_former@localhost IDENTIFIED BY '[random password]';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON erbsland_former.* TO erbsland_former@localhost;
MariaDB [(none)]> FLUSH PRIVILEGES;

System Setup

Copy the file settings.py in the application directory ErbslandFormer and rename it to my_settings.py. Update wsgi.py with the name of your settings file.

Update your my_settings.py file:

  • Set a random SECRET_KEY.

  • Set a random BACKEND_ENCRYPTION_KEY.

  • Set the database host, name, user, and password.

  • Set the STATIC_ROOT to the static directory.

  • Set the BACKEND_WORKING_DIR to the working_dir directory.

  • Configure all EMAIL_... settings to enable email functionality.

  • Remove the last section enclosed in [remove].

Run a check, collect all static files, and initialize the database. Ensure you set the environment variable DJANGO_SETTINGS_MODULE to your settings file.

$ export DJANGO_SETTINGS_MODULE=ErbslandFormer.my_settings
$ python app/manage.py check
System check identified no issues (0 silenced).
$ python app/manage.py collectstatic
189 static files copied to '/var/www/erbsland-former/static'.
$ python app/manage.py migrate

Create a superuser and regular users for the system:

$ python app/manage.py createsuperuser --username ef_admin --email ef_admin@example.com
$ python app/manage.py add_user user1 user1@example.com
$ python app/manage.py add_user user2 user2@example.com
$ python app/manage.py add_user user3 user3@example.com

Setup the Backend Process

Set up Celery as a background process. Use the erbsland-former.service template for this setup.

test@erbsland-former:~$ sudo cp /var/www/erbsland-former/app/ErbslandFormer/erbsland-former.service /etc/systemd/system/
test@erbsland-former:~$ sudo chown root:root /etc/systemd/system/erbsland-former.service
test@erbsland-former:~$ sudo chmod 644 /etc/systemd/system/erbsland-former.service
test@erbsland-former:~$ sudo nano /etc/systemd/system/erbsland-former.service
test@erbsland-former:~$ sudo systemctl enable erbsland-former
test@erbsland-former:~$ sudo systemctl start erbsland-former

Ensure the service is started successfully by checking the logs with journalctl -r.

Example service file:

 1[Unit]
 2Description=ErbslandFORMER Celery Service
 3After=network.target
 4
 5[Service]
 6Type=simple
 7User=erbsland_former
 8Group=erbsland_former
 9WorkingDirectory=/var/www/erbsland-former/app/
10Environment="DJANGO_SETTINGS_MODULE=ErbslandFormer.my_settings"
11ExecStart=/usr/bin/env bash -c 'source /var/www/erbsland-former/venv/bin/activate && exec python3 -m celery -A tasks.celery_app worker --loglevel=info'
12ExecStop=/usr/bin/env bash -c 'source /var/www/erbsland-former/venv/bin/activate && exec python3 -m celery -A tasks.celery_app control shutdown'
13Restart=always
14
15[Install]
16WantedBy=multi-user.target

Configure Apache

You will find an example Apache configuration file named apache.conf in the ErbslandFormer directory. Copy this file to the Apache configuration directory and enable the site. Adjust all paths and names according to your setup.

test@erbsland-former:~$ sudo cp /var/www/erbsland-former/app/ErbslandFormer/apache.conf /etc/apache2/sites-available/former.erbsland.com.conf
test@erbsland-former:~$ sudo a2ensite former.erbsland.com.conf

Below is an example of the Apache configuration. Ensure you modify the paths and user names as needed for your setup.

<VirtualHost *:80>
    ServerName former.erbsland.com
    DocumentRoot /var/www/html
    ErrorLog ${APACHE_LOG_DIR}/former.erbsland.com_error.log
    CustomLog ${APACHE_LOG_DIR}/former.erbsland.com_access.log combined
    RewriteEngine On
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
<VirtualHost *:443>
    ServerName former.erbsland.com
    DocumentRoot /var/www/html
    Alias /static/ /var/www/erbsland-former/static/

    # WSGI
    WSGIDaemonProcess former.erbsland.com \
        home=/var/www/erbsland-former/ \
        python-home=/var/www/erbsland-former/venv \
        python-path=/var/www/erbsland-former/app:/var/www/erbsland-former/venv/lib/python3.12/site-packages \
        user=erbsland_former
    WSGIProcessGroup former.erbsland.com
    WSGIScriptAlias / /var/www/erbsland-former/app/ErbslandFormer/wsgi.py
    <Directory /var/www/erbsland-former/app>
        <Files wsgi.py>
            Require all granted
        </Files>
    </Directory>
    <Directory /var/www/erbsland-former/static>
        Require all granted
    </Directory>

    # SSL Configuration
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/former.erbsland.com.pem
    SSLCertificateKeyFile /etc/ssl/private/former.erbsland.com.pem
    SSLCertificateChainFile /etc/ssl/certs/former.erbsland.com_chain.pem

    # Security Enhancements
    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
    SSLCipherSuite HIGH:!aNULL:!MD5:!3DES:!CAMELLIA:!DES:!eNULL
    SSLHonorCipherOrder on
    SSLCompression off
    SSLSessionTickets off

    # HSTS (HTTP Strict Transport Security)
    Header always set Strict-Transport-Security "max-age=63072000; includeSubdomains; preload"

    # OCSP Stapling
    SSLUseStapling on
    SSLStaplingResponderTimeout 5
    SSLStaplingReturnResponderErrors off
    SSLStaplingCache shmcb:/var/run/ocsp(128000)

    # Logging
    ErrorLog ${APACHE_LOG_DIR}/former.erbsland.com_error.log
    CustomLog ${APACHE_LOG_DIR}/former.erbsland.com_access.log combined
</VirtualHost>

Ensure you adapt this example configuration to comply with the SSL standards of your company. Restart the web server to activate the new configuration.

test@erbsland-former:~$ sudo systemctl restart apache2

Done

This is the basic setup for a single host installation of the application. The application can easily scale across multiple frontend and backend instances, using Redis and Celery to distribute the workload.