### Start Mercator Application

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Starts the Mercator application using PHP's built-in server. Optionally, it can be configured to accept connections from other servers.

```bash
php artisan serve
```

```bash
php artisan serve --host 0.0.0.0 --port 8000
```

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

### Import Test Database (Optional)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Imports a test database into Mercator for development or testing purposes. This step is optional and not required for production setups.

```bash
sudo mysql mercator < database/data/mercator_data_en.sql
```

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

### Install MySQL Server

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs MySQL server, which is used as the database backend for Mercator. MySQL stores all application data including user information and configurations.

```bash
sudo apt install mysql-server
```

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

### Database Connection Settings (.env example)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Example configuration within the .env file for connecting to a MySQL database. Includes host, port, database name, username, and password.

```env
DB_CONNECTION=mysql
#DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=3306
# Comment DB_PORT for pgsql
DB_DATABASE=mercator
DB_USERNAME=mercator_user
DB_PASSWORD=s3cr3t
```

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

### Configure Email Settings (.env example)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Example configuration for sending notification emails via an SMTP server. Includes settings for host, port, authentication, security, and credentials.

```env
MAIL_HOST='smtp.localhost'
MAIL_PORT=2525
MAIL_AUTH=true
MAIL_SMTP_SECURE='ssl'
MAIL_SMTP_AUTO_TLS=false
MAIL_USERNAME=
MAIL_PASSWORD=
```

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

### Configure Environment File (.env)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Copies the example environment file to .env and provides an example configuration for database connection settings within the .env file. Adjust these values as needed.

```bash
cd /var/www/mercator
cp .env.example .env
```

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

### Create MySQL Database and User

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Creates a MySQL database named 'mercator' and a user 'mercator_user' with all necessary privileges. This setup is essential for Mercator's database operations.

```sql
CREATE DATABASE mercator CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE USER 'mercator_user'@'localhost' IDENTIFIED BY 's3cr3t';
GRANT ALL PRIVILEGES ON mercator.* TO 'mercator_user'@'localhost';
GRANT PROCESS ON *.* TO 'mercator_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

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

### Install Apache2, GIT, Graphviz, and Composer

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs Apache2 web server, GIT version control, Graphviz for diagram generation, and Composer for PHP dependency management. These tools are required for Mercator's operation.

```bash
sudo apt install apache2 git graphviz composer
```

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

### Start Development Server (Artisan)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Starts the built-in PHP development server for the Mercator application. It can be configured to listen on specific hosts and ports for external access.

```bash
php artisan serve
# Or for external access:
php artisan serve --host 0.0.0.0 --port 8000
```

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

### Create Project Directory and Clone Mercator

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Creates a directory for the Mercator project in /var/www and clones the project from GitHub. Sets the correct ownership for the project directory.

```bash
cd /var/www
sudo mkdir mercator
sudo chown $USER:$GROUP mercator
git clone https://www.github.com/dbarzin/mercator
```

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

### Configure DKIM Email Settings (.env example)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Example configuration for DomainKeys Identified Mail (DKIM) to improve email deliverability and authenticity. Requires paths to private keys and selectors.

```env
MAIL_DKIM_DOMAIN = 'admin.local';
MAIL_DKIM_PRIVATE = '/path/to/private/key';
MAIL_DKIM_SELECTOR = 'default'; // Match your DKIM DNS selector
MAIL_DKIM_PASSPHRASE = '';      // Only if your key has a passphrase
```

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

### Update and Upgrade Ubuntu System

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Updates the package list and upgrades all installed packages to their latest versions. Ensures the system is up-to-date before proceeding with Mercator installation.

```bash
sudo apt update && sudo apt upgrade
```

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

### Install PHP and Required Libraries

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs PHP along with necessary libraries such as zip, curl, mbstring, xml, ldap, soap, xdebug, mysql, and gd. These libraries are essential for Mercator's functionality.

```bash
sudo apt install php-zip php-curl php-mbstring php-xml php-ldap php-soap php-xdebug php-mysql php-gd libapache2-mod-php
```

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

### Database Migration and Seeding

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Executes database migrations to create the necessary tables and seeds the database with initial data, including the first administrator user.

```bash
php artisan migrate --seed
```

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

### Install Composer Packages

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs all PHP dependencies for Mercator using Composer. This step is crucial for ensuring all required libraries and packages are available.

```bash
cd /var/www/mercator
composer install
```

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

### Install and Configure MySQL Server (Linux)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Installs the MySQL server package, verifies the installation, and starts/enables the MySQL service. It then launches the MySQL client to create the database and user.

```bash
sudo dnf install mysql-server
sudo mysql --version

systemctl start mysqld.service
systemctl enable mysqld.service

sudo mysql
```

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

### Install PHP-FPM in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs PHP-FPM package for improved performance with Apache. Requires apt package manager and sudo. Sets up FastCGI manager; dependent on PHP version compatibility.

```bash
sudo apt install php-fpm
```

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

### Configure Apache Basic Setup and Permissions

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Sets up Apache web server with proper file permissions and ownership. Configures SELinux settings and creates virtual host configuration for the Mercator application.

```Shell
# Set proper ownership and permissions for Mercator directory
sudo chown -R apache:apache /var/www/mercator
sudo chmod -R 775 /var/www/mercator/storage

# Check SELinux status
status

# Disable SELinux by editing configuration file
sudo vi /etc/selinux/config

# Change SELINUX=enforcing to SELINUX=disabled
# Restart system after changes
sudo reboot

# Create Apache virtual host configuration
sudo vi /etc/httpd/conf.d/mercator.conf

# Restart Apache service
sudo systemctl restart httpd
```

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

### Setup Laravel Scheduler in Crontab

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Configures the crontab to run Laravel's scheduler every minute. This ensures scheduled tasks, like CPE synchronization, are executed automatically.

```bash
* * * * * cd /var/www/mercator && php artisan schedule:run >> /dev/null 2>&1
```

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

### Create Project Directory and Clone Repository

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Sets up the project's directory structure under /var/www and clones the Mercator project from its GitHub repository. It also ensures the user has the correct ownership.

```bash
cd /var/www
sudo mkdir mercator
sudo chown $USER:$GROUP mercator

git clone https://www.github.com/dbarzin/mercator
```

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

### Install PHP LDAP Extension for LDAP Authentication

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Installs the PHP LDAP extension, which is required for enabling LDAP authentication in Mercator. The Apache server is restarted to apply changes.

```bash
sudo apt-get install php-ldap
sudo systemctl restart apache2
```

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

### Manage Apache Modules and Sites in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Enables Apache modules, disables default site, and enables Mercator site for web serving. Requires Apache2 and sudo access. Restarts Apache to apply configuration changes; ensures rewrite and site enablement.

```bash
sudo a2enmod rewrite
sudo a2dissite 000-default.conf
sudo a2ensite mercator.conf
sudo systemctl restart apache2
```

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

### Configure Apache for PHP-FPM in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Disables incompatible modules and enables PHP-FPM support in Apache. Requires Apache2, PHP-FPM installed, and sudo. Optimizes event-driven processing; specify PHP version accurately.

```bash
sudo a2dismod mpm_prefork phpX.Y
sudo a2enmod proxy_fcgi mpm_event
```

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

### Set Apache Directory Permissions in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Grants www-data group ownership and write permissions to Mercator directory for Apache serving. Requires sudo privileges and Apache installed. Prepares file system for secure web access; limitations apply to system compatibility.

```bash
sudo chown -R www-data:www-data /var/www/mercator
sudo chmod -R 775 /var/www/mercator/storage
```

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

### Enable Apache SSL Module in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Activates Apache's SSL module for HTTPS support. Depends on Apache2 and sudo privileges. Prepares server for secure connections; requires module restart.

```bash
sudo a2enmod ssl
```

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

### Update and Install Core Packages (Linux)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Updates the system's package list and installs essential tools like Httpd, GIT, Graphviz, Vim, and PHP. This is a fundamental step for setting up the server environment.

```bash
sudo dnf update && sudo dnf upgrade
sudo dnf install vim httpd git graphviz php
```

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

### Pull Latest Mercator Sources from Git

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command updates the Mercator project files by pulling the latest changes from the Git repository. Ensure you are in the project's root directory before executing.

```bash
cd /var/www/mercator
git pull
```

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

### Install Composer Dependencies

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Installs all project dependencies defined in the composer.json file using Composer. This command should be run from the project's root directory.

```bash
composer install
```

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

### Migrate Mercator Database Schema

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command runs database migrations for the Mercator application, applying any pending schema changes. This should be run after pulling the latest code.

```bash
php artisan migrate
```

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

### Create Mercator Database and User (MySQL)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

SQL commands to create the 'mercator' database with UTF8 encoding and a dedicated user 'mercator_user' with a password. It grants necessary privileges and flushes them.

```sql
CREATE DATABASE mercator CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE USER 'mercator_user'@'localhost' IDENTIFIED BY 's3cr3t';
GRANT ALL PRIVILEGES ON mercator.* TO 'mercator_user'@'localhost';
GRANT PROCESS ON *.* TO 'mercator_user'@'localhost';

FLUSH PRIVILEGES;
EXIT;
```

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

### Import Test Database (SQL)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Imports an optional SQL file containing test data into the Mercator database. Assumes the SQL file is located in the 'data' directory.

```bash
sudo mysql mercator < data/mercator_data_en.sql
```

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

### Configure CPE Synchronization

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Adds configuration to the .env file for synchronizing CPEs from the NVD. This is optional but recommended for keeping vulnerability data up-to-date.

```dotenv
# NVD CPE 2.0 API endpoint
CPE_API_URL=https://services.nvd.nist.gov/rest/json/cpes/2.0

# (Optional but recommended) NVD API key to benefit from higher request quotas
NVD_API_KEY=
```

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

### Clear Configuration Cache

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Clears the configuration cache to ensure any changes in the .env file or other configurations are immediately effective.

```bash
php artisan config:clear
```

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

### Configure Apache HTTP VirtualHost

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This snippet shows how to set up an Apache VirtualHost for HTTP traffic. It defines the server name, document root, directory permissions, and PHP FastCGI process handler. It also specifies error and access log file locations.

```apache
<VirtualHost *:80>
    ServerName mercator.local
    ServerAdmin admin@example.com

    DocumentRoot /var/www/mercator/public

    <Directory /var/www/mercator>
        AllowOverride All
        Require all granted
    </Directory>

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

    ErrorLog ${APACHE_LOG_DIR}/mercator_error.log
    CustomLog ${APACHE_LOG_DIR}/mercator_access.log combined
</VirtualHost>
```

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

### Install and Configure PHP-FPM

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Installs PHP-FPM and configures Apache to use it via UNIX socket. Provides better performance and compatibility with mpm_event module. Includes installation commands and virtual host configuration.

```Bash
# Install PHP-FPM
sudo dnf install php-fpm

# Enable and start PHP-FPM service
sudo systemctl enable --now php-fpm
```

```XML
<VirtualHost *:80>
    ServerName mercator.local
    ServerAdmin admin@example.com

    DocumentRoot /var/www/mercator/public

    <Directory /var/www/mercator>
        AllowOverride All
        Require all granted
    </Directory>

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

    ErrorLog /var/log/httpd/mercator_error.log
    CustomLog /var/log/httpd/mercator_access.log combined
</VirtualHost>
```

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

### Configure LDAP in .env File

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Adds LDAP configuration to the .env file, enabling LDAP authentication in Mercator. Supports hybrid mode with local database fallback.

```dotenv
LDAP_ENABLED=true
LDAP_FALLBACK_LOCAL=true
LDAP_AUTO_PROVISION=false
```

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

### Install Composer (Linux)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Downloads and installs Composer, the dependency manager for PHP, into the system's PATH for global accessibility. It uses a PHP script to perform the installation.

```bash
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
```

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

### Configure Mercator Testing Environment

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This set of commands sets up the testing environment for Mercator. It copies the production environment file, then modifies the testing environment file to use SQLite in-memory database and sets the application environment to 'testing'.

```bash
cp .env .env.testing

# Then update the database configuration in .env.testing, for example:
APP_ENV=testing
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=sqlite
DB_DATABASE=:memory:
```

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

### Install PHP Libraries (Linux)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Installs a comprehensive set of common PHP extensions required for web application development, including JSON, MySQL, GD, Zip, Curl, Mbstring, XML, LDAP, and SOAP.

```bash
sudo dnf install php-json php-dbg php-mysqlnd php-gd php-zip php-mbstring php-xml php-ldap php-soap
```

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

### Generate Application Key

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Generates a unique application key used for encryption and other security features in Mercator. This key is essential for secure operations.

```bash
php artisan key:generate
```

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

### Configure Apache HTTP Virtual Host in XML

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Defines Apache virtual host for Mercator application on port 80. Depends on Apache web server and correct document root path. Serves static and dynamic content; requires AllowOverride for .htaccess handling.

```xml
<VirtualHost *:80>
        ServerName mercator.local
        ServerAdmin admin@example.com
        DocumentRoot /var/www/mercator/public
<Directory /var/www/mercator>
        AllowOverride All
        </Directory>
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        </VirtualHost>
```

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

### Configure Apache HTTP Virtual Host

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Creates basic HTTP virtual host configuration for Mercator application. Defines document root, server settings, and logging configuration for HTTP traffic.

```XML
<VirtualHost *:80>
     ServerName mercator.local
     ServerAdmin admin@example.com
     DocumentRoot /var/www/mercator/public
     <Directory /var/www/mercator>
         AllowOverride All
     </Directory>
     ErrorLog /var/log/httpd/mercator_error.log
     CustomLog /var/log/httpd/mercator_access.log combined
</VirtualHost>
```

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

### Configure Mail Settings in .env

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Configures SMTP settings in the .env file for sending notification emails from Mercator. Includes optional DKIM configuration for email security.

```dotenv
MAIL_HOST='smtp.localhost'
MAIL_PORT=2525
MAIL_AUTH=true
MAIL_SMTP_SECURE='ssl'
MAIL_SMTP_AUTO_TLS=false
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_DKIM_DOMAIN = 'admin.local';
MAIL_DKIM_PRIVATE = '/path/to/private/key';
MAIL_DKIM_SELECTOR = 'default';
MAIL_DKIM_PASSPHRASE = '';
```

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

### Import CPE Database (SQL)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Decompresses a gzipped SQL file and imports the CPE (Common Platform Enumeration) database into the Mercator database. This is a crucial step for populating specific data.

```bash
gzip -d mercator_cpe.sql.gz
sudo mysql mercator < mercator_cpe.sql
```

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

### Install Laravel Passport (Artisan)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Installs Laravel Passport, a package for handling OAuth2 authentication for APIs. This command sets up the necessary components for API authentication.

```bash
php artisan passport:install
```

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

### Backup Mercator Database with mysqldump

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command backs up the Mercator MySQL database to a SQL file named 'mercator_backup.sql'. This is a crucial step before performing application upgrades or major changes.

```bash
mysqldump mercator > mercator_backup.sql
```

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

### Configure Apache HTTPS Virtual Host in XML

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Sets up secure Apache virtual host for Mercator on port 443 with SSL. Requires SSL certificates and Apache SSL module enabled. Enforces encrypted connections; depends on certificate files being valid.

```xml
<VirtualHost *:443>
        ServerName carto.XXXXXXXX
        ServerAdmin
        DocumentRoot /var/www/mercator/public
        SSLEngine on
        SSLProtocol all -SSLv2 -SSLv3
        SSLCipherSuite HIGH:3DES:!aNULL:!MD5:!SEED:!IDEA
        SSLCertificateFile /etc/apache2/certs/certs/carto.XXXXX.crt
        SSLCertificateKeyFile /etc/apache2/certs/private/private.key
        SSLCertificateChainFile /etc/apache2/certs/certs/XXXXXCA.crt
<Directory /var/www/mercator/public>
        AllowOverride All
        </Directory>
        ErrorLog ${APACHE_LOG_DIR}/mercator_error.log
        CustomLog ${APACHE_LOG_DIR}/mercator_access.log combined
        </VirtualHost>
```

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

### Execute Mercator Test Suite with Pest

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

These commands execute the non-regression test suite for the Mercator application using Pest. You can run all tests, stop on the first failure, or target specific test files or groups.

```bash
# Run all tests
php artisan test

# or directly
./vendor/bin/pest

# Stop on first failure
./vendor/bin/pest --stop-on-failure

