### Start Asqatasun Services with systemd

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Start-Asqatasun

Use these commands to start the Asqatasun web application and server services managed by systemd.

```bash
systemctl start asqatasun-webapp
systemctl start asqatasun-server
```

--------------------------------

### Install OpenJDK 17

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Installs OpenJDK 17 and configures alternatives for Java. Verify installation with 'java -version'.

```bash
sudo apt install openjdk-17-jre
sudo update-alternatives --config java
java -version
```

--------------------------------

### Enable systemd service

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Enables the Asqatasun service to start automatically at boot.

```bash
systemctl enable asqatasun-webapp.service
```

--------------------------------

### Enable Asqatasun Server at Boot

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Enables the Asqatasun server systemd service to start automatically at system boot time.

```bash
systemctl enable asqatasun-server.service
```

--------------------------------

### Build Asqatasun

Source: https://doc.asqatasun.org/v6/Developer/Referential_creator/Create_a_referential

Install the sebuilder-interpreter JAR and then build the Asqatasun project using Maven. Ensure you are in the Asqatasun root directory.

```bash
cd Asqatasun/

# before first build
mvn install:install-file \
    -DgroupId=com.saucelabs \
    -DartifactId=sebuilder-interpreter \
    -Dversion=1.0.2 \
    -Dpackaging=jar \
    -Dfile=engine/asqatasun-resources/src/main/resources/lib/sebuilder-interpreter-1.0.2.jar

# build
mvn clean install
```

--------------------------------

### Manually Start Asqatasun Server

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Start-Asqatasun

Launch the Asqatasun server by executing its JAR file directly. Configure database connection, logging path, and ports via environment variables and Java system properties. Enables headless Selenium.

```bash
API_PORT="8081"
DB_PORT="3306"
DB_HOST="localhost"
DB_DRIVER="mysql"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
API_LOG_DIR="/var/log/asqatasun/api"

/usr/bin/java \
    -Dwebdriver.firefox.bin=/opt/firefox/firefox  \
    -Dwebdriver.gecko.driver=/opt/geckodriver  \
    -Dapp.logging.path="${API_LOG_DIR}" \
    -Dapp.engine.loader.selenium.headless=true \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar /opt/asqatasun/asqatasun-rest-server.jar \
    --server.port="${API_PORT}" \
    --management.server.port=8091
```

--------------------------------

### Install Postfix and Mailutils for SMTP

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Pre-requisites

Installs Postfix and Mailutils for local SMTP server setup. During re-configuration, select 'Satellite system' and leave the 'SMTP relay' field empty.

```bash
sudo apt-get install postfix mailutils
sudo dpkg-reconfigure postfix
```

--------------------------------

### Install Required Packages on Ubuntu 22.04

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Pre-requisites

Installs Java JRE 17, MariaDB 10.6, libGTK 3, libDbus, and haveged using apt-get. Ensure haveged is installed to prevent slow server startup.

```bash
apt-get --no-install-recommends install \
    openjdk-17-jre         \
    libgtk-3-0             \
    libdbus-glib-1-2       \
    haveged                \
    mariadb-server-10.6
```

--------------------------------

### Manually Start Asqatasun Web Application

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Start-Asqatasun

Launch the Asqatasun web application by executing its WAR file directly. Configure database connection, logging path, and application port via environment variables and Java system properties.

```bash
APP_PORT="8080"
DB_PORT="3306"
DB_HOST="localhost"
DB_DRIVER="mysql"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
APP_LOG_DIR="/var/log/asqatasun/webapp"

/usr/bin/java \
    -Dwebdriver.firefox.bin=/opt/firefox/firefox  \
    -Dwebdriver.gecko.driver=/opt/geckodriver     \
    -Dapp.logging.path="${APP_LOG_DIR}"           \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar /opt/asqatasun/asqatasun-webapp.war \
    --server.port="${APP_PORT}"
```

--------------------------------

### Install Referential into Database

Source: https://doc.asqatasun.org/v6/Developer/Referential_creator/Create_a_referential

Connect to your MySQL database using the provided username and password, and execute the SQL insertion script to install the referential.

```bash
cd tgz-extract-folder/sql/
mysql -u $username -p$myPassword $asqatasunDatabase < $ref-insert.sql
```

--------------------------------

### Configure hurl-options.env

Source: https://doc.asqatasun.org/v6/Developer/Test/E2E-testing-server

Example configuration file for defining the target server URL and port.

```text
proto=http
host=localhost
port=8080
path=/api/v0
```

--------------------------------

### Build Asqatasun with Maven CLI

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Execute Maven commands to validate, clean, install, and test the Asqatasun project. Ensure the working directory is the Asqatasun source root. Logs are directed to specific directories.

