Skip to content
Snippets Groups Projects
Verified Commit 006ace66 authored by Nik | Klampfradler's avatar Nik | Klampfradler
Browse files

Rewrite installation instructions

parent b34329fd
No related branches found
No related tags found
1 merge request!333Documentation for beta release (Documentation for first release part 1)
Hide whitespace changes
Inline Side-by-side
docs/admin/01_install.rst
+ 200
− 101
View file @ 006ace66
Install AlekSIS
===============
From source
-----------
From PyPI
---------
In this section we will install AlekSIS with `uWSGI` and `nGINX` on debian
In this section we will install AlekSIS with `uWSGI` and `nGINX` on Debian
bullseye.
AlekSIS will store its data in two directories; media and static. The
`media` directory contains everything uploaded by users, e.g. photos of
persons. The `static` folder contains static files from AlekSIS such as
scripts an stylesheets.
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.
1. Prerequisites::
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.
.. code-block:: shell
apt install uwsgi \
uwsgi-plugin-python3 \
nginx-full \
python3 \
python3-dev \
libldap2-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.
.. code-block:: shell
sudo -u postgres createuser -l aleksis -
sudo -u postgres createdb -O aleksis aleksis
When asked, use the password generated above.
Create the directories for storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
1. Prepare system
mkdir -p /etc/aleksis \
/usr/share/aleksis/{static,node_modules} \
/var/lib/aleksis/media \
/var/backups/aleksis
* Install system dependencies::
Create AlekSIS configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ apt install uwsgi uwsgi-plugin-python3 nginx-full python3.9 python3.9-dev libldap2-dev libsasl2-dev yarnpkg python3-virtualenv chromium redis-server
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.
* Create and activate virtual environment::
.. code-block:: toml
$ mkdir -p /srv/www/aleksis
$ mkdir -p /srv/www/aleksis/data/{static,media}
$ cd /srv/www/aleksis
$ python3 -m venv
$ source /srv/www/aleksis/venv/bin/activate
$ pip install poetry
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"
* Install and configure PostgreSQL::
[http]
allowed_hosts = ["aleksis.example.com"]
$ apt install postgresql-13
$ sudo -u postgres createuser -l aleksis -
$ sudo -u postgres createdb -O aleksis aleksis
[database]
host = "localhost"
name = "aleksis"
username = "aleksis"
password = "password_generated_above"
* Configure uWSGI::
[backup]
location = "/var/backups/aleksis"
$ editor /etc/uwsgi/apps-available/aleksis.ini
[auth.superuser]
username = "admin"
password = "admin"
email = "root@localhost"
[uwsgi]
vhost = true
plugins = python3
master = true
enable-threads = true
processes = 20
wsgi-file = /usr/src/AlekSIS/aleksis/core/wsgi.py
virtualenv = /srv/www/aleksis/venv
chdir = /usr/src/AlekSIS
lazy = true
lazy-apps = true
attach-daemon = celery -A aleksis.core worker --concurrency=4
attach-daemon = celery -A aleksis.core beat
Install AlekSIS itself
~~~~~~~~~~~~~~~~~~~~~~
$ ln -s /etc/uwsgi/apps-available/aleksis.ini /etc/uwsgi/apps-enabled/aleksis.ini
$ service uwsgi restart
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.
* Get SSL ssl certificate
.. code-block:: shell
* https://certbot.eff.org/instructions
pip3 install aleksis
aleksis-admin yarn install
aleksis-admin collectstatic
aleksis-admin migrate
aleksis-admin createinitialrevisions
* Configure nGINX::
$ editor /etc/nginx/sites-available/aleksis.example.com
server {
listen 80;
listen [::]:80;
Configure uWSGI
~~~~~~~~~~~~~~~
server_name aleksis.example.com;
uWSGI is an application server that will manage the server processes and requests.
It will also run the Celery broker and scheduler for you.
return 301 https://$server_name$request_uri;
}
Configure a uWSGI app by opening `/etc/uwsgi/apps-available/aleksis.ini` in an
editor and inserting:
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
.. code-block:: toml
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;
[uwsgi]
vhost = true
plugins = python3
master = true
enable-threads = true
processes = 20
wsgi-file = /usr/local/lib/python3/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
server_name aleksis.example.com;
Afterwards, enable the app using:
access_log /var/log/nginx/access.log;
.. code-block:: shell
location /static {
alias /srv/www/aleksis/data/static;
}
ln -s /etc/uwsgi/apps-available/aleksis.ini /etc/uwsgi/apps-enabled/aleksis.ini
service uwsgi restart
location / {
uwsgi_pass aleksis;
include uwsgi_params;
Configure the nginx webserver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
proxy_redirect off;
proxy_pass_header Authorization;
}
}
First, you should get a TLS certificate, e.g. by using `Let's Encrypt`_.
$ ln -s /etc/nginx/sites-available/aleksis.example.com /etc/nginx/sites-enabled/aleksis.example.com
$ service nginx restart
Then, create a virtual host in nginx, by editing `/etc/nginx/sites-available/aleksis.example.com`.
* Configure AlekSIS::
$ mkdir /etc/aleksis
$ editor /etc/aleksis/aleksis.toml
static = { root = "/srv/www/aleksis/data/static", url = "/static/" }
media = { root = "/srv/www/aleksis/data/media", url = "/media/" }
secret_key = "SomeRandomValue"
.. code-block:: nginx
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:
.. code-block:: shell
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
-----------
[http]
allowed_hosts = ["aleksis.example.com"]
AlekSIS can also be installed using Docker, either only AlekSIS itself, or the
full stack, including Redis, using docker-compose
[database]
host = "localhost"
name = "aleksis"
username = "aleksis"
password = "SomeSecretPassword!1"
Full stack using docker-compose
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Clone git repository and checkout version::
First, install Docker and docker-compose on your system. Also install git
to get the docker-compose file and image definition.
$ cd /usr/src
$ git clone https://edugit.org/AlekSIS/official/AlekSIS-Core
$ cd AlekSIS-Core
$ git checkout 2.0b
.. code-block:: shell
1. Install dependencies and setup initially::
apt install docker.io docker-compose git
$ poetry install
$ aleksis-admin yarn install
$ aleksis-admin collectstatic
$ aleksis-admin migrate
Now, clone the distribution repository, which contains the docker-compose
file.
1. Restart uWSGI::
.. code-block:: shell
$ service uwsgi restart
git clone https://edugit.org/AlekSIS/official/AlekSIS
Docker with `docker-compose`
---------------------------
You should review the file `docker-compose.yaml` for any environment variables
you want to change.
1. Prerequisites::
Finally, bring the stack up using:
* System with docker and docker-compose installed
.. code-block:: shell
1. Run docker image::
docker-compose up -d
$ git clone https://edugit.org/AlekSIS/Official/AlekSIS
$ docker-compose up -d
AlekSIS will be reachable on port 8000. You are responsible for adding a
reverse proxy like nginx providing TLS, etc.
.. _Dynaconf: https://dynaconf.readthedocs.io/en/latest/
.. _Let's Encrypt: https://certbot.eff.org/instructions
.. _PyPI: https://pypi.org
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment