Installing NavVis IVION Locally via Docker
Prerequisites
Before you start installing a NavVis IVION instance via Docker, you will need to have 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 the memory limit of Docker to make sure the available RAM can be fully accessed.
Installing Docker Engine
Follow these steps to install Docker Engine on your Linux machine:- Install the latest version of Docker Engine. The installation of Docker may vary based on the operating system that you are using, therefore, refer to the official Docker Engine Installation guide to help you with the installation.
Note: NavVis IVION can only be installed on Docker versions 17.04.0+ or newer.
- After installing Docker, run
sudo systemctl start docker
to start it on Linux based operating systems. - 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.
- 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.
- Apply executable permissions to the binary:
sudo chmod +x /usr/local/bin/docker-compose
- Test the installation:
Preparing and Configuring NavVis IVION
Follow these steps to prepare and configure your NavVis IVION instance: - Download the NavVis IVION docker-compose files and move them to the directory where NavVis IVION should be hosted.
- Unpack the .zip file and remove it afterwards.
- 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 afterwards.
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.
- Go to the NavVis Docker Registry.
- Click Login via OIDC Provider.
- Log in with your NavVis Portal account.
- 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.
- 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:- 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. - 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: - 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.
- To stop a NavVis IVION instance run
docker-compose down
.
Updating an Instance
Follow these steps to update your NavVis IVION instance: - Stop the instance by running
docker-compose down
. - Login via your browser into the NavVis Docker Registry to unlock the CLI secret.
- Pull the latest images by running
docker-compose pull
. - 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:- Stop the instance by running
docker-compose down
. - 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: - Copy the data that you have backed up to the storage folder of a new, not running instance.
- 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 so on.
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:
- If the name of the instance is
iv
, run mkdir -p storage/iv && ln -s /mnt/network-drive/datasets_web storage/iv/data
. - Stop the instance by running
docker-compose down
. - Remove the
storage/iv/data
directory. - Create the symbolic link by running
mkdir -p storage/iv ln -s /mnt/network-drive/datasets_web storage/iv/data
. - Start the instance by running
docker-compose up -d
.
Running Multiple Instances
Follow these steps to run multiple instances: - Create a separate directory using
docker-compose.yml
and the .env
files. - Change into the directory.
- 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.
- 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: - Run the following commands to download and save the images:
docker pull docker.navvis.com/postgresql/postgresql:12
docker pull docker.navvis.com/ivion-stable/ivion:latest
docker save -o postgresql.docker docker.navvis.com/postgresql/postgresql:12
docker save -o ivion.docker docker.navvis.com/ivion-stable/ivion:latest
- Transfer
postgresql.docker
and ivion.docker
to the machine, e.g. using a USB stick. - Install Docker and Docker Compose and load the images by running:
docker load -i postgresql.docker
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:
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 prepend sudo
to 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}
.