Skip to content

SØAD Installation Guide

There are two types of packaging for SØAD, a standalone (default package) and container. Depending on your requirement, you have to choose what suits you best.

SØAD Standalone package includes everything needed to run it as a server application, except the database. You have to manually install your database (default supported database is MySQL).

SØAD can run on any OS that supports JVM, however currently the supported platforms are Linux and Windows only.

Prerequisites:

  • JVM/JDK version 11 or latest
  • nginx

Instruction for Standalone package installation

Install JVM/JDK 11

  1. Update package index:

    sudo apt update

  2. Install JDK 11

    sudo apt install openjdk-11-jdk

  3. Verify Installation:

    java -version

Install and setup MySQL

  1. Get MySQL repository configuration package 
    wget https://dev.mysql.com/get/mysql-apt-config_0.8.12-1_all.deb
  2. Install MySQL repository configuration package 
    sudo dpkg -i mysql-apt-config_0.8.12-1_all.deb
  3. Fetches a public GPG key 
    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B7B3B788A8D3785C
  4. Update package list 
    sudo apt-get update
  5. Install MySQL 
    sudo apt install -f mysql-client=5.7* mysql-community-server=5.7* mysql-server=5.7*
  6. For setting MySQL run: 
    sudo mysql_secure_installation
  7. Verify MySQL is installed 
    mysql -u root -p
  8. Create database for SØAD IDE (soadmin) and default application:
    • Database soadmin: 
      CREATE DATABASE soadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    • Database app (replace with the name of application): 
      CREATE DATABASE app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

  9. Create two users:

    • User soadmin_user: 
      CREATE USER 'soadmin_user'@'localhost' IDENTIFIED BY '<password>';
    • User app_user (replace with the name of application): 
      CREATE USER 'app_user'@'localhost' IDENTIFIED BY '<password>';

    Tip

    Change the password to more secured phrase. You can use any name or password that you want, we are going to need these on the configuration file.

  10. Grant privileges on a database:

    ```mysql
GRANT ALL PRIVILEGES ON soadmin.* TO 'soadmin_user'@'localhost';
GRANT ALL PRIVILEGES ON app.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;
```

  11. Create the tables for database soadmin using script file provided. 

    mysql -u root -p soadmin < soadmin-db.sql

Setup and configure SØAD

  1. Install zip utility if not already installed: 
    sudo apt install zip
  2. Unpack (unzip) SØAD standalone package in your preferred location. The location of SØAD package will need to be set as SUFIA_HOME later.: 
    unzip sufia.app.zip
  3. Set database credential:
    1. Open sufia.app\web\WEB-INF\classes\sufia.properties file using editor.
    2. Change the username and password accordingly: 
      db.default.url = jdbc:mysql://127.0.0.1:3306/app?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.default.driver_class = com.mysql.cj.jdbc.Driver
db.default.username = app_user
db.default.password = <password>

#this is for SØAD IDE
db.s0adm.url = jdbc:mysql://127.0.0.1:3306/soadmin?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.s0adm.driver_class = com.mysql.cj.jdbc.Driver
db.s0adm.username = soadmin_user
db.s0adm.password = <password>
  4. Update sufia.app\startup.sh file for SUFIA_HOME location: 
    set SUFIA_HOME=/home/ubuntu/sufia.app

  5. Test run SØAD:

    • Go to /home/ubuntu/sufia.app directory and run: 

      chmod +x *.sh
./startup.sh
      If everything goes well, you should see a console.log file created in the home folder. Check the log file and make sure the server is running successfully without any error.

      Now the server is running on default port (8080), go to your browser and open: http://localhost:8080. You should see the default SØAD home page

      Image title
      SØAD IDE Login Page

  6. Install SØAD as a service

    Copy the sufia.service file to /etc/systemd/system/ directory: 

    sudo cp sufia.service /etc/systemd/system/
    Then enable and start the service: 
    sudo systemctl enable sufia.service
sudo systemctl start sufia.service
    You can check the status of the service using: 
    sudo systemctl status sufia.service
    You can also view the logs for the service using: 
    journalctl -u sufia.service

  7. Update License Information

    For first time login, only master user is allowed to login. You will be given a default username and password for SØAD master user. Use that for first time login.

    Upon successfully logging into the system, navigate to the Settings page and select the License menu. Retrieve the license key from the email you received, then click the Update License button. Paste the copied key into the designated field and click Verify to complete the activation process.

    Image title
    License Page

Install JVM/JDK 11 for Windows

  1. Before installing JDK 11, check if JDK is already installed on your system by running the following command:

    java -version

    If the command outputs a version number, JDK is already installed, and you can skip JVM installation step.

  2. Download JDK 11:

    Download the Windows x64 installer (e.g., OpenJDK11U-jdk_x64_windows_*.msi) and run the installer to complete the installation process.

  3. Verify Installation:

    • Open Command Prompt and run: 
      java -version
    • Expected output: 
      java version "11.0.x" 202x-xx-xx LTS