# Run a specific test file or directory
./vendor/bin/pest tests/Feature/Api

# Use groups/tags
./vendor/bin/pest --group=api
```

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

### Configure Keycloak Integration in dotenv

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Enables Keycloak for OAuth-based authentication and user provisioning in Mercator. Requires Keycloak server details and client credentials. Redirects login flows to Keycloak and auto-provisions users; limitations include dependency on external Keycloak server availability.

```dotenv
KEYCLOAK = enable
KEYCLOAK_CLIENT_ID= # Client Name (on Keycloak)
KEYCLOAK_CLIENT_SECRET=  # Client Secret
KEYCLOAK_REDIRECT_URI=<Mercator IP Address>/login/keycloak/callback
KEYCLOAK_BASE_URL=<KeyCloak IP Address>
KEYCLOAK_REALM=   # RealM Name
KEYCLOAK_AUTO_PROVISIONNING= # enable/disable the automatic creation of users (possibles values: true/false. defaults to 'true')
KEYCLOAK_BTN_LABEL= # set the Keycloak login button label (defaults to 'Keycloak')
```

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

### Configure and Install PHP 8.2 (Linux)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Resets the PHP module stream, enables PHP version 8.2, and installs it. This ensures the correct PHP version is available for the project.

```bash
sudo dnf module reset php
sudo dnf module enable php:8.2
sudo dnf install php
```

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

### Configure LDAP Server Connection in dotenv

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Sets up LDAP connection parameters for user authentication, supporting various servers like OpenLDAP or Active Directory. Requires server credentials and certificate details for TLS or SSL. Processes user login inputs and outputs authentication success or failure, with limitations on non-LDAP attribute handling.

```dotenv
LDAP_HOST=ldap.example.org
LDAP_PORT=389                     # 389 (StartTLS) or 636 (LDAPS)
LDAP_BASE_DN=dc=example,dc=org
LDAP_USERNAME=cn=admin,dc=example,dc=org   # Service account used for searches
LDAP_PASSWORD=********
LDAP_TLS=true                     # StartTLS (recommended when using port 389)
LDAP_SSL=false                    # true if you use ldaps:// on port 636
LDAP_TIMEOUT=5                    # (optional)
# Candidate attributes to identify the username entered in the form
# Order matters: the first match wins.
# OpenLDAP: uid, cn, mail ; AD: sAMAccountName, userPrincipalName, mail
LDAP_LOGIN_ATTRIBUTES=uid,cn,mail,sAMAccountName,userPrincipalName
# User must be member of this LDAP group
LDAP_GROUP=Mercator
```

```dotenv
LDAP_TLS=true
LDAP_SSL=false
LDAP_LOGIN_ATTRIBUTES=uid,cn,mail
LDAP_GROUP=Merator
```

```dotenv
LDAP_TLS=true
LDAP_SSL=false
LDAP_LOGIN_ATTRIBUTES=sAMAccountName,userPrincipalName,mail,cn
LDAP_USERNAME=EXAMPLE\svc_ldap   # or the full DN of the service account
```

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

### Configure LDAP Environment Variables

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Configures LDAP connection parameters for Active Directory integration. Includes connection settings, authentication credentials, and access restrictions for LDAP queries.

```Shell
# LDAP Configuration in .env file
# Several possible types: AD, OpenLDAP, FreeIPA, DirectoryServer
LDAP_TYPE="AD"
# If true, LDAP actions will be written to the application's default log file
LDAP_LOGGING=true
LDAP_CONNECTION=default
LDAP_HOST=127.0.0.1
# Identifiers of the user who will connect to the LDAP in order to perform queries
LDAP_USERNAME="cn=user,dc=local,dc=com"
LDAP_PASSWORD=secret
LDAP_PORT=389
LDAP_BASE_DN="dc=local,dc=com"
LDAP_TIMEOUT=5
LDAP_SSL=false
LDAP_TLS=false
# Allows you to restrict access to a tree structure
LDAP_SCOPE="ou=Accounting,ou=Groups,dc=planetexpress,dc=com"
# Allows you to restrict access to groups
LDAP_GROUPS="Delivering,Help Desk"
```

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

### Deploy Mercator with Docker

Source: https://context7.com/dbarzin/mercator/llms.txt

Instructions for deploying Mercator using Docker. Includes commands for creating a persistent SQLite database, running a development instance with demo data, and deploying a production instance with MySQL.

```bash
# Create persistent database file
touch ./mercator_db.sqlite
chmod a+w ./mercator_db.sqlite