```bash
MAVEN_CLI_OPTS="--batch-mode"
MAVEN_OPTS="-Dmaven.repo.local=.m2/repository"
./mvnw $MAVEN_CLI_OPTS validate
./mvnw $MAVEN_CLI_OPTS clean
./mvnw $MAVEN_CLI_OPTS install -Dmaven.test.skip=true
./mvnw $MAVEN_CLI_OPTS test
mkdir -p \
  ~/var/log/asqatasun/webapp/ \
  ~/var/log/asqatasun/server/
```

--------------------------------

### Install Hugo on Debian-based Linux

Source: https://doc.asqatasun.org/v6/Developer/Documentation/Hugo

Use this command to install Hugo by downloading the .deb package from Github releases.

```bash
sudo dpkg -i hugo_XX.YY.ZZ_Linux-64bit.deb
```

--------------------------------

### List Audits Request Example

Source: https://doc.asqatasun.org/v6/Developer/API/Using

Example curl command to list audits using Basic Auth.

```bash
curl -u your_username:your_password -H "Accept: application/json" 
https://asqatasun_instance_server_url/api/v0/audit/
```

--------------------------------

### Run MariaDB 10.6 Docker Container

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Starts a MariaDB 10.6 Docker container with root password and Asqatasun user/database credentials. Uses port 3307 to avoid conflicts.

```bash
docker run \
  --name mysql \
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -e MYSQL_USER=asqatasunDatabaseUserLogin \
  -e MYSQL_PASSWORD=asqatasunDatabaseUserP4ssword \
  -e MYSQL_DATABASE=asqatasun \
  -p 3307:3306 \
  -d \
  mariadb:10.6
```

--------------------------------

### Install Firefox and Geckodriver Locally

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Installs specific versions of Firefox ESR and Geckodriver for local testing. Ensure versions are compatible.

```bash
FIREFOX_VERSION="102.8.0esr"
GECKODRIVER_VERSION="v0.32.2"
FIREFOX_URL_PREFIX="https://download-installer.cdn.mozilla.net/pub/firefox/releases/"
GECKODRIVER_URL_PREFIX="https://github.com/mozilla/geckodriver/releases/download/"
FIREFOX_URL="${FIREFOX_URL_PREFIX}${FIREFOX_VERSION}/linux-x86_64/en-US/firefox-${FIREFOX_VERSION}.tar.bz2"
GECKODRIVER_URL="${GECKODRIVER_URL_PREFIX}${GECKODRIVER_VERSION}/geckodriver-${GECKODRIVER_VERSION}-linux64.tar.gz"

cd /opt
sudo wget "${FIREFOX_URL}"
sudo wget "${GECKODRIVER_URL}"
sudo tar xf "firefox-${FIREFOX_VERSION}.tar.bz2"
sudo tar xf "geckodriver-${GECKODRIVER_VERSION}-linux64.tar.gz"
```

--------------------------------

### Run Hugo Local Development Server

Source: https://doc.asqatasun.org/v6/Developer/Documentation/Hugo

Execute this command from the repository's root to start a local Hugo server. Browse to http://localhost:1313/ to view the site.

```bash
hugo server --buildDrafts
```

--------------------------------

### Build and Package Referential

Source: https://doc.asqatasun.org/v6/Developer/Referential_creator/Create_a_referential

Navigate to the generated referential directory, build it using Maven, and then extract the tarball. This prepares the referential for installation.

```bash
cd $myGeneratedReferential
mvn clean install
cd target
tar xvf tgz
```

--------------------------------

### Run PostgreSQL 16 Docker Container

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Starts a PostgreSQL 16 Docker container with specified user, password, and database name. Default credentials are in application.yml.

```bash
docker run \
  --name postgres \
  -e POSTGRES_USER=asqatasunDatabaseUserLogin \
  -e POSTGRES_PASSWORD=asqatasunDatabaseUserP4ssword \
  -e POSTGRES_DB=asqatasun \
  -p 5432:5432 \
  -d \
  postgres:16
```

--------------------------------

### List Audits Response Example

Source: https://doc.asqatasun.org/v6/Developer/API/Using

JSON response containing a list of audit objects.

