OpenMAINT is notoriously hard to install and set up, so I've decided to go ahead and document the steps I took to install it, alongside every bit of information for others that might find it useful.
Important: Not only is openMAINT hard to install, it's also hard to understand. I've created a simple "All you need to know" guide to openMAINT that can be found here.
⠀⠀⠀⠀If you're reading this wondering why docker can't simply be used to make our life easier... go ahead and try it for yourself. If you're one of the lucky ones who got it working, then great! If not, accept it, relate to us and keep reading this guide. If you're still a bit skeptic about it, I have some notes about docker at the end of the guide, so go take a look.
⠀⠀⠀⠀Either way, we're going to be installing openMAINT 2.3 (Built on CMDBuild 3.4.1) on a fresh Ubuntu 20.04 OS installation.
(Please note that this guide will not cover the Ubuntu OS installation)
Before actually doing anything, just make sure that your apt is up to date so we don't run into any issues later on.
Also, install unzip.
$ sudo apt-get update -y$ sudo apt-get upgrade$ sudo apt install unzipNOTE: If you get a permission denied error anywhere during this installation, just sudo it.
Now that that's covered, lets go ahead and install java. We need to install Java 17 specifically
$ sudo apt-get install openjdk-17-jdkOnce that's done, just use java -version to make sure it is installed. Something like this should come up.
openjdk version "17.0.7" 2023-04-18
OpenJDK Runtime Environment (build 17.0.7+7-Ubuntu-0ubuntu122.04.2)
OpenJDK 64-Bit Server VM (build 17.0.7+7-Ubuntu-0ubuntu122.04.2, mixed mode, sharing)⠀⠀⠀⠀OpenMAINT uses PostgreSQL in order to store inventory, maintenance, and general data, so we're going to have to install it now. Every version after PostgreSQL 12+ is known to break openMAINT, so we're using version 12 (Besides, the dumps are of a.v 1.14). Also, to add to the fun you're currently having, Ubuntu 20.04 doesn't have PostgreSQL 12 in its repository, so we have to add it manually. Nice, right?
⠀⠀⠀⠀First off, we need to import the repository signing key, so ubuntu knows what repo we're asking for. After running the command, if the output is "OK" you're good to go.
$ wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -Now that the signing keys are added, we need to add the actual repository and refresh the apt data. If you get a permission denied error on this one, it's okay.
$ echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/postgresql-pgdg.list > /dev/null$ sudo apt-get updateAt last, PostgreSQL is ready to be installed. Now we just have to run a simple command, and that's it.
$ sudo apt-get install postgresql-12NOTE: If you want to have support for geographical location data in openMAINT, you will need to install PostGIS. Luckily, by this point, you should have all the references needed to install it straight on like this:
$ sudo apt install postgresql-12-postgis-3 libpostgis-javaNow into the PostgreSQL configuration. Lets first configure PostgreSQ'S credentials: For this, start by logging into PostgreSQL and manually sending a query to change the password.
Warning: Please keep your passwords alphanumeric!
$ sudo passwd postgres
$ sudo usermod -aG sudo postgres$ sudo -u postgres psql template1# Change the 'postgres' user password (superuser password)
ALTER USER postgres WITH PASSWORD 'PSSWD';
# Quit the SQL console
\qDon't ask me why this is needed or what a DMS/CMIS is, I just know that it's something to do with reports and content, but I don't really get it. Either way, we need it, so lets proceed to the installation. First off, download the alfresco installer, change its permissions to allow it to be run, and run it.
$ wget http://dl.alfresco.com/release/community/build-3370/alfresco-community-3.4.d-installer-linux-x64.bin
$ chmod a+x alfresco-community-3.4.d-installer-linux-x64.bin
$ sudo ./alfresco-community-3.4.d-installer-linux-x64.bin --mode textAfter that, run the installer with the following settings:
- Choose 'English' (Type in 1)
- Accept SharePoint, Records Management, Web Quick Start and Web Project Manager
- Select an Installation Type 1
- Leave the installation folder as default
- Select the bundled MySQL database (Type in 1)
- Create the database password (Just type them in)
- Create Alfresco's password (Just type them in)
- Decline the installation as a service (It breaks anyways, so we're handling it ourselves.)
Now, we need to make sure that alfresco isn't running, since we still need to setup its bundled tomcat server. Navigate to /opt/alfresco-3.4 and stop the service if its running.
$ cd /opt/alfresco-3.4.d
$ sudo ./alfresco.sh status
# IF ITS RUNNING
$ sudo ./alfresco.sh stopGreat! Now, lets open alfresco tomcat's server.xml file, and edit the server ports. Change every defined port to the next highest number, so we can avoid conflicts with openMAINT's tomcat ports.
$ sudo nano tomcat/conf/server.xml// Line 22
<Server port="8006" shutdown="SHUTDOWN">
// Line 69 (lol)
<Connector port="8081" URIEncoding="UTF-8" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />Now, alfresco is pretty much set up. Lets go and boot it up, and proceed to the openMAINT installation. (We still need to configure it, but that comes later on).
$ sudo ./alfresco.sh startNow then, lets go and install the GeoServer - This one is really easy so just follow along.
$ sudo adduser geoserver ; sudo usermod -aG sudo geoserver ; sudo su - geoserver$ wget https://sourceforge.net/projects/geoserver/files/GeoServer/2.21.0/geoserver-2.21.0-bin.zipNow just extract it to the home directory, and edit the port it is hosted on...
$ unzip -d /home/geoserver/server geoserver-2.21.0-bin.zip$ nano /home/geoserver/server/start.iniJust scroll down now and replace the jetty.http.port setting with jetty.http.port=8082. When you're finished, press Ctrl+X, Y and ENTER to save.
Lets just add the GeoServer as a service so that we don't have to worry about it anymore...
$ sudo nano /usr/lib/systemd/system/geoserver.service[Unit]
Description=GeoServer Service
After=network.target
[Service]
Type=simple
User=root
Environment="GEOSERVER_HOME=/home/geoserver/server"
ExecStart=/home/geoserver/server/bin/startup.sh
ExecStop=/home/geoserver/server/bin/shutdown.sh
[Install]
WantedBy=multi-user.targetWhen you're done, press Ctrl+X, Y and ENTER to save...
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now geoserverAnd that's that! You can access the GeoServer interface on http://YOUR-IP:8082/geoserver, with credentials admin, geoserver.
At last, the system is now ready for the openMAINT installation! First off, lets create an openmaint user for organisation purposes, then we just need to download openMAINT 2.3.
$ sudo adduser openmaint ; sudo usermod -aG sudo openmaint ; sudo su - openmaint$ wget https://downloads.sourceforge.net/project/openmaint/2.3/openmaint-2.3-3.4.1-d.warMake sure that you have installed "openmaint-2.3-3.4.1-d.war". Notice the "-d" at the end!
Once that's done, run the installation jar, and enter these specific configurations, leaving everything that is not specified as default, and finish the installation by following the instructions displayed in the terminal.
$ java -jar ./openmaint-2.3-3.4.1-d.war installpostrgres admin account: postgres/<PASSWORD-FROM-STEP-3>
cmdbuild posrgres database name: openmaint_db
database dump to load: emptySince starting anything related to Tomcat as a service seems to not work (as far as I've noticed), we're going to have to create a startup and shutdown script to start and shutdown the required apps. Just create a new bash script, make it executable, and you're free to go.
# Use this if you've switched users for some reason
$ su - openmaint
$ nano startmaint.shAdd the following code into the opened file, and press CTRL+X, Yand ENTER to save.
##!/bin/bash
# Alfresco is kind of weird and can get its catalina.pid stuck after shutting,
# so we have to essentially restart it to get it up and running.
sudo "/opt/alfresco-3.4.d/alfresco.sh" stop
sudo rm -f /opt/alfresco-3.4.d/tomcat/temp/catalina.pid
sudo "/opt/alfresco-3.4.d/alfresco.sh" start
# ... The same is true for openMAINT. This is more of a restart script than a startup script
# if anything.
sudo -u openmaint "/home/openmaint/cmdbuild_30/bin/shutdown.sh"
sudo rm -f /home/openmaint/cmdbuild_30/bin/catalina.pid
sudo -u openmaint "/home/openmaint/cmdbuild_30/bin/startup.sh"
echo "------------------> openMAINT Started! <------------------"$ chmod a+x startmaint.shDo the same for the shutdown script, and again, press CTRL+X, Yand ENTER to save.
$ nano stopmaint.sh#!/bin/bash
# The shutdown is incredibly more simple...
sudo "/opt/alfresco-3.4.d/alfresco.sh" stop
sudo -u openmaint "/home/openmaint/cmdbuild_30/bin/shutdown.sh"$ chmod a+x stopmaint.shAnd... That's that! To turn on openMAINT, just use sudo /home/openmaint/startmaint.sh through a sudo-allowed account, and to turn it off use sudo /home/openmaint/stopmaint.sh. Simple!
To access your app after it turns on, use http://SERVER-IP:8080/cmdbuild (http://localhost:8080/cmdbuild will probably work).
Your credentials are Username: admin, Password: admin.
Boot openMAINT up, since we'll need it.
Log into openMAINT and click on the top right corner of the screen, on the small cogwheel near the log out button. This will take you into the administrative menu, where you can change the settings for pretty much everything. Use the navigation menu on the left to scroll down until you find a folder called "DMS" - Open it, hit settings, and edit the "host" field with the following link: http://YOUR-IP:8081/alfresco/s/cmis
Still in the administration page, navigate to the "GIS" folder and hit "External Services". When you're there, just change the port and IP to YOURSERV:8082, not touching anything else, and you're good to go!
After you complete this... you're set! Enjoy using openMAINT (Even though learning to use it can be quite tricky, since the documentation is scarce) and have a good one!
⠀⠀If you're running openMAINT in a server and want to access everything through other machines, you're going to have to configure xhost to allow it to display the reports and everything else to whoever connects. The simplest way to do this is to allow everyone in, even though this is a massive security risk. After you do this, restart openMAINT. The easiest way to know if you need to configure xhost is by trying to generate a report - if you get an x11 error, you know you need to configure it.
$ xhost +
$ sudo /home/openmaint/startmaint.sh # This acts as a restart by itself.⠀⠀Due to the nature of this program, creating backups and having them be somewhere safe is extremely important. Due to this, I created a script to automatically create backups for the alfresco and openMAINT databases. Every backup created will be stored over at /home/openmaint/backups, but its highly recommended that you change this to an entrypoint for some remote server folder.
⠀⠀After following the instructions to add the script, press Ctrl+X, Y and ENTER to save.
$ sudo nano /home/openmaint/backup.sh#!/bin/bash
# Database and general information
MAINT_DBNAME="openmaint_db"
TIME=$(date "+%Y%m%d-%H%M%S")
# Directories
BACKUP_DIR="/home/openmaint/backups"
MAINT_BACKUP_DIR="${BACKUP_DIR}/openmaint"
ALFRESCO_DATA_DIR="/opt/alfresco-3.4.d/alf_data"
ALFRESCO_BACKUP_DATA_DIR="${BACKUP_DIR}/alfresco/data"
ALFRESCO_BACKUP_DB_DIR="${BACKUP_DIR}/alfresco/db"
# Backup filenames
MAINT_BACKUP_FILE="${MAINT_BACKUP_DIR}/OM_$TIME.sql"
ALFRESCO_BACKUP_FILE="${ALFRESCO_BACKUP_DB_DIR}/al_$TIME.sql"
ALFRESCO_DATA_BACKUP="${ALFRESCO_BACKUP_DATA_DIR}/alfresco-data-${TIME}.tar.gz"
1
# Stops openMAINT and alfresco and creates the backups directory
echo -e "\033[0;33m----------- Stopping openMAINT & Alfresco -----------\033[0m"
sudo /home/openmaint/stopmaint.sh
sudo mkdir -p $BACKUP_DIR
sudo mkdir -p $MAINT_BACKUP_DIR
sudo mkdir -p $ALFRESCO_BACKUP_DATA_DIR
sudo mkdir -p $ALFRESCO_BACKUP_DB_DIR
sudo chmod -R 777 $BACKUP_DIR
# Separation
echo -e "\033[0;33m---------- Backing up openMAINT & Alfresco ----------\033[0m"
# ---------------------------------------------------------------------------------------------------------------------------
# OPENMAINT BACKUP > -------------------------------------------------------------------------------------------------------
# ---------------------------------------------------------------------------------------------------------------------------
echo "Backing up $MAINT_DBNAME to $MAINT_BACKUP_FILE"
# Backup the database using pg_dump
sudo -u postgres pg_dump $MAINT_DBNAME > $MAINT_BACKUP_FILE
# Log completion of backup
if [ -f $MAINT_BACKUP_FILE ] && [ -s $MAINT_BACKUP_FILE ]; then
echo -e "\033[32mopenMAINT Database backup successful!\033[0m"
else
echo -e "\033[31mError: openMAINT Database backup not created!\033[0m"
fi
# ---------------------------------------------------------------------------------------------------------------------------
# ALFRESCO BACKUP > ---------------------------------------------------------------------------------------------------------
# ---------------------------------------------------------------------------------------------------------------------------
echo "Backing up alfresco to $ALFRESCO_BACKUP_FILE and $ALFRESCO_BACKUP_DATA_DIR"
# Backup the Alfresco database
echo "Backing up Alfresco database"
sudo /opt/alfresco-3.4.d/alfresco.sh start mysql
sudo -u openmaint /opt/alfresco-3.4.d/mysql/bin/mysqldump --all-databases > $ALFRESCO_BACKUP_FILE
sudo /opt/alfresco-3.4.d/alfresco.sh stop mysql
# Backup the Alfresco data directory
echo "Backing up Alfresco data"
tar czf $ALFRESCO_DATA_BACKUP $ALFRESCO_DATA_DIR
# Log completion of backups
if [ -f $ALFRESCO_BACKUP_FILE ] && [ -s $ALFRESCO_BACKUP_FILE ]; then
echo -e "\033[32mAlfresco Database backup successful!\033[0m"
else
echo -e "\033[31mError: Alfresco Database backup not created!\033[0m"
fi
# ---------------------------------------------------------------------------------------------------------------------------
# FINISHING > ---------------------------------------------------------------------------------------------------------------
# ---------------------------------------------------------------------------------------------------------------------------
# If the -y argument is passed, start openmaint without questioning
if [ "$1" = "-y" ]; then
sudo /home/openmaint/startmaint.sh
exit 0
fi
# If the -n argument is passed, exit the program by this stage.
if [ "$1" = "-n" ]; then
exit 0
fi
# If no argument is passed, prompt the user with a yes/no interface to either start openmaint or not.
echo "Backups finished. Would you like to start up openMAINT? (y/n)"
select yn in "Yes" "No"; do
case $yn in
Yes ) sudo /home/openmaint/startmaint.sh; break;;
No ) exit;;
esac
done$ sudo chmod a+x /home/openmaint/backup.shTo run the script now, simply use the command below. The two available parameters to run it with are -y and -n, use it to either automatically run openMAINT after finishing the backups or not.
$ sudo /home/openmaint/backup.shOptionally (but very much recommended) you should also add this script to a crontab, so it runs every X amount of time, without the need for human input. This needs to be added in root's crontab, so we need to use sudo with it.
$ sudo crontab -eAdd the following line to the opened file, which will create a backup every day at 4 AM. You can, of course, change the backup times as you wish. if you're using nano, press CTRL+X, Y and ENTER to save, and if you're using VIM, :wq.
0 4 * * * sudo /home/openmaint/backup.sh -y⠀⠀⠀⠀Restoring a backup is pretty simple, and documented over at Page 24 of the CMDBuild Technical Manual.
⠀⠀⠀⠀I decided to include this here for anyone that might find it useful - I had a sort of rough time learning how to use openMAINT, given that it was my first time ever hearing about asset management, maintenance, etc, and I didn't really know what I was doing - I started working with it due to an internship I was in, and managed to pull it off after a few days of searching through the scarce tutorials that exist. That said, here are a few notes I'd like to leave you with and some learning materials for you to look at.
⠀⠀⠀⠀CMDBuild is an open source inventory management tool, in which a bunch of applications are built on. You can use a bunch of third party tools to go and create reports, workflows and custom pages (although these require JS, CSS & HTML knowledge), and dynamically modify your interface.
⠀⠀⠀⠀OpenMAINT is one of the many apps built on top of CMDBUILD, that handles the maintenance, both preventive and corrective, of the assets registered in it. Now, even though it is technically a fully separate app built on top of CMDBuild, it still relies heavily on it to the point where it can be considered almost a CMDBuild addon/framework. This means that the two are virtually the same, as far as the user input and experience goes. OpenMAINT offers a built-in organised structure for asset maintenance, which should not be altered, and a bunch of pre-built reports, workflows and custom pages to be used. Essentially, people made it amazingly simple to handle maintenance by setting up and creating everything related to maintenance for us.
⠀⠀⠀⠀This means that the CMDBuild manuals are extremely useful since openMAINT is "an addon" for CMDBuild, so you can just go ahead and read the CMDBuild manuals to learn most of the things. (Not everything, but most things.)
- My simple guide to openMAINT
- CMDBuild Administrator's Manual
- OpenMAINT Usage Overview Webinar
- OpenMAINT Preventive Maintenance Webinar
- OpenMAINT Overview Manual
⠀⠀⠀⠀I initially tried to just use docker to create an openMAINT container and not bother with a manual installation, however, I quickly found out that almost no one has public containers available, and those that do, have broken openMAINT images on them. Due to this, I was only able to find One functioning openMAINT 2.0 docker image.
- Snipe.IT - This one has a lot of functionality, is open source AND has both local and cloud-based data hosting, however, it does NOT include preventive maintenance (at the time of writing). It has an amazing interface, and if you're looking for a simple alternative, the installation is really easy, and the interface is also pretty friendly. They also have an amazing, maintained docker image!
- ManWinWin - This one has ACTUAL GOD-LEVEL SUPPORT. I found it a lot more complicated to understand than openMAINT was, but the support is simply amazing. They offer you proper documentation, learning courses, calls with technical support where they're really patient with you during the appointed time, and more. Such a service is of course, paid, however, it has a free version with some limits. I signed up for a free license on their website and I didn't really get their e-mails and was struggling to install the app. After a while of not replying to them, they found the contact of the company I worked for at the time, called it, asked for me, and helped me go through it. Apparently, their e-mails are sent by actual employees that keep up with your experience. 10/10.
Hi, This has been a great guide to getting OpenMaint working, thanks a lot. Recently found this docker image that works just as well fully set up you should take a look at it. https://github.com/itmicus/cmdbuild_docker