Page tree
Skip to end of metadata
Go to start of metadata

This documentation is related to openITCOCKPIT 4


Create a virtual machine

We recommend to create a new virtual machine (e.g. with VirtualBox) which fulfill the minimum requirements:

OSHard driveMemoryCPU Cores
Ubuntu Focal 20.04 (64 Bit)20GB2048MB2


To access the virtual machine via the network, the easiest method is to use a "Bridged Network". 

If you don't want to use a "Bridged Network" we recommend to add 2 network cards to the VM. On in "NAT" mode to access the internet and on in "Host-Only Network" so you can access the VM from your local computer.

Read more about networking with VirtualBox at: https://www.virtualbox.org/manual/ch06.html


If preferred you can also use "Ubuntu Desktop" to get a graphical environment.

Prepare the operating system

Please make sure that your system has installed the latest updates

sudo add-apt-repository universe
sudo apt-get update
sudo apt-get dist-upgrade

Install required packages for development

sudo apt-get dist-upgrade vim git tmux screen mc htop curl wget ca-certificates sysstat nfs-kernel-server samba-common samba gnupg2 apt-transport-https

Enable the "root" user

By default the root user is disabled on Ubuntu.

Use sudo to switch to the root user.

sudo su

Set a new password for the root user with the command "passwd"

passwd
passwd example
root@oitc-dev:/home/dziegler# passwd
New password:
Retype new password:
passwd: password updated successfully
root@oitc-dev:/home/dziegler#

Enable root login through SSH (optional)

Open the file "/etc/ssh/sshd_config" and change the following line

/etc/ssh/sshd_config
PermitRootLogin yes

Apply the changes

systemctl restart sshd

You can now connect as root user via SSH.

Install openITCOCKPIT

As you want to setup a development system of openITCOCKPIT we assume that you are familiar with the openITCOCKPIT setup process. For more information on how to setup an openITCOCKPIT System, pease see: https://openitcockpit.io/download_server/

curl https://packages.openitcockpit.io/repokey.txt | sudo apt-key add -

echo "deb https://packages.openitcockpit.io/openitcockpit/$(lsb_release -sc)/stable $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openitcockpit.list
sudo apt-get update

sudo apt-get install openitcockpit

Setup openITCOCKPIT

Use the setup wizard of openITCOCKPIT to create a user for the web interface. It's not required that the used email address exists.

sudo /opt/openitc/frontend/SETUP.sh

Setup phpMyAdmin (optional)

phpMyAdmin is a web based mysql database management tool. After the installation it is reachable at https://xxx.xxx.xxx.xxx/phpmyadmin. You can find the MySQL username and password in the file "/opt/openitc/etc/mysql/mysql.cnf"

sudo apt-get install phpmyadmin
MySQL username and password
dziegler@oitc-dev:~$ sudo cat /opt/openitc/etc/mysql/mysql.cnf
; Automatically generated for openITCOCKPIT scripts. DO NOT TOUCH!
[client]
database = openitcockpit
host = localhost
user = openitcockpit
password = zw8upknsKte2pGvn
port = 3306
dziegler@oitc-dev:~$

Install PHP-Composer

Composer is a package manager for php libraries and required for openITCOCKPIT development systems.

curl -o composer-setup.php https://getcomposer.org/installer
php composer-setup.php
sudo cp composer.phar /usr/local/bin/composer

Clone the source code from GitHub

openITCOCKPIT use git as version control system. The repository is publicly hosted on GitHub.

Fork the openITCOCKPIT repository

Even if not required it is highly recommended to create a personal fork of the official openITCOCKPIT repository.

It is required if you want to contribute to the openITCOCKPIt project. If you just want to look around (or have no GitHub account yet) you can clone the official openITCOCKPIT repository instead.


Fork the openITCOCKPIT repository: https://github.com/it-novum/openITCOCKPIT via the GitHub web interface.

Clone your personal repository (recommended)

Delete the data installed by apt

sudo su
rm -rf /opt/openitc/frontend


Clone the repository (replace YOUR_ACCOUNT_NAME with your GitHub user)

cd /opt/openitc/
git clone -b development https://github.com/YOUR_ACCOUNT_NAME/openITCOCKPIT frontend

Clone official openITCOCKPIT repository (only recommended if you do not have a GitHub account)

Delete the data installed by apt

sudo su
rm -rf /opt/openitc/frontend
cd /opt/openitc/
git clone -b development https://github.com/it-novum/openITCOCKPIT frontend


Install dependencies

Please make sure to run all commands as root user (sudo su)

Install PHP dependencies

cd /opt/openitc/frontend

composer install

rm -f /opt/openitc/frontend/config/app_local.php


Install JavaScript dependencies