```json
[
    {
        "id": 42,
        "subject":{
            "id":51,
            "type":"PAGE",
            "url":"https://mywebsite.fr/",
            "nbOfPages":1,
            "grade":"C",
            "mark":88.89,
            "nbOfFailureOccurrences":1,
            "repartitionBySolutionType":
            [
              {"type":"PASSED","number":8},
              {"type":"FAILED","number":1},
              {"type":"NEED_MORE_INFO","number":67},
              {"type":"NOT_APPLICABLE","number":41},
              {"type":"NOT_TESTED","number":140}
            ]
        },
        "status":"COMPLETED",
        "date":"2025-06-10T12:30:27.000+00:00",
        "tags":[],
        "referential":"RGAA_4_2_1",
        "referentialLevel":"LEVEL_2"
    },
  {
    "id": 43,
    "subject":{
      "id":59,
      "type":"PAGE",
      "url":"https://another_mywebsite.fr/",
      "nbOfPages":1,
      "grade":"F",
      "mark":51.89,
      "nbOfFailureOccurrences":21,
      "repartitionBySolutionType":
      [
        {"type":"PASSED","number":6},
        {"type":"FAILED","number":4},
        {"type":"NEED_MORE_INFO","number":67},
        {"type":"NOT_APPLICABLE","number":41},
        {"type":"NOT_TESTED","number":140}
      ]
    },
    "status":"COMPLETED",
    "date":"2025-08-26T12:30:27.000+00:00",
    "tags":[],
    "referential":"RGAA_4_2_1",
    "referentialLevel":"LEVEL_2"
  }
]
```

--------------------------------

### Build Asqatasun Skipping Dependency Check

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Build the Asqatasun project, skipping the dependency-check task for faster compilation. This command installs the project artifacts and skips tests.

```bash
./mvnw $MAVEN_CLI_OPTS install -Dmaven.test.skip=true -Ddependency-check.skip=true
```

--------------------------------

### Define JAVA_HOME Environment Variable

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Sets the JAVA_HOME environment variable to the path of the Java 17 installation. Add to ~/.zshrc for persistence.

```bash
export JAVA_HOME=/usr/lib/jvm/java-1.17.0-openjdk-amd64  # path indicated for Java 17 by "update-java-alternatives -l" 
```

```bash
echo "export JAVA_HOME=/usr/lib/jvm/java-1.17.0-openjdk-amd64" >> ~/.zshrc
```

--------------------------------

### Create system user and directories

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Sets up the dedicated system user and required directory structure for Asqatasun runtime files.

```bash
ASQA_SYSTEM_USER="asqatasun"
ASQA_HOME="/home/${ASQA_SYSTEM_USER}"

useradd -c "Asqatasun user" -d "${ASQA_HOME}" -l -s /bin/bash "${ASQA_SYSTEM_USER}"
mkdir -p \
  /var/log/asqatasun/webapp/ \
  /var/log/asqatasun/server/ \
  /etc/asqatasun/ \
  "${ASQA_HOME}/.dconf"
chown -R asqatasun \
  /var/log/asqatasun/webapp/ \
  /var/log/asqatasun/server/ \
  /etc/asqatasun/ \
  "${ASQA_HOME}"
```

--------------------------------

### Get Specific Audit Request Example

Source: https://doc.asqatasun.org/v6/Developer/API/Using

Example curl command to retrieve results for a specific audit.

```bash
curl -u your_username:your_password \
-H "Accept: application/json" \
https://asqatasun_instance_server_url/api/v0/audit/42
```

--------------------------------

### Get Specific Audit Response Example

Source: https://doc.asqatasun.org/v6/Developer/API/Using

JSON response containing the details of a specific audit.

```json
{
  "id": 62,
  "subject":{
    "id": 83,
    "type":"PAGE",
    "url":"https://unique_mywebsite.fr/",
    "nbOfPages":1,
    "grade":"F",
    "mark":51.89,
    "nbOfFailureOccurrences":21,
    "repartitionBySolutionType":
    [
      {"type":"PASSED","number":6},
      {"type":"FAILED","number":4},
      {"type":"NEED_MORE_INFO","number":67},
      {"type":"NOT_APPLICABLE","number":41},
      {"type":"NOT_TESTED","number":140}
    ]
  },
  "status":"COMPLETED",
  "date":"2025-08-26T12:30:27.000+00:00",
  "tags":[],
  "referential":"RGAA_4_2_1",
  "referentialLevel":"LEVEL_2"
}
```

--------------------------------

### Create Asqatasun Database and User

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Pre-requisites

Sets up the Asqatasun database and a dedicated user with a password. It's recommended to unset the history file to avoid storing sensitive credentials.

```bash
unset HISTFILE    # Do not keep the following commands in history
DB_DATABASE='asqatasun'
DB_USER='asqatasunDatabaseUserLogin'
DB_PASSWORD='asqatasunDatabaseUserP4ssword'
DB_TOHOST='localhost'

mysql -u root -e "CREATE USER ${DB_USER}@${DB_TOHOST} IDENTIFIED BY \"${DB_PASSWORD}\";"
mysql -u root -e "CREATE DATABASE ${DB_DATABASE} CHARACTER SET utf8;"
mysql -u root -e "GRANT ALL PRIVILEGES ON ${DB_DATABASE}.* TO ${DB_USER}@${DB_TOHOST}"
mysql -u root -e "FLUSH PRIVILEGES;"
```

