Installing NavVis IVION Locally via Docker

Prerequisites

Before you start installing a NavVis IVION instance via Docker, you will need the following:

• A NavVis Portal account with permissions to access the NavVis Docker Registry Hub and the repository

• At least 3 GiB of free disk space

• At least 2 GiB RAM per Docker container running a NavVis IVION instance

• At least 32 GiB RAM (recommended 64 GiB) to use certain NavVis IVION features which are memory intensive (e.g. floor maps generation)

We recommend running NavVis IVION on Ubuntu. However, you can choose any other Linux based OS that is able to run Docker. Be aware that we do not support hosting NavVis IVION on a Windows Server, so we will not be able to support NavVis IVION instances installed on Windows.

Note: On certain operating systems, you will need to increase Docker's memory limit to make sure the available RAM can be fully accessed.

Installing Docker Engine

Follow these steps to install Docker Engine on your Linux machine:

1. Install the latest version of Docker Engine. Docker installation may vary based on the operating system that you are using, therefore, refer to the official Docker Engine Installation guide for help with the installation.
   Note: NavVis IVION can only be installed on Docker versions 17.04.0+ or newer.
2. After installing Docker, run sudo systemctl start docker to start it on Linux-based operating systems.
3. If you want Docker to start automatically on boot up, run sudo systemctl enable docker on Linux-based operating systems.

Installing Docker Compose

Follow these steps to install Docker Compose on your Linux machine:

Note: Make sure your machine is connected to the internet, and you have curl installed.

1. Run:

   sudo curl -L "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   Note: You can check here for the latest version of Docker Compose and substitute the respective version number (e.g. 1.29.1) accordingly to install the most recent version.
2. Apply executable permissions to the binary:

   sudo chmod +x /usr/local/bin/docker-compose
3. Test the installation:

   docker-compose --version

Preparing and Configuring NavVis IVION

Follow these steps to prepare and configure your NavVis IVION instance:

1. Download the NavVis IVION docker-compose files and move them to the directory where NavVis IVION should be hosted.
2. Unpack the .zip file and remove it afterward.
3. To adjust the NavVis IVION configuration, open the .env file in a file editor of your choice. Edit the .env file as needed and save the file afterward.
   Note: The .env file is hidden.

Connecting to the NavVis Docker Registry

In order to access the NavVis IVION Docker Images, you will need to connect to the NavVis Docker Registry. If you do not have access or do not see any repositories in your account, contact support@navvis.com. 

Follow these steps to connect to the NavVis Docker Registry:

Note: If you are installing NavVis IVION via Docker in China, see the documentation for China.

1. Go to the NavVis Docker Registry.
2. Click Login via OIDC Provider.
3. Log in with your NavVis Portal account.
4. Click on your username in the upper right corner, go to the user profile and copy the CLI secret.
   Note: If you do not have a username yet, you will be prompted to create one when you log in for the first time to the NavVis Docker Registry.
5. Make sure that Docker is running. Then, run docker login docker.navvis.com in a new terminal window and enter your unique username and paste the CLI secret when prompted to insert the password.
   If the login was successful, you will see Login Succeeded inside your terminal session.

   Note: If logging in with docker login docker.navvis.com fails, login to the NavVis Docker Registry with a web browser and then rerun the docker login command.

Initializing NavVis IVION

Before starting your first NavVis IVION instance, make sure that you are successfully connected to the NavVis Docker Registry. This will ensure that the latest NavVis IVION Docker images can be pulled during first startup.

Follow these steps to initialize your first NavVis IVION instance:

1. Run docker-compose up -d to create and start your first NavVis IVION instance. Alternatively, you can run docker-compose up to see all background tasks that are run during startup.
2. Use the following credentials to log into NavVis IVION for the first time:
   Username: admin
   Password: ivadmin

NavVis IVION will now be served locally on your machine/server at the network address of the machine at the specified port, e.g. http://localhost:{INSTANCE_PORT}/{INSTANCE_NAME}.

When using the default configuration, the network address will be http://localhost:8080/iv. If you are starting your instance for the first time, the boot procedure might take some time.

Note: We recommend setting up HTTPS for the traffic that is served by NavVis IVION to make sure all the transferred data is encrypted. The options to do this depend on your specific infrastructure. You can find more information here.

Starting and Stopping an Instance

Follow these steps to start and stop your NavVis IVION instance:

