Skip to main content

Installation automatique.

This guide walks you through the steps to set up the iTop Portal on your server. Follow these instructions carefully to ensure a smooth installation process. Before proceeding, make sure you’ve met all the Prerequisites.

Step 1: Retrieve the Project​

The iTop Portal source code is hosted on GitHub. To get started, clone the repository to your local machine or server:

  git clone https://github.com/Sparfel/itop-portal-2.git
  cd itop-portal-2
Important

Make sure that the cloned folder is fully accessible by your web server (e.g., Apache). This means proper permissions must be set so that Apache can read and execute files within this directory. On Linux systems, this typically involves setting the correct ownership and permissions.

For example:

  sudo chown -R www-data:www-data itop-portal-2/

Step 2: Create the Database​

The iTop Portal requires a MariaDB database to store its data. Set up the database as follows:

  1. Log in to your MariaDB server:

    mysql -u root -p

  2. Create a new database (replace itop_portal_db with your preferred name):

    CREATE DATABASE itop_portal_db;

  3. Optionally, create a dedicated user and grant privileges:

    CREATE USER 'itop_user'@'localhost' IDENTIFIED BY 'your_secure_password';
    GRANT ALL PRIVILEGES ON itop_portal_db.* TO 'itop_user'@'localhost';
    FLUSH PRIVILEGES;
    EXIT;

Step 3: Configure the Environment​

Laravel uses a .env file to manage environment-specific settings. Set it up as follows:

Environment file .env​

Copy the example environment file:​

cp .env.example .env

Edit .env to include your database credentials:​

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=itop_portal_db
DB_USERNAME=itop_user
DB_PASSWORD=your_secure_password

and iTop integration details:

ITOP_0_NAME="My iTop"
ITOP_0_PROTOCOL=https
ITOP_0_URL=URL_ITOP
ITOP_0_USER=webservice_itop_user
ITOP_0_PASSWORD=webservice_itop_user_password
ITOP_0_DEBUG=0
Webservice Access

webservice_itop_user and webservice_itop_user_password are the credentials of your iTop user with special permissions (REST User Service and Administrator) required for the portal to interact with iTop, see Prerequisites.

Secondary Instance (Test):​

info

It is possible to link to other iTop instances. In that case, they should be defined as shown below:

ITOP_1_NAME="My iTop (Test)"
ITOP_1_PROTOCOL=https
ITOP_1_URL=URL_ITOP_TEST
ITOP_1_USER=webservice_itop_user
ITOP_1_PASSWORD=webservice_itop_user_password
ITOP_1_DEBUG=0
warning

The connection to iTop is defined at the user level. Therefore, a user is linked to an iTop instance within the portal.

danger

All linked iTop instances must be identical (or very similar) because the calls to the iTop Webservice are based on a DataModel. This DataModel must therefore be common to all linked iTop instances.

Generate an application key:​

php artisan key:generate

Step 5 : Installation​

Automatic Installation via setup.sh​

To simplify the installation process, an automated script is available at the root of the repository: setup.sh (or setup.ps1 for Windows PowerShell users).

This script handles all the necessary steps to set up the project in either development or production mode:

  • Installation of PHP dependencies via Composer (with or without dev packages, depending on the mode)
  • Installation of JavaScript dependencies
  • Asset compilation (CSS/JS)
  • Creation of the symbolic link to the storage folder
  • Execution of database migrations and seeders

Usage​

# Development mode (default)
./setup.sh

or

# Production mode
./setup.sh --prod

The --prod flag installs only production dependencies, optimizes the autoloader, compiles assets for production, and runs migrations and seeders without confirmation.

Manual Installation (Advanced)​

If you prefer to install and configure the portal manually instead of using the setup.sh script, follow these steps:

  1. Install PHP dependencies using Composer:
composer install
note

Add options '--no-dev --optimize-autoloader' for production

  1. Install JavaScript dependencies (main frontend):
npm install
npm audit fix
  1. Customize AdminLTE assets:
cd resources/vendor/admin-lte
npm install
npm audit fix
npm run production
cd ../../..
  1. Compile the main frontend assets (CSS/JS):
npm run dev
note

Use 'npm run production' for production

  1. Create the symbolic link to the storage folder:
php artisan storage:link
  1. Run database migrations and seeders:
php artisan migrate:fresh --seed

In production, you can also run the database migration and seed steps manually:

php artisan migrate --force
php artisan db:seed --class=RolesTableSeeder --force
php artisan db:seed --class=PermissionsTableSeeder --force
php artisan db:seed --class=RoleHasPermissionsTableSeeder --force

Step 6: Creating an Administrator Account from iTop​

To initialize the portal, you can automatically create a local administrator account based on an existing iTop contact.

This is done using the following Artisan command:

php artisan itop:setup-admin --instance=0

Replace --instance=0 with the appropriate iTop instance if you have configured multiple instances in your .env file.

You will be prompted to enter the email address of the administrator contact as defined in iTop. If the contact is found, a local user account will be created on the portal, and you will be asked to define a password.

The user will automatically be assigned the Administrator role and granted access to the platform.

Note: If your iTop instance uses a self-signed SSL certificate, make sure your system or proxy does not block the connection.