--------------------------------

### Run Asqatasun Server with MariaDB

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Launch the Asqatasun server using Java, configured for MariaDB. Ensure the JAR file path and database connection details are correctly set. Selenium hub URL and application logging path are also configured.

```bash
ASQATASUN_RELEASE="6.0.0-SNAPSHOT"
DB_PORT="3307"
DB_HOST="localhost"
DB_DRIVER="mariadb"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
APP_LOG_DIR="${HOME}/var/log/asqatasun/server"
JAR_FILE="${HOME}/Asqatasun/server/asqatasun-server/target/asqatasun-server-${ASQATASUN_RELEASE}.jar"

/usr/bin/java \
    -Dapp.engine.loader.selenium.hubUrl=http://localhost:4444/ \
    -Dapp.logging.path="${APP_LOG_DIR}" \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar "${JAR_FILE}"
```

--------------------------------

### Run Asqatasun Server with PostgreSQL

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Launch the Asqatasun server using Java, configured for PostgreSQL. Ensure the JAR file path and database connection details are correctly set. Selenium hub URL and application logging path are also configured.

```bash
ASQATASUN_RELEASE="6.0.0-SNAPSHOT"
DB_PORT="5432"
DB_HOST="localhost"
DB_DRIVER="postgresql"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
APP_LOG_DIR="${HOME}/var/log/asqatasun/server"
JAR_FILE="${HOME}/Asqatasun/server/asqatasun-server/target/asqatasun-server-${ASQATASUN_RELEASE}.jar"

/usr/bin/java \
    -Dapp.engine.loader.selenium.hubUrl=http://localhost:4444/ \
    -Dapp.logging.path="${APP_LOG_DIR}" \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar "${JAR_FILE}"
```

--------------------------------

### Download Asqatasun binaries

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Retrieves the server JAR and webapp WAR files from the official repository.

```bash
ASQA_VERSION="6.0.0-alpha.1"
cd /home/asqatasun
# Asqatasun server (API only)
curl \
  --output "./asqatasun-server-${ASQA_VERSION}.jar" \
  "https://gitlab.com/api/v4/projects/asqatasun%2FAsqatasun/packages/generic/Asqatasun/${ASQA_VERSION}/asqatasun-server-${ASQA_VERSION}.jar"
# Asqatasun Webapp (webapp only)
curl \
  --output "./asqatasun-web-app-${ASQA_VERSION}.war" \
  "https://gitlab.com/api/v4/projects/asqatasun%2FAsqatasun/packages/generic/Asqatasun/${ASQA_VERSION}/asqatasun-web-app-${ASQA_VERSION}.war"
```

--------------------------------

### Get Specific Audit Tests Endpoint

Source: https://doc.asqatasun.org/v6/Developer/API/Using

The endpoint for retrieving test results for a specific audit ID.

```http
GET /api/v0/audit/{auditId}/tests
```

--------------------------------

### Import Data to New Instance

Source: https://doc.asqatasun.org/v6/Operator/Installation/Upgrade/4.0.3_to_4.1.0

Stop the Tomcat service and restore the database backup into the new Asqatasun instance.

```bash
systemctl stop tomcat8.service
mysql --user=asqatasun -p -e "drop database asqatasun;"
mysql --user=asqatasun -p <SAVE_DB_asqatasun.sql
```

--------------------------------

### Run Asqatasun Webapp with MariaDB

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Launch the Asqatasun web application using Java, configured for MariaDB. Ensure the WAR file path and database connection details are correctly set. Selenium hub URL and application logging path are also configured.

```bash
ASQATASUN_RELEASE="6.0.0-SNAPSHOT"
DB_PORT="3307"
DB_HOST="localhost"
DB_DRIVER="mariadb"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
APP_LOG_DIR="${HOME}/var/log/asqatasun/webapp"
WAR_FILE="${HOME}/Asqatasun/web-app/asqatasun-web-app/target/asqatasun-web-app-${ASQATASUN_RELEASE}.war"

/usr/bin/java \
    -Dapp.engine.loader.selenium.hubUrl=http://localhost:4444/ \
    -Dapp.logging.path="${APP_LOG_DIR}" \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar "${WAR_FILE}"
```

--------------------------------

### Run Asqatasun Webapp with PostgreSQL

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_CLI

Launch the Asqatasun web application using Java, configured for PostgreSQL. Ensure the WAR file path and database connection details are correctly set. Selenium hub URL and application logging path are also configured.

