Installation
Manual installation (recommended for production)
Install system dependencies:
On Debian derivatives
$ sudo apt update
$ sudo apt install git virtualenv python3-dev build-essential mariadb-server gettext libzip-dev libssl-dev
On Ubuntu 18.04 LTS you need to install libmariadbclient-dev:
$ sudo apt install libmariadbclient-dev
On Ubuntu 20.04 LTS and later you need to install libmariadb-dev-compat:
$ sudo apt install libmariadb-dev-compat
On Centos/Fedora derivatives
$ sudo yum install MariaDB-server galera-4 MariaDB-client MariaDB-shared MariaDB-backup MariaDB-common git python3 python3-virtualenv make gcc gettext
On Arch Linux
$ sudo pacman -S mariadb mariadb-libs python make gcc gettext
Install pdm
Get the source, configure and initialize Pytition
Get the latest release git tag:
$ version=$(curl -s https://api.github.com/repos/pytition/pytition/releases/latest | grep "tag_name" | cut -d : -f2,3 | tr -d \" | tr -d ,)
Create a directory to host your Pytition instance and it’s static files:
$ mkdir -p www/static www/mediaroot
Clone Pytition git repository and checkout latest release:
$ cd www
$ git clone https://github.com/pytition/pytition
$ cd pytition
$ git checkout $version
Install Pytition’s dependencies and enter the virtual environment:
$ pdm self update # update pdm to latest version
$ pdm sync --clean
$ eval $(pdm venv activate)
Create a MySQL database and user for Pytition:
$ password="ENTER_A_SECURE_PASSWORD_YOU_WILL_REMEMBER_HERE"
$ sudo mysql -h localhost -u root -Bse "CREATE USER pytition@localhost IDENTIFIED BY '${password}'; CREATE DATABASE pytition; GRANT USAGE ON *.* TO 'pytition'@localhost; GRANT ALL privileges ON pytition.* TO pytition@localhost; FLUSH PRIVILEGES;"
Write your SQL credential file in my.cnf outside of www:
[client]
database = pytition
user = pytition
password = YOUR_PASSWORD_HERE
default-character-set = utf8
If your SQL server is MariaDB <= 10.2.1, you need to setup your SQL server to use table format compatible with larger-than-767-bytes columns. From 10.2.2 onward, row format is already DYNAMIC by default. So, if you have an old MariaDB, add the following lines after [server] in /etc/mysql/mariadb.conf.d/50-server.cnf (This path is for Ubuntu 18.04):
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=true
innodb_default_row_format=DYNAMIC
Create your Pytition instance config file by copying the example one:
$ cd www/pytition
$ cp pytition/pytition/settings/config_example.py pytition/pytition/settings/config.py
Now you can edit your config file in pytition/pytition/settings/config.py according to Configuration.
You must at least configure the settings described in the Mandatory settings section of the Configuration page.
Those are:
|
|
Note
Do not forget to put a correct path to your my.cnf MySQL credential file in your config DATABASES setting.
Initialize Pytition project database. Pay attention to be in your virtualenv to enter the following commands:
$ cd www/pytition/pytition
$ export DJANGO_SETTINGS_MODULE="pytition.settings.config"
$ python3 manage.py migrate
$ python3 manage.py collectstatic
$ python3 manage.py compilemessages
$ python3 manage.py createsuperuser
Note
You will be asked to enter a username, email and password for the administrator’s account.
Before trying to configure a web server you can try to see if your configuration is OK by running:
$ DEBUG=1 DJANGO_SETTINGS_MODULE=pytition.settings.config python3 ./manage.py runserver 0.0.0.0:8000
You can then point your browser to http://yourdomain.tld:8000 and check that you can see Pytition’s home page and log-in with your newly created admin account.
Warning
If you’ve set USE_MAIL_QUEUE
to True
and MAIL_EXTERNAL_CRON_SET
to False
, running Pytition via manage.py runserver
might not work well since you need to be run via uwsgi. Especially emails might not be sent.
Note
If you switch USE_MAIL_QUEUE
from False
to True
at some point, you might have to re-run python3 manage.py migrate
to create the database structures needed for the mail queues.
Configure your web server
Nginx + uwsgi (recommended)
First install Nginx web server:
$ sudo apt install nginx
Here is an example of Nginx configuration that you can put in /etc/nginx/sites-available/pytition:
server {
server_name pytition.mydomain.tld;
keepalive_timeout 70;
location / {
include uwsgi_params;
uwsgi_pass unix:/var/run/uwsgi/app/pytition/socket;
}
location /static {
alias /home/pytition/www/static;
}
location /mediaroot {
alias /home/pytition/www/mediaroot;
}
listen 443 ssl; # managed by Certbot
ssl_certificate /etc/letsencrypt/live/pytition.mydomain.tld/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/pytition.mydomain.tld/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}
server {
server_name pytition.mydomain.tld;
listen 80;
return 301 https://pytition.mydomain.tld$request_uri;
}
The previous example automatically redirects HTTP/80 to HTTPS/443 and uses Let’s Encrypt generated certificate.
Enable your new Nginx config:
$ sudo ln -s /etc/nginx/sites-available/pytition /etc/nginx/sites-enabled/pytition
$ sudo systemctl reload nginx
Install uwsgi dependency:
sudo apt install uwsgi uwsgi-plugin-python3 python3-uwsgidecorators
Put the UNIX user of your install in www-data group (for Debian like systems) if your user wasn’t www-data already. For instance in our case we use the pytition unix username:
sudo usermod -a -G pytition www-data
Give both uwsgi and nginx access to your mediaroot directory:
sudo chown -R pytition:www-data /home/pytition/www/mediaroot
Now let’s create our uwsgi configuration in /etc/uwsgi/apps-available/pytition.ini:
[uwsgi]
chdir = /home/pytition/www/pytition/pytition
module = pytition.wsgi
home = /home/pytition/www/pytition/.venv
master = true
processes = 10
vacuum = true
socket = /run/uwsgi/app/pytition/socket
uid = ENTER_HERE_PYTITION_UNIX_USER
gid = www-data
chmod-socket = 664
plugins = python3
env = DJANGO_SETTINGS_MODULE=pytition.settings.config
Note
The uwsgi configuration (pytition.ini) file’s home value must be set to your pdm virtual env path. You can have pdm display the venv path using this command while being in the pytition source code top level directory: pdm venv list.
Create a symlink to enable or uwsgi configuration:
sudo ln -s /etc/uwsgi/apps-available/pytition.ini /etc/uwsgi/apps-enabled/pytition.ini
Start uwsgi and nginx servers:
$ sudo systemctl restart uwsgi
$ sudo systemctl restart nginx
Your Pytition home page should be available over there: http://mydomain.tld
Now it’s time to Configure your Pytition instance the way you want!
Installation via Docker (recommended for development)
Warning
Please, do NOT use this in production. You would have tons of security and performance issues. You could lose your SECRET_KEY, you would run with Django’s DEBUG setting enabled, you would be serving static files via Django basic webserver. You would be running with no HTTPS possibility at all. etc etc. Please : don’t.
Clone latest development version of Pytition:
$ git clone https://github.com/pytition/pytition
Install docker and docker-compose:
$ sudo apt install docker.io docker-compose
Put your user in the docker group (needed for Ubuntu 18.04) and start docker daemon:
$ sudo usermod -a -G docker $USER
$ # log-in again as your user for group change to take effect
$ # or just type the following line
$ su -l $USER
$ sudo systemctl enable docker
$ sudo systemctl start docker
For the first run you need to create the database container and let it be ready:
$ docker-compose up --build db
Wait until it prints something like:
LOG: database system is ready to accept connections
Then hit ^C (ctrl+C) to shutdown the database container.
From now on, you can just type this to run Pytition in a container:
$ docker-compose up --build
Last command before being able to click on the “http://0.0.0.0:8000/” link that the “web” container prints to out on the console. You need to run migrations, install static files, compile language files, create an admin account and lastly populate your database with some dummy data. You can do all of this with the dev/initialize.sh script:
$ docker-compose exec web ./dev/initialize.sh
Aaaand that’s it! You can now just click on the links:
http://0.0.0.0:8000/ for the Pytition interface
http://0.0.0.0:8080/ for the mail server web interface
Next time, just run $ docker-compose up --build