On-Premise Installation

This documentation is valid from release v88 on.

Welcome to the Heisenware On-Premise Installation Guide! This document will walk you through setting up and running your own private instance of the Heisenware platform. The process is designed to be straightforward, even if you're not a system administrator.

Prerequisites: Docker Installation

The entire Heisenware platform runs in a set of containers managed by Docker. Before you can install our software, you need to have a working Docker environment on your server or local machine.

The setup process is slightly different depending on your operating system. Please follow the guide for your specific OS.

If you are running a Linux distribution (like Ubuntu, Debian, or CentOS), you will install Docker Engine, which now includes the Docker Compose plugin.

Follow the official Docker guide to install Docker Engine for your specific Linux distribution. The setup process will include all the necessary components, including the docker compose command.
You will run all subsequent commands in your standard terminal window.

Download Docker Desktop from the official website: Docker Desktop for Mac.
Open the downloaded .dmg file and drag the Docker icon into your Applications folder.
Launch Docker Desktop from your Applications folder. It may ask for permissions to finish its installation.

You will run all subsequent commands in the standard Terminal application, which you can find in Applications/Utilities.

Modern Windows systems use the Windows Subsystem for Linux (WSL) to run Docker efficiently. This gives you the power of a Linux environment directly inside Windows and is the most stable way to run Heisenware.

Step 1: Install WSL and Ubuntu

The easiest way to set up everything you need is with a single command.

Open the PowerShell application as an Administrator. You can do this by searching for "PowerShell" in the Start Menu, right-clicking it, and selecting "Run as administrator".
In the blue PowerShell window, copy and paste the following command, then press Enter:
```
wsl --install
```
This command will automatically enable the required Windows features, download the Linux kernel, and install Ubuntu as your default Linux distribution.
After it finishes, reboot your computer as prompted to complete the installation.

Step 2: Install Docker Desktop for Windows

Download Docker Desktop from the official website: Docker Desktop for Windows.
Run the downloaded installer and follow the on-screen instructions. A crucial step is to ensure the "Use WSL 2 instead of Hyper-V (recommended)" option is checked.
Once installed, launch Docker Desktop. It will automatically detect and integrate with the Ubuntu environment you installed via WSL.

Step 3: Work inside the WSL Terminal

From now on, whenever you need to run a command for the installation, you will do it inside your new Ubuntu environment.

Open your Start Menu and search for Ubuntu.
Click to open it. This will launch a terminal window. This is where you will copy your Heisenware installation files and run the install.sh script.

Installing Heisenware

You will receive two files from us:

heisenware-onprem-vXX-Y.tar.gz - The main application package.
install.sh - The installation script.

Place both of these files into a new, empty directory on your machine. For Windows users, make sure you do this inside your Ubuntu (WSL) environment. The file path will look something like /home/yourusername/heisenware/.

Optional: Direct download into the terminal

To ease your installation we offer the possibility to receive the above mentioned files directly into the terminal in which you are going to run the platform. We will provide you a time-bound link to the application package which you download using wget :

Make sure to put quotes (") around the link when downloading

wget -O heisenware.tar.gz "<the link from us>"

The install.sh can always freely be downloaded using:

wget "https://downloads.heisenware.cloud/public/install.sh"

Open Your Terminal

Windows: Open the Ubuntu app from your start menu.
macOS/Linux: Open your standard Terminal app.

Navigate to the directory where you saved the two files. For example:

cd /home/yourusername/heisenware/

Make the Script Executable

Run the following command to give your computer permission to run the installation script:

chmod +x install.sh

Run the Installer

Now, start the installation by running the script and providing the name of the application package:

./install.sh heisenware.tar.gz

The script will guide you through the process with a series of prompts. It will unpack all the necessary files, load the Docker images, and set up your environment.

Start the Application

Once the script finishes successfully, start the entire platform with one command:

docker compose up -d

It may take a few minutes for all services to start up for the first time. Congratulations, your Heisenware On-Premise instance is now running!

Access

Your application should now be available under http://localhost . If this does not work try http://localhost/manager . Initially the system uses self-signed certificates created by us, which your browser will not and cannot verify. You hence must explicitly allow your browser to still continue (it's safe, you started it locally 😄).

Certificates

In case you are having own certificates for your premises, you can happily install them in the certs folder. Just keep the format and the name of the file, restart and everything is in shape.

You can use docker restart heisenware-ingress-1 to apply new certificates easily.

Account Creation

The first thing you will have to do on this fresh system is creating an account (will stay local). For that click the respective link and use email + password to setup your credentials (Google will not work on your local server!)

Updating Your Installation

The update process is designed to be safe and simple. When a new version is available, you will receive a new link to download the application package.

Place the new file in the same directory as your existing installation, replacing the old one.
Run the installer again, just like you did the first time:
```
./install.sh heisenware.tar.gz
```

The script will automatically detect an existing installation and switch to update mode.

Automatic Backup: Before making any changes, the script will automatically create a full backup of your existing application data. This backup will be saved as a timestamped .tar.gz file in a new backup/ directory. This is your safety net in case anything goes wrong.

The script will then guide you through stopping the old version and installing the new one.

Rollback & Restoring a Backup

If an update causes an issue, you can easily roll back your data to the state it was in before the update.

Find the backup file you want to restore in the backup/ directory.
Run the same install.sh script, but this time, give it the path to the backup file:
```
./install.sh backup/heisenware-backup-YYYY-MM-DD_HH-MM-SS.tar.gz
```
The script will recognize the backup file and enter Restore Mode. It will ask for confirmation, stop the application, and overwrite the current data with the contents of your backup.
Once it's finished, you can restart the application with docker compose up -d to run on the restored data.

Basic Application Management

Here are a few basic commands you can run in your terminal (from your installation directory) to manage the platform:

Stop the application: docker compose stop
Start the application again: docker compose start
View live logs from all services: docker compose logs -f

Last updated 9 days ago