```bash
ASQATASUN_RELEASE="6.0.0-SNAPSHOT"
DB_PORT="5432"
DB_HOST="localhost"
DB_DRIVER="postgresql"
DB_DATABASE="asqatasun"
DB_USER="asqatasunDatabaseUserLogin"
DB_PASSWORD="asqatasunDatabaseUserP4ssword"
APP_LOG_DIR="${HOME}/var/log/asqatasun/webapp"
WAR_FILE="${HOME}/Asqatasun/web-app/asqatasun-web-app/target/asqatasun-web-app-${ASQATASUN_RELEASE}.war"

/usr/bin/java \
    -Dapp.engine.loader.selenium.hubUrl=http://localhost:4444/ \
    -Dapp.logging.path="${APP_LOG_DIR}" \
    -Djdbc.url="jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}" \
    -Djdbc.user="${DB_USER}" \
    -Djdbc.password="${DB_PASSWORD}" \
    -jar "${WAR_FILE}"
```

--------------------------------

### Deploy Asqatasun Application

Source: https://doc.asqatasun.org/v6/Developer/Referential_creator/Create_a_referential

Navigate to the extracted TGZ folder, set the TOMCAT_HOST_PATH environment variable in deploy.sh, and then execute the deployment script. Ensure the path points to your Tomcat web-app folder.

```bash
cd tgz-extract-folder/ 
vi deploy.sh ## Set $TOMCAT_HOST_PATH with your tomcat asqatasun web-app folder path.
./deploy.sh
```

--------------------------------

### Configure MariaDB Server for Asqatasun

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Pre-requisites

Creates a MariaDB configuration file to set character set, timezone, and other performance-related parameters for Asqatasun. Ensure this file is loaded after default configurations.

```bash
CNF_FILE="/etc/mysql/mariadb.conf.d/90-asqatasun.cnf"
touch "${CNF_FILE}"
cat >"${CNF_FILE}" <<EOF
[client]
default-character-set=utf8mb4

[mysql]
default-character-set=utf8mb4

[mysqld]
default_time_zone=Europe/Paris
collation-server=utf8mb4_general_ci
init-connect='SET NAMES utf8mb4'
character-set-server=utf8mb4
max_allowed_packet=64M
innodb_file_per_table
innodb_log_file_size=1G
innodb_buffer_pool_size=4G
# CAUTION we must respect the ratio:
# innodb_buffer_pool_size = 4 x innodb_log_file_size
EOF
```

--------------------------------

### Build and Validate Project

Source: https://doc.asqatasun.org/v6/Developer/Code-base/Dependencies

Command to build the project and run tests after upgrading a dependency.

```bash
./mvnw $MAVEN_CLI_OPTS validate clean install -Dmaven.test.skip=true && ./mvnw $MAVEN_CLI_OPTS test
```

--------------------------------

### GitLab CI Deployment Configuration

Source: https://doc.asqatasun.org/v6/Developer/Documentation/Deploy

Configuration for the deployment pipeline, including SSH agent setup, key management, and rsync execution.

```yaml
---
.deploy_common:
  image: debian:buster
  stage: deploy
  before_script:
    ##
    ## Install ssh-agent if not already installed, it is required by Docker.
    ## (change apt-get to yum if you use an RPM-based image)
    ##
    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

    ##
    ## Run ssh-agent (inside the build environment)
    ##
    - eval $(ssh-agent -s)

    ##
    ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
    ## We're using tr to fix line endings which makes ed25519 keys work
    ## without extra base64 encoding.
    ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
    ##
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -

    ##
    ## Create the SSH directory and give it the right permissions
    ##
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh

    ##
    ## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the
    ## following two lines.
    ##
    - echo "$SSH_KNOWN_HOSTS" >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts

    ##
    ## You can optionally disable host key checking. Be aware that by adding that
    ## you are susceptible to man-in-the-middle attacks.
    ## WARNING: Use this only with the Docker executor, if you use it with shell
    ## you will overwrite your user's SSH config.
    ##
    - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config'

    ## Rsync install in runner
    - apt-get update -y && apt-get install rsync -y

  script:
    - rsync -avz --delete  ./public/ "$DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH"
```

```yaml
---
stages:
  - deploy

include:
  - local: /.gitlab/ci/deploy.yml

deploy_master:
  extends: .deploy_common
  only:
    refs:
      - master

deploy_manual:
  extends: .deploy_common
  when: manual
```

--------------------------------

### Get test results for a specific audit

Source: https://doc.asqatasun.org/v6/Developer/API/Using

Retrieves all test results associated with a specific audit ID. Authentication is required using Basic Auth.

