AlekSIS
AlekSIS

Install AlekSIS

From PyPI

In this section we will install AlekSIS with uWSGI and nGINX on Debian bullseye.

Filesystem locations

AlekSIS will need and use the following paths:

  • /etc/aleksis for configuration files

  • /var/lib/aleksis/media for file storage (Django media)

  • /var/backups/aleksis for backups of database and media files

  • /usr/local/share/aleksis/static for static files

  • /usr/local/share/aleksis/node_modules for frontend dependencies

You can change any of the paths as you like.

Prerequisites

For an installation on a dedicated server, the following prerequisites are needed:

  • Debian 11

  • PostgreSQL

  • Redis

  • uWSGI

  • nginx

  • Python 3.9

  • Some system dependencies to build Python modules and manage frontend files

  • The aforementioned paths

Install system packages

Install some packages from the Debian package system.

apt install uwsgi \
            uwsgi-plugin-python3 \
            nginx-full \
            python3 \
            python3-dev \
            libldap2-dev \
            libpq-dev \
            libsasl2-dev \
            yarnpkg \
            python3-virtualenv \
            chromium \
            redis-server \
            postgresql

Create PostgreSQL user and database

Generate a secure password for the database, then create the user and database.

sudo -u postgres createuser -D -P -R -S aleksis
sudo -u postgres createdb -E UTF-8 -O aleksis -T template0 -l C.UTF-8 aleksis

When asked, use the password generated above.

Create the directories for storage

mkdir -p /etc/aleksis \
         /usr/share/aleksis/{static,node_modules} \
         /var/lib/aleksis/media \
         /var/backups/aleksis
chown -R www-data:www-data /var/lib/aleksis

Create AlekSIS configuration file

AlekSIS is configured in files in /etc/aleksis. Create a basic configuration file for the environment defined above by opening /etc/aleksis/aleksis.toml with your favourite text editor and adding the following configuration.

static = { root = "/usr/local/share/aleksis/static", url = "/static/" }
media = { root = "/var/lib/aleksis/media", url = "/media/" }
node_modules = { root = "/usr/local/share/aleksis/node_modules" }
secret_key = "SomeRandomValue"

[http]
allowed_hosts = ["aleksis.example.com"]

[database]
host = "localhost"
name = "aleksis"
username = "aleksis"
password = "password_generated_above"

[backup]
location = "/var/backups/aleksis"

[auth.superuser]
username = "admin"
password = "admin"
email = "root@localhost"

Install AlekSIS itself

To install AlekSIS now, and run all post-install tasks, run the following commands. They will pull the AlekSIS standard distribution from PyPI and install it to the system-wide dist-packages of Python. Afterwards, it will download frontend dependencies from yarnpkg, collect static files, and migrate the database to the final schema.

pip3 install aleksis
aleksis-admin yarn install
aleksis-admin collectstatic
aleksis-admin migrate
aleksis-admin createinitialrevisions

Configure uWSGI

uWSGI is an application server that will manage the server processes and requests. It will also run the Celery broker and scheduler for you.

Configure a uWSGI app by opening /etc/uwsgi/apps-available/aleksis.ini in an editor and inserting:

[uwsgi]
vhost = true
plugins = python3
master = true
enable-threads = true
processes = 20
wsgi-file = /usr/local/lib/python3.9/dist-packages/aleksis/core/wsgi.py
chdir = /var/lib/aleksis
lazy = true
lazy-apps = true
attach-daemon = celery -A aleksis.core worker --concurrency=4
attach-daemon = celery -A aleksis.core beat

Afterwards, enable the app using:

ln -s /etc/uwsgi/apps-available/aleksis.ini /etc/uwsgi/apps-enabled/aleksis.ini
service uwsgi restart

Configure the nginx webserver

First, you should get a TLS certificate, e.g. by using Let’s Encrypt.

Then, create a virtual host in nginx, by editing /etc/nginx/sites-available/aleksis.example.com.

upstream aleksis {
  server unix:///run/uwsgi/app/aleksis/socket;
}

server {
  listen 80;
  listen [::]:80;

  server_name aleksis.example.com;

  return 301 https://$server_name$request_uri;
}

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;

  ssl_certificate /etc/letsencrypt/certs/aleksis.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/certs/aleksis.example.com/privkey.pem;
  ssl_trusted_certificate /etc/letsencrypt/certs/aleksis.example.com/chain.pem;

  server_name aleksis.example.com;

  access_log /var/log/nginx/access.log;

  location /static {
    alias /usr/local/share/aleksis/static;
  }

  location / {
    uwsgi_pass aleksis;
    include uwsgi_params;
    proxy_redirect off;
    proxy_pass_header Authorization;
  }
}

Enable the virtual host:

ln -s /etc/nginx/sites-available/aleksis.example.com /etc/nginx/sites-enabled/aleksis.example.com
service nginx restart

Finalisation

Your AlekSIS installation should now be reachable and you can login with the administration account configured above.

With Docker

AlekSIS can also be installed using Docker, either only AlekSIS itself, or the full stack, including Redis, using docker-compose

Full stack using docker-compose

First, install Docker and docker-compose on your system. Also install git to get the docker-compose file and image definition.

apt install docker.io docker-compose git

Now, clone the distribution repository, which contains the docker-compose file.

git clone https://edugit.org/AlekSIS/official/AlekSIS

You should review the file docker-compose.yaml for any environment variables you want to change.

Finally, bring the stack up using:

docker-compose up -d

AlekSIS will be reachable on port 80 if you forgot to configure the environment. You are responsible for adding a reverse proxy like nginx providing TLS, etc.