Install and setup MySQL for Windows

  1. Download MySQL:

  2. Install MySQL:

    1. Run the installer and choose the Server Only or Full Installation.

    2. Set up the root password when prompted.

    3. Complete the installation process.

  3. Verify Installation:

    1. Open Command Prompt and run: 
      mysql -u root -p
    2. Enter the password to access MySQL.
  4. Create database soadmin and application:
    • Database soadmin: 
      CREATE DATABASE soadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    • Database app (replace with the name of application): 
      CREATE DATABASE app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

  5. Create two user soadmin and application:

    • User soadmin_user: 
      CREATE USER 'soadmin_user'@'localhost' IDENTIFIED BY '<password>';
    • User app_user (replace with the name of application): 
      CREATE USER 'app_user'@'localhost' IDENTIFIED BY '<password>';

    Tip

    Change the password to more secured phrase. You can use any name or password that you want, we are going to need these on the configuration file.

  6. Grant privileges on a database:

    1. Grant privileges to these databases using previously created user. 
      GRANT ALL PRIVILEGES ON soadmin.* TO 'soadmin_user'@'localhost';
GRANT ALL PRIVILEGES ON app.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;
  7. Create the tables for database soadmin using script file provided. 
    mysql -u root -p soadmin < soadmin-db.sql

Setup and configure SØAD for Windows

  1. Download and install 7-Zip from 7-Zip official website.
  2. Unpack (unzip) SØAD standalone package in your preferred location. The location of SØAD package will need to be set as SUFIA_HOME later.
    • Right-click on the downloaded sufia.app.zip file and select "Extract Here" or "Extract to sufia.app\".
  3. Set database credential for SØAD:
    1. Open sufia.app\web\WEB-INF\classes\sufia.properties file using editor.
    2. Change the username and password accordingly: 
      db.default.url = jdbc:mysql://127.0.0.1:3306/app?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.default.driver_class = com.mysql.cj.jdbc.Driver
db.default.username = app_user
db.default.password = <password>

#this is for SØAD IDE
db.s0adm.url = jdbc:mysql://127.0.0.1:3306/soadmin?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.s0adm.driver_class = com.mysql.cj.jdbc.Driver
db.s0adm.username = soadmin_user
db.s0adm.password = <password>
  4. Update sufia.app\startup.cmd file for SUFIA_HOME location: 
    set SUFIA_HOME=D:\sufia.app

  5. Test run SØAD:

    • Launch Command Prompt in the D:\sufia.app directory and run: 

      .\startup.cmd
      If everything goes well, you should see a console.log file created in the home folder. Check the log file and make sure the server is running successfully without any error.

      Now the server is running on default port (8080), go to your browser and open: http://localhost:8080. You should see the default SØAD home page

      Image title
      SØAD Homepage

  6. Update License Information

    For first time login, only master user is allowed to login. You will be given a default username and password for SØAD master user. Use that for first time login.

    Upon successfully logging into the system, navigate to the Settings page and select the License menu. Retrieve the license key from the email you received, then click the Update License button. Paste the copied key into the designated field and click Verify to complete the activation process.

    Image title
    License Page

    Now your SØAD application is ready.

Setup web server as proxy to SØAD server

You can now setup web server as proxy to SUFIA server (e.g. nginx, apache). You also can setup SSL on the web server. Refer to these excellent articles:

  1. Install Nginx on UBuntu

  2. Secure Nginx with Let's Encrypt

  3. Nginx Reverse Proxy

Container

SØAD can be run in a container. The container is built using Docker and can be run on any platform that supports Docker.

Prerequisites:

  • Docker installed on your system

Pulling the SØAD Docker Image

To pull the SØAD Docker image, run the following command:

docker pull registry.gitlab.com/pakcusoft/soad-cloud
This command will download the latest SØAD image from the GitLab registry.

Running SØAD in a Container

Before running the container, ensure that you have a MySQL database set up and accessible. You will need to create a database named soadmin and another for your application (e.g., app), along with the necessary users and permissions as described in the standalone installation section.

To setup the configuration for the SØAD container, you can create a sufia.properties file with the following content:

db.default.url=jdbc:mysql://<mysql_host>:3306/app?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.default.driver_class=com.mysql.cj.jdbc.Driver
db.default.username=app_user
db.default.password=<app_password>

db.s0adm.url=jdbc:mysql://<mysql_host>:3306/soadmin?autoReconnect=true&useSSL=false&allowPublicKeyRetrieval=true
db.s0adm.driver_class=com.mysql.cj.jdbc.Driver
db.s0adm.username=soadmin_user
db.s0adm.password=<soadmin_password>

Replace <mysql_host>, <app_password>, and <soadmin_password> with your actual MySQL host and credentials. You can mount this configuration file into the container when you run it. To run the SØAD container with the configuration file, use the following command:

docker run -d -p 8080:8080 \
    --name sufia \
    -v /path/to/sufia.properties:/app/conf/sufia.properties \
    -v /path/to/local/webapp:/app/webapp \
    registry.gitlab.com/pakcusoft/soad-cloud

Replace /path/to/sufia.properties with the actual path to your sufia.properties file and /path/to/local/webapp with the path to your local web application folder on your host machine. This command will run the SØAD container in detached mode, mapping port 8080 of the container to port 8080 on your host machine, mounting the configuration file, and mounting the local web application folder into the container.

Accessing the SØAD Application

Once the container is running, you can access the SØAD application by navigating to http://localhost:8080 in your web browser. You should see the SØAD IDE Login Page.