Server installation#

There are different ways to install DigiAgriApp server, it is suggested to use Podman/Docker solution but if you cannot do it there is the native installation.

Running with Podman#

Podman is a software to manage containers, pods and images, it can run on different platform including Linux, Windows and Mac. Its power is that you can run it as normal user instead of an administrator of the computer/server.

Podman requirements#

Install dependencies:

  • Podman

  • Podman-compose

  • Git

Debian < 12#

apt install git podman python3-pip
pip3 install podman-compose

Debian >= 12#

apt install git podman podman-compose

Ubuntu < 24#

sudo apt install git podman python3-pip
sudo pip3 install podman-compose

Ubuntu >= 24#

sudo apt install git podman podman-compose

Instructions#

First clone the DigiAgriApp server repository

git clone https://gitlab.com/digiagriapp/digiagriapp-server

Next steps is to run the Podman service, this is required to run podman containers, remember to start the Podman service with the user that you will use to run DigiAgriApp containers (we suggest to not run as root user)

podman system service --time=0 unix:///run/user/1000/podman.sock

/run/user/1000/podman.sock is the path to the Podman socket, you can use any path where the user can write; this path will be used later in the configuration. As socket you can also use TCP url.

At this point enter in the docker folder inside digiagriapp-server directory and now it is possible to build the needed images with

podman-compose -f compose.yml build

Finally you can start the containers; using DOCKER_SOCK=/run/user/1000/podman.sock we are telling to Podman to use the Podman socket created before. If you are running DigiAgriApp in production please read Changing parameters and Running in production sections.

DOCKER_SOCK=/run/user/1000/podman.sock podman-compose -f compose.yml up -d

You can also modify permanently the socket changing the compose.yml file. The are some lines to change, using Podman it is required to modify

${DOCKER_SOCK:-/var/run/docker.sock}:/var/run/docker.sock:ro

with

${DOCKER_SOCK:-/run/user/1000/podman.sock}:/var/run/docker.sock:ro

At this point you should be able to reach DigiAgriApp server admin panel using a browser and going to https://digiagriapp.containers.localhost:8443/agriadm/

Default user and password are admin, if you want modify it please read next section.

⚠ WARNING

We suggest to copy compose.yml digiagri.env and db.env to not have problem with updates of the source code. If you rename digiagri.env and db.env please replace them in the new compose.yml file.

Change parameters#

To change default parameters there are two different file in docker directory.

In the digiagri.env file there are all the settings related to DigiAgriApp server. DIGIAGRI_USER, DIGIAGRI_PASSWORD, DIGIAGRI_EMAIL are the username, password and email of the DigiAgriApp server administrator. REDIS is the server name of redis service, please not change this variable. REGISTRATION is a variable for activate registration capability, by default it is not activated; set it to True only if you want provide a public instance of DigiAgriApp. APP_NAME is the name of instance, APP_PROVIDER is the name of the organization providing thec DigiAgriApp instance, APP_URL is the domain of the service. EMAIL_* are all the settings of a email server to send email from the DigiAgriApp instance. OPENROUTESERVICE_TOKEN is the token of OpenRouteService to calculate some routes between farms and waste destination, to get a token you can signup here. TRAEFIK_BASIC_AUTH value is the login user and password for Traefik, the USER should a string (possibily lower case), HASHEDPASSWORD a password hashed using MD5, SHA1, or BCrypt, more info at https://doc.traefik.io/traefik/middlewares/http/basicauth/. The $ symbol should be duplicated to work properly (a password like this $apr1$gzyBBd92$.l0yXuajTvk9p/ovMafmY/ should became $$apr1$gzyBBd92$$.l0yXuajTvk9p/ovMafmY/)

In the db.env file instead you can find parameters used by PostgreSQL. You can modify the PostgreSQL admin user (POSTGRES_USER) and its password (POSTGRES_PASSWORD); you could also change the database name (POSTGRES_DB). Please not change POSTGRES_HOST variable

Running in production with Let’s encrypt#

When you use this solution in production you need also to change some other lines in the compose.production.yml or compose_tls.yml file:

  • check the permission of letsencrypt/acme.json file, it should be 600 in the case it is different please set it with chmod command (no needed if you use compose_tls.yml)

  • replace APP_URL value in digiagri.env with your DNS address and change default passwords in both digiagri.env and db.env files.

  • replace the TRAEFIK_BASIC_AUTH and YOUR_DOMAIN values in the choose YML file

Running in production with your own SSL certificate#

If you want to use your own TLS certificates you need to use the compose_tls.yml file and follow the next steps.

Copy/move all the used certificates there in the certs folder.

Copy the digiagriapp-server/certs-traefik.yaml file to a new one modify the lines::

tls:
  certificates:
    - certFile: /etc/certs/cert1.crt
      keyFile: /etc/certs/cert1.key

You need to replace cert1.crt, cert1.key with the name of your certificate, you have to add the certFile, keyFile lines for each certificate you added into the certs folder.

In the new compose_tls.yml file modify the name of certs-traefik.yml files with the new one.

Running multiple instances of DigiAgriApp server#

If you want to run multiple DigiAgriApp server instaces in the same serve copy the compose.yaml or compose_tls.yaml file and remove the traefik service section. At this point you need to rename postgresql, redis, django and celery with a new name, please remember to change also some parameters of the environment variable files. In db.env set the right value for the variable POSTGRES_HOST with the new name of postgresql service.

Running with Docker#

Docker is a platform for developing, shipping and running application using containers. It’s similar to Podman but it is run as administrator.

