Installation on Linux

Notes

As an example, we are using sgi.domain.com and sgi-back.domain.com as the domains. This should be changed to the real subdomains

Debian base installation (Ubuntu 22.04 LTS)

Backend

1. First install Apache + PHP

sudo add-apt-repository ppa:ondrej/php -y

sudo apt-get install apache2 php8.4 libapache2-mod-php8.4

Make sure apache and php are running OK by creating a phpinfo.php file on the web folder, usually in /var/www/ or /var/www/html

2. Next install all dependencies and extensions needed

Current PHP extensions: sudo apt install php8.4-fpm php8.4-cli php8.4-curl php8.4-dev php8.4-mysql php8.4-ldap php8.4-xml php8.4-curl php8.4-gd php8.4-zip php8.4-mbstring php8.4-soap php8.4-fileinfo php8.4-sqlite3 php8.4-intl php8.4-bcmath php8.4-redis php8.4-imagick

To enable PHP 8.4 FPM in Apache2 do:

a2enmod proxy_fcgi setenvif
a2enconf php8.4-fpm

Check PHP version being used: php -v If the PHP version is wrong (e.g. PHP8.3), change the default PHP version used: sudo update-alternatives --config php.

3. Next install redis: sudo apt-get install redis-server

4. Next install composer

sudo apt-get install curl
curl -sS https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
sudo composer self-update
composer -v

5. Check out the backend to a web folder, usually put the folder in the /var/www folder, and name give it the name do the subdomain when possible, something like /var/www/sgi-back.client.com

git clone https://gitlab.wemake.pt/wemake/sgi/backend/core.git /var/www/sgi-back.client.com

cd /var/www/sgi-back.client.com
git config core.fileMode false

6. Create a configuration file

cd /var/www/sgi-back.client.com
sudo cp .env.example .env

7. Run composer install: sudo composer install

[Symfony\Component\Debug\Exception\FatalThrowableError]

Undefined class constant 'SQLSRV_ATTR_FETCHES_NUMERIC_TYPE'

In this case just edit the config/database.php file and comment the lines

PDO::ATTR_STRINGIFY_FETCHES => false,

PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true

8. Configure the .env file (Always check the current configuration file as this may be already obsolete)

8. Generate the application key: php artisan key:generate and the JWT secret: php artisan jwt:secret

9. Set the correct permissions

sudo chown -R www-data storage/ bootstrap/cache/ && sudo chmod -R 775 storage/ bootstrap/cache/

9.5. ☺ Create the database, user and grant the user privileges over the database

mysql
CREATE DATABASE <database_name> CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci;
CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON <database_name>.* TO 'user'@'localhost';

10. Run migrations: php artisan migrate

11. Create a new apache configuration file under the folder /etc/apache2/sites-available/. Name it something like sgi-back.domain.com.conf

Without HTTPS

<Directory /var/www/html/sgi-back.domain.com/public>
    AllowOverride All
    Require all granted
</Directory>

<VirtualHost sgi-back.domain.com:80>
    ServerName sgi-back.domain.com
    DocumentRoot /var/www/html/sgi-back.domain.com/public

    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/php/php8.4-fpm.sock|fcgi://localhost"
    </FilesMatch>

    ErrorLog /var/log/apache2/sgi-back.domain.com/apache-logs/error.log
    CustomLog /var/log/apache2/sgi-back.domain.com/apache-logs/access.log combined
</VirtualHost>

With HTTPS

<Directory /var/www/html/sgi-back.domain.com/public>
    AllowOverride All
    Require all granted
</Directory>
<VirtualHost sgi-back.domain.com:443>
    ServerName sgi-back.domain.com
    DocumentRoot /var/www/html/sgi-back.domain.com/public

    SSLEngine on
    SSLCertificateFile <path_to_cert_file>
    SSLCertificateKeyFile <path_to_key_file>

    ErrorLog /var/log/apache2/sgi-back.domain.com/apache-logs/error.log
    CustomLog /var/log/apache2/sgi-back.domain.com/apache-logs/access.log combined