# Run with demo data
docker run -it --rm \
  -e APP_ENV=development \
  -e USE_DEMO_DATA=1 \
  -p 8080:8080 \
  -v $PWD/mercator_db.sqlite:/var/www/mercator/sql/db.sqlite \
  --name mercator \
  ghcr.io/dbarzin/mercator:latest

# Access at http://127.0.0.1:8080
# Default credentials: admin@admin.com / password
```

```bash
# Production deployment with MySQL
docker run -d \
  -e DB_CONNECTION=mysql \
  -e DB_HOST=mysql.example.com \
  -e DB_PORT=3306 \
  -e DB_DATABASE=mercator \
  -e DB_USERNAME=mercator_user \
  -e DB_PASSWORD=secure_password \
  -e APP_URL=https://mercator.company.com \
  -p 8080:8080 \
  --name mercator-prod \
  ghcr.io/dbarzin/mercator:latest
```

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

### Clear Laravel Application Cache in Bash

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Clears Laravel configuration and optimization caches to apply .env changes. Depends on Laravel Artisan CLI and PHP installed on the system. Takes no inputs and outputs confirmation of cache clearance, with no limitations on standalone execution.

```bash
php artisan config:clear
php artisan optimize:clear
```

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

### Run Database Migrations and Seeders (Artisan)

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Executes Laravel database migrations and seeds the database with initial data, including the creation of an admin user. Also generates the application key and clears configuration cache.

```bash
php artisan migrate --seed
php artisan key:generate
php artisan config:clear
```

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

### Clear Mercator Application Caches

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command clears the configuration and view caches for the Mercator application. It's recommended after updates or configuration changes.

```bash
php artisan config:clear && php artisan view:clear
```

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

### Generate Mercator Test Coverage Report

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command generates a code coverage report for the Mercator application's tests using Pest and Xdebug. Ensure XDEBUG_MODE is set to 'coverage'.

```bash
XDEBUG_MODE=coverage ./vendor/bin/pest --coverage
```

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

### PowerShell Integration Example

Source: https://context7.com/dbarzin/mercator/llms.txt

Demonstrates authentication and querying of logical servers using PowerShell and the Mercator API. This script shows how to authenticate via POST request, then retrieve and format data with `Invoke-RestMethod`.

```powershell
# Authenticate
$loginUri = "http://127.0.0.1:8000/api/login"
$loginBody = @{
    login = "admin@admin.com"
    password = "password"
}

$loginResponse = Invoke-RestMethod -Uri $loginUri -Method Post -Body $loginBody
$token = $loginResponse.access_token

# Get all logical servers
$headers = @{
    'Authorization' = "Bearer $token"
    'Accept' = 'application/json'
}

$servers = Invoke-RestMethod -Uri "http://127.0.0.1:8000/api/logical-servers" `
    -Method Get -Headers $headers

$servers | Format-Table id, name, operating_system, environment, address_ip
```

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

### Create Physical Infrastructure (Python)

Source: https://context7.com/dbarzin/mercator/llms.txt

Demonstrates creating physical infrastructure components such as sites, buildings, bays/racks and physical servers using the Mercator API via Python.  Requires authentication token and illustrates nested resource creation where a server relies on other resources having been created first.

```python
import requests

base_url = "http://127.0.0.1:8000/api"
headers = {'Authorization': f'Bearer {token}'}

# Create site
site = requests.post(f"{base_url}/sites", headers=headers, data={ 
    'name': 'Headquarters',
    'description': 'Main office building'
}).json()

# Create building
building = requests.post(f"{base_url}/buildings", headers=headers, data={ 
    'name': 'Server Room A',
    'description': 'Primary data center',
    'site_id': site['id'],
    'camera': 1,
    'badge': 1
}).json()

# Create bay/rack
bay = requests.post(f"{base_url}/bays", headers=headers, data={ 
    'name': 'Rack 1',
    'description': 'Production servers rack',
    'room_id': building['id']
}).json()

# Create physical server
server = requests.post(f"{base_url}/physical-servers", headers=headers, data={ 
    'name': 'PROD-SRV-01',
    'description': 'Dell PowerEdge R740',
    'type': 'Rack Server',
    'responsible': 'Infrastructure Team',
    'configuration': '2x Intel Xeon, 256GB RAM, 4TB SSD RAID10',
    'site_id': site['id'],
    'building_id': building['id'],
    'bay_id': bay['id']
}).json()

print(f"Created infrastructure: Site {site['id']} -> Building {building['id']} -> Bay {bay['id']} -> Server {server['id']}")
```

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