1. To start a single NavVis IVION instance run docker-compose up -d.
   Alternatively, you can run docker-compose up to see all background tasks that are run during startup.
2. To stop a NavVis IVION instance run docker-compose down.

Updating an Instance

Follow these steps to update your NavVis IVION instance:

1. Stop the instance by running docker-compose down.
2. Login via your browser into the NavVis Docker Registry to unlock the CLI secret.
3. Pull the latest images by running docker-compose pull.
4. You can then start the new version in the background using docker-compose up -d.

Creating a Backup

Follow these steps to create a backup of your NavVis IVION instance:

1. Stop the instance by running docker-compose down.
2. Copy the complete content of the storage path. By default the storage path is storage/iv.
   Important: To avoid corruption of the backup, you need to stop the instance before the backup.

Restoring a Backup

Follow these steps to restore a backup of your NavVis IVION instance:

1. Copy the data that you have backed up to the storage folder of a new, not running instance.
2. Start the instance by running docker-compose up -d.

Advanced Configuration

Directory Structure

All data is stored inside the ${STORAGE_PATH}/${INSTANCE_NAME} directory. This includes dataset files, uploaded files, temporary files, log files, the search index, and others.

Using Existing Data

By default, a new and empty directory will be created in storage/iv/data when running docker-compose up. If you want to use data from an existing directory, you can use a symbolic link.

Follow these steps to create a symbolic link:

1. If the name of the instance is iv, run mkdir -p storage/iv && ln -s /mnt/network-drive/datasets_web storage/iv/data.
2. Stop the instance by running docker-compose down.
3. Remove the storage/iv/data directory.
4. Create the symbolic link by running mkdir -p storage/iv ln -s /mnt/network-drive/datasets_web storage/iv/data.
5. Start the instance by running docker-compose up -d.

Running Multiple Instances

Follow these steps to run multiple instances:

1. Create a separate directory using docker-compose.yml and the .env files.
2. Change into the directory.
3. Modify the INSTANCE_NAME , INSTANCE_PORT and POSTGRES_DB variables in the .env file.
   Note: You do not have to modify the STORAGE_PATH to run multiple instances, as the INSTANCE_NAME is used to separate the data from multiple instances.
4. Run docker-compose up or docker-compose up -d to start the instance.

Installing NavVis IVION Offline

To install NavVis IVION on a machine without internet access, you have to transfer the required Docker images to that machine.

To install NavVis IVION offline, follow these steps after you have accessed the Docker images and before configuring your NavVis IVION instance:

1. Run the following commands to download and save the images:
   1. docker pull docker.navvis.com/postgresql/postgresql:12
   2. docker pull docker.navvis.com/ivion-stable/ivion:latest
   3. docker save -o postgresql.docker docker.navvis.com/postgresql/postgresql:12
   4. docker save -o ivion.docker docker.navvis.com/ivion-stable/ivion:latest
2. Transfer postgresql.docker and ivion.docker to the machine, e.g. using a USB stick.
3. Install Docker and Docker Compose and load the images by running:
   1. docker load -i postgresql.docker
   2. docker load -i ivion.docker

Beta Versions

From time to time, NavVis releases beta versions of NavVis IVION.

To use them, edit docker-compose.yml and change image: docker.navvis.com/ivion-stable/ivion:latest to image: docker.navvis.com/ivion-testing/ivion:latest.

Note: Do not use beta versions in production as they may contain bugs and be less secure. Upgrading to the next release version, as well as downgrading to the current stable version, may not be possible. Consider making a backup of the database before starting a beta version.

Troubleshooting

The following commands can be useful in case of errors or unexpected behavior:

• docker ps to list all containers.

• docker stats to display resource usage statistics.

• docker-compose logs to view the logs from running services.

The NavVis IVION log files are stored in ${STORAGE_PATH}/${INSTANCE_NAME}/log . When you are reporting a problem, please include the output of docker -v and docker-compose -v .

If you get the following errors when running docker commands you might need to add sudo before the commands.

Output docker: Cannot connect to the Docker daemon. Is the docker daemon running on this host?. See 'docker run –help'.

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied

If you want to avoid typing sudo whenever you run a docker command, add your username to the docker group: sudo usermod -aG docker ${USER}. To apply the new group membership, log out of the server and log back in, or run su - ${USER}.