cd /opt/openitc/frontend

npm install


Update database and fix file permissions

openitcockpit-update --cc --rights


Enable openITCOCKPIT development mode (permanently)

As developer you want to enable the development features of openITCOCKPIT such as printing error messages to the browser, enabling the global php methods "dd($var)" and "debug($var);" and force the browser to load uncompressed CSS and JavaScript files.

Please make sure to run all commands as root user (sudo su)

Please be aware, that enabling the debug mode could lead to leakage of sensitive information. 

echo "OITC_DEBUG=1" >> /etc/environment
export OITC_DEBUG=1

sed -i 's/OITC_DEBUG 0/OITC_DEBUG 1/g' /etc/nginx/openitc/master.conf
systemctl restart nginx


Start hacking (smile)

Access the files from a remote system (IDE) (optional)

Most of the time your development environment (e.g. PhpStorm or Visual Studio Code) is not running on the same system as openITCOCKPIT does.

There are three common ways to access the source code from your IDE.

Through NFS (Linux and macOS clients)

Open the file "/etc/exports" on your openITCOCKPIT server and create a new record like this: (You can set access to a single ip address or to an entire subnet like in the given example. Please make sure to adjust the ip address to your network)

/opt/openitc/frontend/ 192.168.56.0/24(rw,no_subtree_check,no_root_squash,all_squash,anonuid=33,anongid=33)
sudo exportfs -a

Mount the NFS share on a Linux client

sudo apt-get install nfs-common

mkdir ~/openitcockpit-frontend
mount xxx.xxx.xxx.xxx:/opt/openitc/frontend ~/openitcockpit-frontend

Make sure to replace xxx.xxx.xxx.xxx with the ip address of your openITCOCKPIT server.

You can now open the folder "~/openitcockpit-frontend" with your IDE.

umount ~/openitcockpit-frontend

Mount the NFS share on a macOS client

mkdir ~/openitcockpit-frontend
sudo mount_nfs -o resvport xxx.xxx.xxx.xxx:/opt/openitc/frontend ~/openitcockpit-frontend

Make sure to replace xxx.xxx.xxx.xxx with the ip address of your openITCOCKPIT server.

You can now open the folder "~/openitcockpit-frontend" with your IDE.

sudo umount ~/openitcockpit-frontend

Through SMB (Window, Linux and macOS clients)

First you need to setup the SMB daemon on the openITCOCKPIT Server.

sudo cp /etc/samba/smb.conf /etc/samba/smb.conf.backup

Replace your current smb configuration located at "/etc/samba/smb.conf" with the following file:

/etc/samba/smb.conf
[global]
    workgroup = WORKGROUP
    server string = %h server (Samba, Ubuntu)

#### Debugging/Accounting ####
    log file = /var/log/samba/log.%m
    max log size = 1000
    logging = file
    panic action = /usr/share/samba/panic-action %d


####### Authentication #######
    server role = standalone server
    obey pam restrictions = yes
    unix password sync = yes
    passwd program = /usr/bin/passwd %u
    passwd chat = *Enter\snew\s*\spassword:* %n\n *Retype\snew\s*\spassword:* %n\n *password\supdated\ssuccessfully* .
    pam password change = yes

    security = user
    guest only = yes
    map to guest = bad user
    guest account = nobody

############ Misc ############
    usershare allow guests = yes

#======================= Share Definitions =======================
[frontend]
    path = /opt/openitc/frontend
    available = yes
    browseable = yes
    guest ok = no
    writeable = yes
    create mask = 0644
    directory mask = 0755
    force user = www-data
    valid users = www-data

Set a password for the user "www-data" to access the data via samba.

smbpasswd -a www-data

Apply the changes

sudo systemctl restart smbd

Mount the SMB share on a Windows client

Open Windows Explorer and click on "Map network drive"


Map your smb share as a network drive.

Make sure to tick "Connect using different credentials"

Use "www-data" as user and the password you set above


Browse through the files


Open "Z:\" with your IDE

Help: https://support.microsoft.com/en-us/help/4026635/windows-10-map-a-network-drive

Mount the SMB share on a macOS client

Go to finder and press CMD+k

Use "www-data" as user and the password you set above

Browse through the files

Open "/Volumes/frontend" with your IDE

Through SSH (cross-platform - depends on the IDE)

Many IDEs support to access remote files via FTP, SFTP or SSH. The setup process depends on the IDE you like to use.

Please search the web for something like "<IDE NAME> remote ssh project".


Setup for PhpStorm: https://www.jetbrains.com/help/phpstorm/create-new-project-add-remote-server.html

Setup for Visual Studio Code: https://code.visualstudio.com/docs/remote/ssh


Continue reading



  • No labels