Docker requirements#

Install dependencies:

  • Docker

  • Docker-compose

  • Git

Debian/Ubuntu#

sudo apt install git docker.io docker-compose-v2 containerd

In older Debian/Ubuntu version you can install docker-compose V1 with the following command

sudo apt install git docker docker-compose

Docker instructions#

First clone the DigiAgriApp server repository

git clone https://gitlab.com/digiagriapp/digiagriapp-server

Enter in the docker folder inside digiagriapp-server folder and it is possible can build the needed images and start all the needed services

sudo docker compose -f compose.yml build

If you are running DigiAgriApp in production please read Changing parameters and Running in production sections.

Now you can start the services; the first time you run the following command the images of needed containers will be downloaded.

sudo docker compose -f compose.yml up -d

At this point you should be able to reach DigiAgriApp server admin panel using a browser and going to https://digiagriapp.containers.localhost:8443/agridm/

Default user and password are admin.

Configure parameters#

Please refer to the Changing parameters

Running in production#

Please refer to the previous Podman Running in production section

Running with native installation#

With this solution you don’t use any container and install all the needed software on your machine.

Requirements#

Install dependencies:

  • Python 3 >= 3.7

  • PostgreSQL

  • PostGIS

  • Proj4

  • GDAL

  • redis

  • Git

Install Debian dependencies#

apt install git proj-bin python3 postgresql postgis gdal-bin libproj-dev libgeos-dev libpq-dev redis

Install Ubuntu dependencies#

sudo apt install git proj-bin python3 postgresql postgis gdal-bin libproj-dev libgeos-dev libpq-dev redis

First steps#

Please clone the DigiAgriApp server repository

git clone https://gitlab.com/digiagriapp/digiagriapp-server

Set two needed environment variables to download and install the correct Python GDAL and Proj version. To get the Proj version run in the command line proj. For Proj please refer to the compatibility matrix table, for example if you have Proj 8.2.1 you can set PROJ_VER=”3.4.1”

export GDAL_VER=`gdal-config --version`
export PROJ_VER="3.4.1"

Enter in the directory and create the Python environment, activate it and install the needed libraries

cd digiagriapp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Create the database, you can choose between different ones but we really suggest to use PostgreSQL with the PostGIS extension.

createdb digiagri
psql -c "CREATE EXTENSION postgis" digiagri
psql -c "CREATE EXTENSION postgis_raster" digiagri

Make a copy of src/DigiAgriApp/template_settings.py file, rename it to src/DigiAgriApp/settings.py, and set up the right parameters for PostgreSQL user and MQTT if you need it.

At this point initialize the database (since version v.0.2.0 the migrations are already in the source code)

python src/manage.py migrate
python src/manage.py collectstatic

Next steps is to create admin user for DigiAgriApp, please remember to use a strong password

python src/manage.py createsuperuser

Testing#

Run Django app#

python src/manage.py runserver
⚠ WARNING

Each time you execute the file make sure you activated the python environment

Run Celery#

DJANGO_SETTINGS_MODULE='DigiAgriApp.settings' celery -A DigiAgriApp.digi_celery worker -l INFO

Production with uwsgi#

Django configuration#

Install uwsgi library

pip install uwsgi

Modify the ini file, to fix the full paths

vim src/digiagriapp.ini

Create the log directory

mkdir log

Run uwsgi

uwsgi src/digiagriapp.ini

To look the log you can use tail command

tail -f log/uwsgi.log

To be exposed to internet you need a HTTP server like Apache or NGIX. For example with Apache you need to use a configuration file like this

    ServerName DOMAIN

    ServerAdmin EMAIL@DOMAIN
    DocumentRoot /FULLPATH/TO/SRC/DIRECTORY/

    ErrorLog ${APACHE_LOG_DIR}/bioeconomy-error.log
    CustomLog ${APACHE_LOG_DIR}/bioeconomy-access.log combined

    <Location />
        Options FollowSymLinks Indexes
        SetHandler uwsgi-handler
        uWSGISocket 127.0.0.1:3131
        uWSGIMaxVars 256
    </Location>

    <Location /static>
        SetHandler none
        Options -Indexes
    </Location>

    <Location /media>
        SetHandler none
        Options -Indexes
    </Location>

    Alias /media/ /FULLPATH/TO/SRC/DIRECTORY/media/

    Alias /static/ /FULLPATH/TO/SRC/DIRECTORY/static/

    <Directory /FULLPATH/TO/SRC/DIRECTORY/>
        Require all granted
    </Directory>

    <Directory /FULLPATH/TO/SRC/DIRECTORY/media/>
        Options FollowSymLinks
        Order allow,deny
        Allow from all
    </Directory>

    <Directory /FULLPATH/TO/SRC/DIRECTORY/static/>
        Options FollowSymLinks
        Order allow,deny
        Allow from all
    </Directory>

    <Location /.well-known/acme-challenge>
        Require all granted
        SetHandler none
        Options -Indexes
    </Location>

    Alias /.well-known/acme-challenge/ /var/lib/letsencrypt/http_challenges/

Celery configuration#

Copy the service template to the right systemd folder and modify it fixing all the paths

sudo cp src/conf/template_celery.service /etc/systemd/system/

Copy the Celery configuration file from the template template_celery.conf and fix the paths

cp src/conf/template_celery.conf src/conf/celery.conf

Start the celery system with

sudo systemctl start celery.service

If you facing problem starting Celery you can try inside the src folder