```APIDOC
## GET /api/v0/audit/{auditId}/tests

### Description
Retrieve all test results associated with a specific audit ID.

### Method
GET

### Endpoint
/api/v0/audit/{auditId}/tests

### Parameters
#### Path Parameters
- **auditId** (long) - Required - The ID of the audit.

#### Query Parameters
- **Accept** (string) - Required - Application JSON

### Request Example
```bash
curl -u your_username:your_password -H "Accept: application/json" https://asqatasun_instance_server_url/api/v0/audit/42/tests
```

### Response
#### Success Response (200)
- **id** (long) - The unique identifier for the audit.
- **subject** (object) - Information about the audited subject.
  - **id** (long) - The unique identifier for the subject.
  - **type** (string) - The type of the subject (e.g., "PAGE").
  - **url** (string) - The URL of the audited subject.
  - **nbOfPages** (integer) - The number of pages audited.
  - **grade** (string) - The overall grade of the audit (e.g., "F").
  - **mark** (number) - The numerical mark obtained in the audit.
  - **nbOfFailureOccurrences** (integer) - The number of failure occurrences.
  - **repartitionBySolutionType** (array) - Distribution of results by solution type.
    - **type** (string) - The type of solution (e.g., "PASSED", "FAILED").
    - **number** (integer) - The count for that solution type.
- **status** (string) - The completion status of the audit (e.g., "COMPLETED").
- **date** (string) - The date and time the audit was performed (ISO 8601 format).
- **tags** (array) - An array of tags associated with the audit.
- **referential** (string) - The referential standard used for the audit (e.g., "RGAA_4_2_1").
- **referentialLevel** (string) - The level of the referential standard.

#### Response Example
```json
{
  "id": 62,
  "subject":{
    "id": 83,
    "type":"PAGE",
    "url":"https://unique_mywebsite.fr/",
    "nbOfPages":1,
    "grade":"F",
    "mark":51.89,
    "nbOfFailureOccurrences":21,
    "repartitionBySolutionType":
    [
      {"type":"PASSED","number":6},
      {"type":"FAILED","number":4},
      {"type":"NEED_MORE_INFO","number":67},
      {"type":"NOT_APPLICABLE","number":41},
      {"type":"NOT_TESTED","number":140}
    ]
  },
  "status":"COMPLETED",
  "date":"2025-08-26T12:30:27.000+00:00",
  "tags":[],
  "referential":"RGAA_4_2_1",
  "referentialLevel":"LEVEL_2"
}
```
```

--------------------------------

### Configure Asqatasun web application

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Generates the YAML configuration file for the web application with database and security settings.

```bash
touch /etc/asqatasun/asqatasun-webapp.yml
chown asqatasun /etc/asqatasun/asqatasun-webapp.yml
chmod 600 /etc/asqatasun/asqatasun-webapp.yml

unset HISTFILE    # Do not keep the following commands in history (credentials in plain text)
DB_DRIVER='mysql'
DB_HOST='localhost'
DB_PORT='3306'
DB_DATABASE='asqatasun'
DB_USER='asqatasunDatabaseUserLogin'
DB_PASSWORD='asqatasunDatabaseUserP4ssword'
WEBAPPURL='https://asqatasun.example.org'       # without trailing slash
ASQA_VERSION='6.0.0-alpha.1'

cat >/etc/asqatasun/asqatasun-webapp.yml <<EOF
---
jdbc:
  url: "jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
  user: "${DB_USER}"
  password: "${DB_PASSWORD}"
app:
  version: "${ASQA_VERSION}"
  emailSender:
    smtp:
      from: "admin@asqatasun.org"
  webapp:
    security:
      owasp:
        esapiPropertyValue: "/etc/asqatasun"
        tokenDurationValidity: 3600
    ui:
      config:
        authorizedPageSize: "10,25,50,100,250,1000,-1"
        authorizedRefForCriterionViewList: "Aw22,Rgaa30,Rgaa40"
        authorizedScopeForCriterionList: "DOMAIN,SCENARIO"
        authorizedScopeForPageList: "DOMAIN,SCENARIO"
        authorizedScopeForSynthesis: "DOMAIN,SCENARIO"
        authorizedScopeForTrend: "DOMAIN,SCENARIO"
        defaultReferential: "Rgaa40"
        forbiddenUserListForSettings: "guest"
        nbOfFailedPages: 10
        nbOfFailedTest: 5
        referentialWithModifiableTestWeight: "SEO,Aw22"
        userExclusionListForEmail: "guest"
        webAppUrl: "${WEBAPPURL}"
        contrastfinderServiceUrl: "https://app.contrast-finder.org"
        forgottenPassword:
          excludeUserList: "guest"
        orchestrator:
          ayncDelay: 30000
          emailSentToUserExclusionList: "guest"
          krashReportMailList: "support@asqatasun.org"
          enableKrashReport: true
EOF
```