</VirtualHost>

12. Enable the new configuration: sudo a2ensite sgi-back.domain.com.conf

13. Because of the php-fpm configuration: sudo a2enmod actions proxy_fcgi rewrite

14. Reload apache: sudo systemctl reload apache2

15. Test that the backend is online: http://sgi-back.domain.com/ you should get an NotFoundHttpException error, which is normal because there's no route for root

Laravel Echo Server

1. Install laravel-echo-server: sudo npm install -g laravel-echo-server

2. Copy the laravel-echo-server.example.json to laravel-echo-server.json: cp laravel-echo-server.example.json laravel-echo-server.json

3. Configure the configuration file laravel-echo-server.json

Without HTTPS

{
  "appKey": "47r1i66li4cn9anb4pocpb9h6eb5fc7d35f5lhs363gho1kmqcqf2tred6p2",
  "authHost": "https://sgi-back.domain.com",
  "authEndpoint": "/broadcasting/auth",
  "database": "redis",
  "databaseConfig": {
    "redis": {
      "port": "6379",
      "host": "127.0.0.1",
      "options": {
        "db": 1
      }
    },
    "sqlite": {
      "databasePath": "/database/laravel-echo-server.sqlite"
    }
  },
  "devMode": false,
  "host": "sgi-back.domain.com",
  "port": "6001",
  "referrers": [
    {
      "host": "*",
      "apiKey": "nrhmk8ic64lgnqbs6t794gpj6per33ho5q34j2mrgia61j8hf238rf0c014b"
    }
  ],
  "socketio": {
    "cookie": "false"
  },
  "protocol": "http",
  "sslCertPath": "",
  "sslKeyPath": "",
  "verifyAuthPath": true,
  "verifyAuthServer": false
}

With HTTPS

{
  "appKey": "47r1i66li4cn9anb4pocpb9h6eb5fc7d35f5lhs363gho1kmqcqf2tred6p2",
  "authHost": "https://sgi-back.domain.com",
  "authEndpoint": "/broadcasting/auth",
  "database": "redis",
  "databaseConfig": {
    "redis": {
      "port": "6379",
      "host": "127.0.0.1",
      "options": {
        "db": 1
      }
    },
    "sqlite": {
      "databasePath": "/database/laravel-echo-server.sqlite"
    }
  },
  "devMode": false,
  "host": "sgi-back.domain.com",
  "port": "6002",
  "referrers": [
    {
      "host": "*",
      "apiKey": "nrhmk8ic64lgnqbs6t794gpj6per33ho5q34j2mrgia61j8hf238rf0c014b"
    }
  ],
  "socketio": {
    "cookie": "false"
  },
  "protocol": "https",
  "sslCertPath": "<path_to_cert_file>",
  "sslKeyPath": "<path_to_key_file>",
  "verifyAuthPath": true,
  "verifyAuthServer": false
}

4. Run laravel-echo-server start on the backend folder and check if it works. If it is working, stop it by doing Ctrl+c and go to next step

5. Use supervidord to configure the service, create a new file /etc/supervisor/conf.d/sgi-back.domain.com.conf and use the following configuration (change as needed)

[program:laravel-echo-server]
directory=/var/www/sgi-back.domain.com
command=laravel-echo-server start
autostart=true
autorestart=true
user=root
redirect_stderr=true
stdout_logfile=/var/www/sgi-back.domain.com/storage/logs/laravel-echo-server.log

6. Start the service supervisorctl start laravel-echo-server

7. (OPTIONAL) If, after installation, you see that the server is not working, it might be that the port is not open (e.g. when you have multiple installations on the same server machine), do the following:

   sudo iptables -A INPUT -p tcp --match multiport --dports x11-1:<port-number> -j ACCEPT

   Replace <port-number> to with the associated port (e.g. 6050).