### Force HTTPS Redirection in dotenv

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

Sets application environment to production to enforce HTTPS redirects in Mercator. Requires Laravel framework and .env file. Modifies response headers for security; limited to production mode.

```dotenv
APP_ENV=production
```

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

### Configure Apache HTTPS Virtual Host

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.RedHat.md

Sets up secure HTTPS virtual host with SSL/TLS configuration. Includes certificate paths, SSL protocol settings, and cipher suite configuration for secure connections.

```XML
<VirtualHost *:443>
     ServerName map.XXXXXXXX
     ServerAdmin
     DocumentRoot /var/www/mercator/public
     SSLEngine on
     SSLProtocol all -SSLv2 -SSLv3
     SSLCipherSuite HIGH:3DES:!aNULL:!MD5:!SEED:!IDEA
     SSLCertificateFile /etc/apache2/certs/certs/carto.XXXXX.crt
     SSLCertificateKeyFile /etc/apache2/certs/private/private.key
     SSLCertificateChainFile /etc/apache2/certs/certs/XXXXXCA.crt
     <Directory /var/www/mercator/public>
         AllowOverride All
     </Directory>
     ErrorLog /var/log/httpd/mercator_error.log
     CustomLog /var/log/httpd/mercator_access.log combined
</VirtualHost>

# Environment configuration for HTTPS enforcement
APP_ENV=production
```

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

### Manage Logical Servers with Bash

Source: https://github.com/dbarzin/mercator/blob/master/docs/api.md

This Bash script demonstrates logging in to obtain a token, retrieving a logical server object by ID, updating its operating system field, and verifying the update via API calls. It depends on curl and jq being available in the environment, with inputs like login credentials and object ID. Outputs include the retrieved and updated JSON responses. Note that it assumes the API responds correctly and credentials are valid; errors are not handled beyond default curl behaviors.

```bash
#!/usr/bin/bash

API_URL=http://127.0.0.1:8000/api

# valid login and password

data='{"login":"admin@admin.com","password":"password"}'

# Get a token after correct login

TOKEN=$(curl -s -d ${data} -H "Content-Type: application/json" ${API_URL}/login | jq -r .access_token)

# Récupération de l'objet

OBJECT_ID=10

RESPONSE=$(curl -s -X GET "${API_URL}/logical-servers/${OBJECT_ID}" \
 -H "Authorization: Bearer ${TOKEN}" \
 -H "Accept: application/json")

echo "Objet récupéré: ${RESPONSE}"

# Mise à jour d'une valeur avec une requête PUT

RESPONSE=$(echo "$RESPONSE" | jq -c '.data')
RESPONSE=$(echo "$RESPONSE" | jq -r '.operating_system="Linux"')

echo "Objet modifié: ${RESPONSE}"

curl -s -X PUT "${API_URL}/logical-servers/${OBJECT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "cache-control: no-cache" \
  -d "$RESPONSE"

# Vérification de la mise à jour

UPDATED_OBJECT=$(curl -s -X GET "${API_URL}/logical-servers/${OBJECT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json")

echo "Objet mis à jour: ${UPDATED_OBJECT}"
```

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

### Manage Workflows with Processes and Activities (Bash)

Source: https://context7.com/dbarzin/mercator/llms.txt

Shows how to create a macro process, a process, and an activity using the Mercator API via Bash.  Utilizes `curl` to make POST requests, including JSON data, to create and link workflows. Demonstrates setting attributes and linking entities and applications.