--------------------------------

### Configure Mysql Server for Asqatasun

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Pre-requisites

Creates a Mysql configuration file to set character set, timezone, and other performance-related parameters for Asqatasun. Ensure this file is loaded after default configurations.

```bash
cat >/etc/mysql/mysql.conf.d/z_asqatasun.cnf <<EOF
[client]
default-character-set=utf8mb4

[mysql]
default-character-set=utf8mb4

[mysqld]
default_time_zone=Europe/Paris
collation-server=utf8mb4_general_ci
init-connect='SET NAMES utf8mb4'
character-set-server=utf8mb4
max_allowed_packet=64M
innodb_file_per_table
innodb_log_file_size=1G
innodb_buffer_pool_size=4G
# CAUTION we must respect the ratio:
# innodb_buffer_pool_size = 4 x innodb_log_file_size
EOF
```

--------------------------------

### Create Asqatasun Server Configuration

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Creates and configures the Asqatasun server YAML configuration file. Ensure database credentials are correct for your instance. The HISTFILE variable is unset to prevent credentials from being stored in shell history.

```bash
touch /etc/asqatasun/asqatasun-server.yml
chown asqatasun /etc/asqatasun/asqatasun-server.yml
chmod 600 /etc/asqatasun/asqatasun-server.yml

unset HISTFILE    # Do not keep the following commands in history (credentials in plain text)
DB_DRIVER='mysql'
DB_HOST='localhost'
DB_PORT='3306'
DB_DATABASE='asqatasun'
DB_USER='asqatasunDatabaseUserLogin'
DB_PASSWORD='asqatasunDatabaseUserP4ssword'
ASQA_VERSION='6.0.0-alpha.1'

cat >/etc/asqatasun/asqatasun-server.yml <<EOF
---
jdbc:
  url: "jdbc:${DB_DRIVER}://${DB_HOST}:${DB_PORT}/${DB_DATABASE}"
  user: "${DB_USER}"
  password: "${DB_PASSWORD}"
app:
  version: "${ASQA_VERSION}"
  engine:
    maxConcurrentSize:
      page: 5
EOF
```

--------------------------------

### Display Firefox Browser Window via VM Options

Source: https://doc.asqatasun.org/v6/Developer/Build/Debug

Set this VM option to `false` to make the Firefox browser window visible when Asqatasun runs in IntelliJ. This helps in understanding scenario failures by observing the browser's state.

```java
-Dapp.engine.loader.selenium.headless=false
```

--------------------------------

### Create symbolic link for public assets

Source: https://doc.asqatasun.org/v6/Developer/Build/Build_IntelliJ

Run this command from the project root to link the public directory required by the web application.

```bash
cd web-app/asqatasun-web-app/src/main/resources
ln -s ../webapp/public public
```

--------------------------------

### SSH Access and Key Generation Commands

Source: https://doc.asqatasun.org/v6/Developer/Documentation/Deploy

Commands to connect to the hosting server, generate an SSH key pair, and authorize the public key.

```bash
ssh deploy-user@xxxx.ftp.infomaniak.com
```

```bash
ssh-keygen -t ed25519
```

```bash
cd ~/.ssh/ && cat ed25519.pub >>authorized_keys
```

--------------------------------

### Export Asqatasun Database

Source: https://doc.asqatasun.org/v6/Operator/Installation/Upgrade/4.0.3_to_4.1.0

Use mysqldump to create a backup of the existing Asqatasun database before performing the upgrade.

```bash
mysqldump \
  --user=asqatasun \
  -p \
  --databases asqatasun \
  --result-file=SAVE_DB_asqatasun.sql
```

--------------------------------

### Run full E2E test suite

Source: https://doc.asqatasun.org/v6/Developer/Test/E2E-testing-webapp

Executes the complete E2E test suite using Maven with required environment configuration parameters.

```bash
cd testing-tools/E2E-testing-webapp
mvn test \
    -Dadmin.user=admin@asqatasun.org \
    -Dadmin.password=myAsqaPassword \
    -Dhost.location=http://localhost:8080/ \
    -Dfirefox.path=/opt/firefox/firefox \
    -Dgecko.path=/opt/geckodriver
```

--------------------------------

### Run Selenium Grid with Firefox Docker Image

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Launches a Selenium Grid with Firefox using a Docker image. This is the recommended method for browser automation.

```bash
docker run \
  --name selenium-ff \
  -p 4444:4444 \
  -p 7900:7900 \
  --shm-size="2g" \
  -d \
  selenium/standalone-firefox:122.0-geckodriver-0.34.0-grid-4.17.0-20240123
```