To show the new rule: sudo iptables -L

It should show something like this:

ACCEPT   tcp  --  anywhere     anywhere   multiport dports x11-1:<port-number>

Laravel Queue

1. Use supervidord to configure the service, create (or edit) a file /etc/supervisor/conf.d/sgi-back.domain.com.conf and use the following configuration (change as needed)

[program:laravel-queue-work]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/sgi-back.client.com/artisan queue:work --sleep=3
autostart=true
autorestart=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/var/www/sgi-back.domain.com/storage/logs/laravel-queue-work.log

2. Start the service supervisorctl start laravel-queue-work

Scheduler

1. To configure the scheduler to run the scheduled jobs (every minute jobs, daily jobs, etc.), we need to use crontab.

   crontab -e

2. Add the following line at the end:

   * * * * * php /var/www/sgi-back.client.com/artisan schedule:run >> /dev/null 2>&1

You may have to specify the PHP version (e.g. php8.4) if you're installing in a server that has other clients installed that use previous PHP versions.

WKHTMLTOPDF

1. Install required packages if they aren’t already installed: sudo apt-get install libxrender1 wget xfonts-75dpi fontconfig xfonts-base

2. Download the appropriated binaries for the latest stable release. Example for version 0.12.6 and Ubuntu 22.04:

#UBUNTU
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb

#REDHAT
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox-0.12.6.1-3.almalinux8.aarch64.rpm
sudo dnf install ./wkhtmltox-0.12.6.1-3.almalinux8.aarch64.rpm

3. After installing, you can verify that they’re installed by running the commands below:

wkhtmltopdf --version

That should output similar line as shown below:

wkhtmltopdf 0.12.6 (with patched qt)

Run the next command below:

wkhtmltoimage --version

Will output similar line as shown below:

wkhtmltoimage 0.12.6 (with patched qt)

4. Open the .env file, and update the paths to the binaries. Example:

WKHTML_PDF_BINARY="/usr/local/bin/wkhtmltopdf"
WKHTML_IMG_BINARY="/usr/local/bin/wkhtmltoimage"

In order to locate both binaries, run the following commands:

which wkhtmltopdf
which wkhtmltoimage

Frontend

1. Use and existing development machine and export the frontend files by running gulp export

2. Create a folder for the frontend, something like /var/www/sgi.domain.com

3. Set the permissions of the newly created folder sudo chown -R www-data.devel /var/www/sgi.domain.com and chmod -R 775 /var/www/sgi.domain.com

4. Copy the results of the gulp export and change the env.js file accordingly

5. Create a new apache configuration file under the folder /etc/apache2/sites-available/. Name it something like sgi.domain.com.conf

Without HTTPS

<Directory /var/www/html/sgi.domain.com>
        AllowOverride All
        Require all granted
</Directory>
<VirtualHost sgi.domain.com:80>
        ServerName sgi.domain.com
        DocumentRoot /var/www/html/sgi.domain.com

        ErrorLog /var/log/sgi.domain.com/apache-logs/error.log
        CustomLog /var/log/sgi.domain.com/apache-logs/access.log combined
</VirtualHost>

With HTTPS

<Directory /var/www/html/sgi.domain.com>
        AllowOverride All
        Require all granted
</Directory>
<VirtualHost sgi.domain.com:443>
        ServerName sgi.domain.com
        DocumentRoot /var/www/html/sgi.domain.com

        SSLEngine on
        SSLCertificateFile <path_to_cert_file>
        SSLCertificateKeyFile <path_to_key_file>

        ErrorLog /var/log/sgi.domain.com/apache-logs/error.log
        CustomLog /var/log/sgi.domain.com/apache-logs/access.log combined
</VirtualHost>

6. Enable the new configuration: sudo a2ensite sgi.domain.com.conf

7. Reload apache: sudo systemctl reload apache2

8. Test it: http://sgi.domain.com/

Extra documentation

Supervisord - http://supervisord.org/