Installing AVAA Server on Ubuntu Server

Domain

A domain name is required and should already point to the server we are about to set up. Throughout this installation guide, replace demo.avaa-toolkit.org with your actual domain name.

Ports

Make sure the following inbound TCP ports are opened:

80 (HTTP)
443 (HTTPS)
41744 (AVAA WebSocket)

Install utilities

sudo apt install zip curl

Install Java

sudo apt install default-jre

Install Python with venv

sudo apt install python3-venv

Install PyEnv

PyEnv should also be installed to allow separate Python versions.

From pyenv suggested build environment:

sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Then use the official automatic installer

curl -fsSL https://pyenv.run | bash

Finally, follow instructions to add PyEnv to PATH

Open a new shell and check it worked with pyenv --version

Install FFmpeg

sudo apt install ffmpeg

Install AVAA

cd ~/
wget https://avaa-toolkit.org/release/latest
unzip ./latest
rm ./latest
sudo mv ./avaa-toolkit /opt/avaa-toolkit
cd /opt/avaa-toolkit
chmod +x ./avaa-toolkit.sh
chmod 770 ./editor
chown www-data:users ./editor
# create a folder for user generated files
mkdir ./tickets

Install Apache

sudo apt install apache2
sudo nano /etc/apache2/sites-available/avaa.conf

Basic configuration file (adapt with your domain name)

<VirtualHost *:80>
    ServerName demo.avaa-toolkit.org
    ServerAlias demo.avaa-toolkit.org
    DocumentRoot /opt/avaa-toolkit/editor
    ErrorLog ${APACHE_LOG_DIR}/avaa_error.log
    CustomLog ${APACHE_LOG_DIR}/avaa_access.log combined
</VirtualHost>

Enable site and restart apache

sudo a2ensite /etc/apache2/sites-available/avaa.conf
sudo service apache2 restart

Install certbot for SSL certificate

HTTPS is required for WebSocket connections, so we need to set it up.

LetsEncrypt provides free certificates and can be automated with certbot.

sudo snap install --classic certbot 
sudo python3 -m venv /opt/certbot/
sudo /opt/certbot/bin/pip install --upgrade pip
sudo /opt/certbot/bin/pip install certbot certbot-apache

Now let's obtain a certificate

sudo /opt/certbot/bin/certbot certonly --webroot --webroot-path "/opt/avaa-toolkit/editor" -d demo.avaa-toolkit.org

Configure Apache with SSL

Let's change now our httpd configuration file

sudo nano /etc/apache2/sites-available/avaa.conf

You should adapt the following sample configuration:

<VirtualHost *:80>
    ServerName demo.avaa-toolkit.org
    ServerAlias demo.avaa-toolkit.org
    DocumentRoot /opt/avaa-toolkit/editor
    ErrorLog /opt/avaa-toolkit/logs/apache_error.log
    CustomLog /opt/avaa-toolkit/logs/apache_access.log combined
    Redirect permanent / https://demo.avaa-toolkit.org/
</VirtualHost>
<VirtualHost *:443>
    SSLEngine On
    SSLProtocol all -SSLv2 -SSLv3
    SSLCertificateFile /etc/letsencrypt/live/demo.avaa-toolkit.org/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/demo.avaa-toolkit.org/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/demo.avaa-toolkit.org/chain.pem
    ServerAdmin dev@avaa-toolkit.org
    ServerName demo.avaa-toolkit.org
    ServerAlias *.demo.avaa-toolkit.org
    DocumentRoot /opt/avaa-toolkit/editor
    ErrorLog /opt/avaa-toolkit/logs/apache_error.log
    CustomLog /opt/avaa-toolkit/logs/apache_access.log combined
    Alias /tickets /opt/avaa-toolkit/tickets
    Alias /assets /opt/avaa-toolkit/assets
    Alias /include /opt/avaa-toolkit/include
    Alias /upload /opt/avaa-toolkit/upload
</VirtualHost>
<Directory "/opt/avaa-toolkit/upload">
    Require all granted
    Options Indexes
    Order allow,deny
    Allow from all
</Directory>
<Directory "/opt/avaa-toolkit/tickets">
    Require all granted
    Options Indexes
    Order allow,deny
    Allow from all
</Directory>
<Directory "/opt/avaa-toolkit/assets">
    Require all granted
    Order allow,deny
    Allow from all
    Options Indexes FollowSymLinks
</Directory>
<Directory "/opt/avaa-toolkit/include">
Require all granted
    Order allow,deny
    Allow from all
</Directory>

We must also install httpd ssl dependencies

sudo a2enmod ssl
sudo systemctl reload apache2

Make a Java compatible certificate

A custom JKS certificate is required for the WebSocket server.

# create a valid full CAfile
sudo cat /etc/letsencrypt/live/demo.avaa-toolkit.org/fullchain.pem /etc/letsencrypt/live/demo.avaa-toolkit.org/chain.pem > allchain.pem

Build JKS

# use password "avaapass"
sudo openssl pkcs12 -export -in /etc/letsencrypt/live/demo.avaa-toolkit.org/cert.pem -inkey /etc/letsencrypt/live/demo.avaa-toolkit.org/privkey.pem -out cert.p12 -name avaacert -CAfile allchain.pem -caname root
sudo keytool -importkeystore -deststorepass avaapass -destkeypass avaapass -destkeystore avaacert.jks -srckeystore cert.p12 -srcstoretype PKCS12 -srcstorepass avaapass -alias avaacert

Make sure avaacert.jks is in avaa-toolkit directory (currently the certificate path/name/password are hardcoded)

Configure launcher to use SSL

Edit avaa-toolkit.sh and adapt with your server's RAM and domain origin:

java -Xmx8g -jar ./avaa-toolkit.jar --server --server-ssl --server-allowed-origin "https://demo.avaa-toolkit.org"

Install PDF converter

sudo apt install libxdamage1
sudo mkdir /opt/chrome-headless-shell
sudo wget -O /opt/chrome-headless-shell/chrome-headless-shell-linux64.zip https://storage.googleapis.com/chrome-for-testing-public/120.0.6098.0/linux64/chrome-headless-shell-linux64.zip
sudo unzip /opt/chrome-headless-shell/chrome-headless-shell-linux64.zip -d /opt/chrome-headless-shell/

Edit avaa-config.xml and set

<PDF exe="/opt/chrome-headless-shell/chrome-headless-shell-linux64/chrome-headless-shell">

Install MongoDB

Following the official MongoDB installation docs

sudo apt-get install gnupg
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
sudo apt-get update
sudo apt-get install -y mongodb-org mongodb-mongosh

Start AVAA

./avaa-toolkit.sh

Configure WebDAV (optional)

sudo a2enmod dav_fs
sudo chown www-data:www-data ./projects
sudo nano /etc/apache2/sites-enabled/avaa.conf

add the following Location:

<Location /projects>
    DAV On
    AuthType Basic
    AuthName "webdav"
    AuthUserFile /usr/local/apache2/webdav.passwords
    Require valid-user
</Location>

Don't forget to add webdavhtpasswd attribute to the SERVER LOGIN element:

<LOGIN webdavhtpasswd="/usr/local/apache2/webdav.passwords" />

so AVAA will be able to update the webdav passwords when a user password is changed.