--------------------------------

### Create Asqatasun Server Systemd Unit

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Creates the systemd service unit file for the Asqatasun server. This includes specifying the Java executable, configuration file location, webdriver paths, logging path, and working directory.

```bash
cat >/etc/systemd/system/asqatasun-server.service <<EOF
[Unit]
Description=asqatasun-server
After=syslog.target

[Service]
User=asqatasun
ExecStart=/usr/bin/java                                                     \
    -Dspring.config.location=file:///etc/asqatasun/asqatasun-server.yml     \
    -Dwebdriver.firefox.bin=/opt/firefox/firefox                            \
    -Dwebdriver.gecko.driver=/opt/geckodriver                               \
    -Dapp.logging.path=/var/log/asqatasun/server/                           \
    -jar asqatasun-server.jar
SuccessExitStatus=143
WorkingDirectory=/home/asqatasun

[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### Browse Asqatasun Logs with systemd

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Start-Asqatasun

Access Asqatasun application logs through the systemd journal. The -f option continuously streams new log entries.

```bash
journalctl -u asqatasun-webapp.service
journalctl -u asqatasun-server.service
```

--------------------------------

### Create symbolic links for binaries

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Creates symlinks to simplify binary execution and version management.

```bash
cd "/home/asqatasun/"
WEBAPP_STUB="asqatasun-web-app"
API_STUB="asqatasun-server"
ln -s "${WEBAPP_STUB}-${ASQA_VERSION}.war" "${WEBAPP_STUB}.war"
ln -s "${API_STUB}-${ASQA_VERSION}.jar" "${API_STUB}.jar"
```

--------------------------------

### Clone Asqatasun Source Code

Source: https://doc.asqatasun.org/v6/Developer/Build/Pre-requisites

Clones the Asqatasun repository from GitHub and navigates into the project directory.

```bash
git clone https://github.com/Asqatasun/Asqatasun.git
cd Asqatasun
```

--------------------------------

### Create systemd unit for web application

Source: https://doc.asqatasun.org/v6/Operator/Installation/Regular/Installation

Defines the systemd service unit to manage the Asqatasun web application lifecycle.

```bash
cat >/etc/systemd/system/asqatasun-webapp.service <<EOF
[Unit]
Description=asqatasun-webapp
After=syslog.target

[Service]
User=asqatasun
ExecStart=/usr/bin/java                                                     \
    -Dspring.config.location=file:///etc/asqatasun/asqatasun-webapp.yml     \
    -Dwebdriver.firefox.bin=/opt/firefox/firefox                            \
    -Dwebdriver.gecko.driver=/opt/geckodriver                               \
    -Dapp.logging.path=/var/log/asqatasun/webapp/                           \
    -jar asqatasun-web-app.war
SuccessExitStatus=143
WorkingDirectory=/home/asqatasun

[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### Define release and development version variables

Source: https://doc.asqatasun.org/v6/Developer/Release

Set the environment variables for the current release version and the subsequent development version.

```bash
RELEASE_VERSION="6.0.0-alpha.1"
DEV_VERSION="6.0.0-SNAPSHOT"
```

--------------------------------

### Run Audit via cURL

Source: https://doc.asqatasun.org/v6/User/Asqatasun-Usage

Use this cURL command to initiate an audit of a given URL. Ensure ASQA_USER, ASQA_PASSWORD, and API_PREFIX_URL are correctly set.

```bash
ASQA_USER="admin%40asqatasun.org"                                                                                                                    
ASQA_PASSWORD="myAsqaPassword"
API_PREFIX_URL="http://${ASQA_USER}:${ASQA_PASSWORD}@localhost:8080"
API_URL="${API_PREFIX_URL}/api/v0/audit/page/run"

PROJECT_ID="1"
REFERENTIAL="RGAA_4_0"
LEVEL="AA"
URL_TO_AUDIT="https://www.wikidata.org/"

curl -X POST \
     "${API_URL}"                                               \
     -H  "accept: */*"                                          \
     -H  "Content-Type: application/json"                       \
     -d "{\n            \"urls\": [    \"${URL_TO_AUDIT}\"  ],              \
                           \"referential\": \"${REFERENTIAL}\", \n                           \"level\": \"${LEVEL}\",             \
                           \"contractId\": ${PROJECT_ID},       \
                           \"tags\": []                         \n         }"
```

--------------------------------

### Build Referential Creator Maven Plugin

Source: https://doc.asqatasun.org/v6/Developer/Referential_creator/Create_a_referential

Navigate to the referential-creator-maven-plugin directory and build the plugin using Maven. This step is required before generating referentials.

```bash
cd Asqatasun/rules/referential-creator-maven-plugin/
mvn clean install
```