Installing NavVis IVION Locally via Docker

Before you start installing aNavVis IVION Instance via Docker, you will need the following:

• Permission 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 instance

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

We recommend running 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 on a Windows Server, so we will not be able to support 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.

Procedure

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: 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

Procedure

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

Procedure

1. Download the docker-compose files and move them to the directory where should be hosted.

2. Unpack the .zip file and remove it afterward.

3. To adjust the 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 Docker Images, you will need to connect to the 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 Docker Registry:

Note: If you are installing 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 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 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, refer here for more detail.

   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 instance, make sure that you are successfully connected to the Docker Registry. This will ensure that the latest Docker images can be pulled during first startup.

Procedure

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 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 to make sure all the transferred data is encrypted. The options to do this depend on your specific infrastructure.

Starting and Stopping an Instance

Procedure

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 instance run docker-compose down.

Updating an Instance

Procedure

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

Procedure

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

Procedure

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 s torage/iv/data when running docker-compose up. If you want to use data from an existing directory, you can use a symbolic link.

Procedure

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

Procedure

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 variable 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 on a machine without internet access, you have to transfer the required Docker images to that machine. Follow these steps after you have accessed the Docker images and before configuring your instance.

Procedure

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}.