```bash
curl -X POST "http://127.0.0.1:8000/api/macro-processuses" 
  -H "Authorization: Bearer ${TOKEN}" 
  -d "name=Order Management" 
  -d "description=End-to-end order processing workflow" 
  -d "security_need_c=2" 
  -d "security_need_i=3" 
  -d "security_need_a=2"

MACRO_ID=1

curl -X POST "http://127.0.0.1:8000/api/processes" 
  -H "Authorization: Bearer ${TOKEN}" 
  -d "identifier=Order Fulfillment" 
  -d "description=Process customer orders from receipt to delivery" 
  -d "owner=Operations Manager" 
  -d "macroprocess_id=${MACRO_ID}" 
  -d "entities[]=1" 
  -d "entities[]=3" 
  -d "applications[]=5"

PROCESS_ID=10

curl -X POST "http://127.0.0.1:8000/api/activities" 
  -H "Authorization: Bearer ${TOKEN}" 
  -d "name=Order Validation" 
  -d "description=Validate order details and payment" 
  -d "processes[]=10"
```

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

### Reset Administrator Password with MySQL and PHP

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This command resets the administrator password for the Mercator application in a MySQL database. It uses PHP's password_hash function to securely generate a bcrypt hash for the new password and updates the user with ID 1 in the 'users' table.

```bash
mysql mercator -e "update users set password=$(php -r \"echo password_hash('n3w-p4sSw0rD.', PASSWORD_BCRYPT, ['cost' => 10]);\") where id=1;"
```

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

### Configure Apache HTTPS VirtualHost

Source: https://github.com/dbarzin/mercator/blob/master/INSTALL.md

This snippet configures an Apache VirtualHost for HTTPS traffic, including SSL settings. It specifies the server name, document root, SSL engine, protocols, ciphers, certificate paths, directory permissions, and PHP FastCGI handler. Error and access logs are also defined.

```apache
<VirtualHost *:443>
    ServerName carto.example.com
    ServerAdmin admin@example.com

    DocumentRoot /var/www/mercator/public

    SSLEngine on
    SSLProtocol all -SSLv2 -SSLv3
    SSLCipherSuite HIGH:!aNULL:!MD5

    SSLCertificateFile /etc/apache2/certs/carto.example.com.crt
    SSLCertificateKeyFile /etc/apache2/certs/private.key
    SSLCertificateChainFile /etc/apache2/certs/CA.crt

    <Directory /var/www/mercator/public>
        AllowOverride All
        Require all granted
    </Directory>

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

    ErrorLog ${APACHE_LOG_DIR}/mercator_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/mercator_ssl_access.log combined
</VirtualHost>
```

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

### Create application with relationships via REST API (Bash)

Source: https://context7.com/dbarzin/mercator/llms.txt

Logs in to obtain a JWT token, then posts a new application with linked entities, processes, and logical servers using curl. Requires bash, curl, and jq for JSON parsing. Suitable for automation scripts; ensure proper permissions for the API user.

```bash
#!/bin/bash
API_URL="http://127.0.0.1:8000/api"

# Login
TOKEN=$(curl -s -d '{"login":"admin@admin.com","password":"password"}' \
  -H "Content-Type: application/json" \
  ${API_URL}/login | jq -r .access_token)

# Create application with relationships
curl -X POST "${API_URL}/applications" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=CRM System" \
  -d "version=2.5.1" \
  -d "description=Customer Relationship Management" \
  -d "type=Web Application" \
  -d "security_need_c=3" \
  -d "security_need_i=3" \
  -d "security_need_a=2" \
  -d "technology=PHP/MySQL" \
  -d "responsible=John Doe" \
  -d "entities[]=1" \
  -d "entities[]=2" \
  -d "processes[]=5" \
  -d "logical_servers[]=10" \
  -d "databases[]=3"
```

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

### Query API Users with Bash and JQ

Source: https://github.com/dbarzin/mercator/blob/master/docs/api.md

This script queries the API for users and decodes the JSON response using JQ. It requires curl and jq to be installed and assumes a valid bearer token is set in the environment variable ${token}. Input is the token; output is the parsed JSON user data. Limitations include dependency on an active API server and network connectivity.

```bash
curl -s -H "Content-Type: application/json" -H "Authorization: Bearer ${token}" "http://127.0.0.1:8000/api/users" | jq .
```