Overview

This document is used for setting up your server, and installing every dependency where IDHub will be deployed, in order to run the application seamlessly.
Before starting the installation and setting up the server, a few things needs to be completed:

  • Server Type
  • SSH access to the server
  • Docker
  • Docker compose
  • Open required Ports 
  • SSL keys and certificates
  • IDHub download file

These steps are discussed in detail below:


Setup Step 1: Type of Server

The type of server required for IDHub setup, will be one of the two mentioned below:

    1. Physical Server: A physical server, also known as a "Bare-Metal Server", is a single-tenant computer server. Meaning, a specific physical server is designated to a single user. The resources and components of a physical server are not shared between multiple users. Each physical server includes memory, processor, network connection,  storage, and an operating system (OS) for running programs and applications.

    2. Virtual Server: A virtual machine (VM) is a software computer used as emulation of an actual physical computer. A virtual server operates in a “Multi-Tenant” environment. Meaning, multiple VMs run on the same physical hardware. In this case, the computing resources of a physical server are visualized, and shared among all VMs running on it.

The type of server won't effect the below steps. You can choose either of them for your installation of IDHub.

Setup Step 2: SSH Access/ Secure Shell Access

In order to proceed, you must procure the SSH access of the server, in order to install the dependencies in the upcoming steps.

Before you proceed with installing an SSH client, determine if there is any instance of IDHub already running:

  • If an instance is installed, you will need to uninstall and proceed with re-installation of the IDHub.
  • If it is not already installed or uninstalled, proceed with installation.

For Linux: many Linux distributions already have an SSH client.

For Windows: you can install PuTTY or any other client of your choice, to gain access to a server.

Linux based SSH Access

To check if the client is available on your Linux-based system, you will need to:

  1. Load an SSH terminal. You can either search for “terminal” or press CTRL + ALT + T on your keyboard.
  2. Type in ssh and press "Enter" in the terminal.
  3. If the client is installed, you will receive a response that looks like this:
username@host:~$ ssh

usage: ssh [-1246AaCfGgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec]
[-D [bind_address:]port] [-E log_file] [-e escape_char]
[-F configfile] [-I pkcs11] [-i identity_file]
[-J [user@]host[:port]] [-L address] [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port] [-Q query_option] [-R address] [-S ctl_path] [-W host:port] [-w local_tun[:remote_tun]]
[user@]hostname [command]

username@host:~$
CODE

This means that you are ready to remotely connect to a physical or virtual machine.

If you do not see the response above, you will have to install the OpenSSH client:

  • Run the following command to install the OpenSSH client on your computer


sudo apt-get install openssh-client
CODE


  • Type in your superuser password when asked
  • Press "Enter" to complete the installation


You will now be able to SSH into any machine, with the server-side application on it.

*Note: you will need the necessary privileges to gain access, as well as the hostname or IP address to get to this stage.


In order to accept SSH connections, a machine needs to have the server-side part of the SSH software toolkit.

You can determine if OpenSSH server is available on the Ubuntu system of the remote computer which needs to accept SSH connections, you can try to connect to the local host:

  1. Open the terminal on the server machine. You can either search for “terminal” or press CTRL + ALT + T on your keyboard.
  2. Type in ssh localhost and press "Enter"
  3. For systems without the SSH server installed, the response will look similar to this:
username@host:~$ ssh localhost
ssh: connect to host localhost port 22: Connection refused username@host:~$
CODE

If the above is the case, you will need to install the OpenSSH server. Leave the terminal open and:

  1. Run the following command to install the SSH server:
sudo apt-get install openssh-server ii.
BASH


  1. Type in your superuser password when asked
  2. Enter and Y to allow the installation to continue after the disk space prompt

The required support files will be installed, and then you can check to determine if the SSH server is running on the machine by typing this command:

sudo service ssh status
BASH


If the SSH service is now running properly, the response in the terminal should look similar to this:

username@host:-$ sudo service ssh status
• ssh.service - OpenBSD Secure Shell server
Loaded: loaded (/lib/systemd/system/ssh.service; enabled; vendor preset: enab
Active: active (running) since Fr 2018-03-12 10:53:44 CET; 1min 22s ago Process: 1174 ExecReload=/bin/kill -HUP $MAINPID (code=exited, status=0/SUCCES

Main PID: 3165 (sshd)
BASH

Another way to test if the OpenSSH server is installed properly and will accept connections, is to try running the ssh localhost command again in your terminal prompt. The response will look similar to this screen when you run the command for the first time:

username@host:~$ ssh localhost

The authenticity of host 'localhost (127.0.0.1)' can't be established. ECDSA key fingerprint is SHA256:9jqmhko9Yo1EQAS1QeNy9xKceHFG5F8W6kp7EX9U3Rs. Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.

username@host:~$
BASH

Enter yes or y to continue.

Congratulations! You have set up your server to accept SSH connection requests, from a different computer using an SSH client.

Setup Step 3: Installing Docker

Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and deploy it as one package.

There may be two or more OS types in the server installed i.e: Ubuntu or centos, we cover these two installation steps in this document.

Install Docker in Ubuntu Based Environment

Uninstall old versions

Older versions of Docker were called docker, docker.io, or docker-engine. If these are installed, uninstall them:

$ sudo apt-get remove docker docker-engine docker.io containerd runc
BASH

It’s OK if apt-get reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved. The Docker Engine package is now called docker-ce.

Supported Storage Drivers

Docker Engine on Ubuntu supports overlay2, aufs and btrfs storage drivers.

Docker Engine uses the overlay2 storage driver by default. If you need to use aufs instead, you need to configure it manually. See use the AUFS storage driver

Installation Methods

Depending on your needs, you can install Docker Engine in different ways:

  • Most users set up Docker’s repositories and install from them, for ease of installation and upgrade tasks. This is the recommended approach.

  • Some users download the DEB package and install it manually, and manage upgrades completely manually. This is useful in situations such as installing Docker on air-gapped systems with no access to the internet.

  • In testing and development environments, some users choose to use automated convenience scripts to install Docker.

Install Using the Repository

Before you install Docker Engine for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.

Repository Setup
  1. Update the apt package index and install packages to allow apt to use a repository over HTTPS:

    $ sudo apt-get update
    BASH


    $ sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg-agent \ software-properties-common
    BASH


  2. Add Docker’s official GPG key:


    $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    BASH


    Verify that you now have the key with the fingerprint 9DC8 5822 9FC7 DD38 854A  E2D8 8D81 803C 0EBF CD88, by searching for the last 8 characters of the fingerprint.


    $ sudo apt-key fingerprint 0EBFCD88 
    BASH

    pub rsa4096 2017-02-22 [SCEA] 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 uid [ unknown] Docker Release (CE deb) <docker@docker.com> sub rsa4096 2017-02-22 [S]


  3. Use the following command to set up the stable repository. To add the nightly or test repository, add the word nightly or test (or both) after the word stable in the commands below. Learn about nightly and test channels.

    Note: The lsb_release -cs sub-command below returns the name of your Ubuntu distribution, such as xenial. Sometimes, in a distribution like Linux Mint, you might need to change $(lsb_release -cs) to your parent Ubuntu distribution. For example, if you are using Linux Mint Tessa, you could use bionic. Docker does not offer any guarantees on untested and unsupported Ubuntu distributions.


    $ sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) \ stable"
    BASH


Install Docker Engine
  1. Update the apt package index, and install the latest version of Docker Engine and containerd, or go to the next step to install a specific version:

    $ sudo apt-get update 
    BASH


    $ sudo apt-get install docker-ce docker-ce-cli containerd.io
    
    
    BASH

    Got multiple Docker repositories?

    If you have multiple Docker repositories enabled, installing or updating without specifying a version in the apt-get install or apt-get update command always installs the highest possible version, which may not be appropriate for your stability needs.

  2. To install a specific version of Docker Engine, list the available versions in the repo, then select and install:

    a. List the versions available in your repo:


    $ apt-cache madison docker-ce
    BASH


    docker-ce | 5:18.09.1~3-0~ubuntu-xenial | https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
    docker-ce | 5:18.09.0~3-0~ubuntu-xenial | https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
    docker-ce | 18.06.1~ce~3-0~ubuntu | https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
    docker-ce | 18.06.0~ce~3-0~ubuntu | https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages ...

    b. Install a specific version using the version string from the second column, for example, 5:18.09.1~3-0~ubuntu-xenial.


    $ sudo apt-get install docker-ce=<VERSION_STRING> docker-ce-cli=<VERSION_STRING> containerd.io
    BASH



  3. Verify that Docker Engine is installed correctly by running the hello-world image.


    $ sudo docker run hello-world
    BASH


    This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Docker Engine is installed and running. The docker group is created but no users are added to it. You need to use sudo to run Docker commands. Continue to Linux postinstall to allow non-privileged users to run Docker commands and for other optional configuration steps

Upgrade Docker Engine

To upgrade Docker Engine, first run:


sudo apt-get update
BASH


Install From a Package

If you cannot use Docker’s repository to install Docker Engine, you can download the .deb file for your release and install it manually. You need to download a new file each time you want to upgrade Docker.

  1. Go to https://download.docker.com/linux/ubuntu/dists/, choose your Ubuntu version, then browse to pool/stable/, choose amd64, armhf, or arm64, and download the .deb file for the Docker Engine version you want to install.

    Note: To install a nightly or test (pre-release) package, change the word stable in the above URL to nightly or test. Learn about nightly and test channels.

  2. Install Docker Engine, changing the path below to the path where you downloaded the Docker package.


    $ sudo dpkg -i /path/to/package.deb
    BASH


    The Docker daemon starts automatically.

  3. Verify that Docker Engine is installed correctly by running the hello-world image.


    $ sudo docker run hello-world
    BASH

    This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.


Docker Engine is installed and running

Install Docker in Centos Based Environment

Uninstall Old Versions

Older versions of Docker were called docker or docker-engine. If these are installed, uninstall them, along with associated dependencies.


$ sudo yum remove docker \ docker-client \ docker-client-latest \ docker-common \ docker-latest \ docker-latest-logrotate \ docker-logrotate \ docker-engine
BASH


It’s OK if yum reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved. The Docker Engine package is now called docker-ce.

Installation Methods

You can install Docker Engine in different ways, depending on your needs:

  • Most users set up Docker’s repositories and install from them, for ease of installation and upgrade tasks. This is the recommended approach.

  • Some users download the RPM package and install it manually and manage upgrades completely manually. This is useful in situations such as installing Docker on air-gapped systems with no access to the internet.

  • In testing and development environments, some users choose to use automated convenience scripts to install Docker.

Install Using the Repository

Before you install Docker Engine for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.

Repository Setup

Install the yum-utils package (which provides the yum-config-manager utility) and set up the stable repository.


$ sudo yum install -y yum-utils 
BASH


$ sudo yum-config-manager \ --add-repo \ https://download.docker.com/linux/centos/docker-ce.repo
BASH


Optional: Enable the nightly or test repositories.

These repositories are included in the docker.repo file above but are disabled by default. You can enable them alongside the stable repository. The following command enables the nightly repository.

$ sudo yum-config-manager --enable docker-ce-nightly

To enable the test channel, run the following command:

$ sudo yum-config-manager --enable docker-ce-test

You can disable the nightly or test repository by running the yum-config-manager command with the --disable flag. To re-enable it, use the --enable flag. The following command disables the nightly repository.

$ sudo yum-config-manager --disable docker-ce-nightly

Learn about nightly and test channels.

Install Docker Engine
  1. Install the latest version of Docker Engine and containerd, or go to the next step to install a specific version:


    $ sudo yum install docker-ce docker-ce-cli containerd.io
    BASH


    If prompted to accept the GPG key, verify that the fingerprint matches 060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35, and if so, accept it.

    Got multiple Docker repositories?

    If you have multiple Docker repositories enabled, installing or updating without specifying a version in the yum install or yum update command always installs the highest possible version, which may not be appropriate for your stability needs.

    Docker is installed but not started. The docker group is created, but no users are added to the group

  2. To install a specific version of Docker Engine, list the available versions in the repo, then select and install:

    a. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:


    $ yum list docker-ce --showduplicates | sort -r 
    BASH

    docker-ce.x86_64 3:18.09.1-3.el7
    docker-ce-stable docker-ce.x86_64 3:18.09.0-3.el7
    docker-ce-stable docker-ce.x86_64 18.06.1.ce-3.el7
    docker-ce-stable docker-ce.x86_64 18.06.0.ce-3.el7
    docker-ce-stable

    The list returned depends on which repositories are enabled, and is specific to your version of CentOS (indicated by the .el7 suffix in this example).

    b. Install a specific version by its fully qualified package name, which is the package name (docker-ce) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ce-18.09.1.


    $ sudo yum install docker-ce-<VERSION_STRING> docker-ce-cli-<VERSION_STRING> containerd.io
    BASH


    Docker is installed but not started. The docker group is created, but no users are added to the group

  3. Start Docker.


    $ sudo systemctl start docker
    BASH
  4. Verify that Docker Engine is installed correctly by running the hello-world image.


    $ sudo docker run hello-world
    BASH


    This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits

Docker Engine is installed and running. You need to use sudo to run Docker commands. Continue to Linux postinstall to allow non-privileged users to run Docker commands and for other optional configuration steps.

Upgrade Docker Engine

To upgrade Docker Engine, follow the installation instructions, choosing the new version you want to install.

Install From a Package

If you cannot use Docker’s repository to install Docker, you can download the .rpm file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

  1. Go to https://download.docker.com/linux/centos/ and choose your version of CentOS. Then browse to x86_64/stable/Packages/ and download the .rpm file for the Docker version you want to install.

    Note: To install a nightly or test (pre-release) package, change the word stable in the above URL to nightly or test. Learn about nightly and test channels.

  2. Install Docker Engine, changing the path below to the path where you downloaded the Docker package.


    $ sudo yum install /path/to/package.rpm
    BASH


    Docker is installed but not started. The docker group is created, but no users are added to the group

  3. Start Docker.


    $ sudo systemctl start docker
    BASH
  4. Verify that Docker Engine is installed correctly by running the hello-world image.


    $ sudo docker run hello-world
    BASH


    This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits

Docker Engine is installed and running. You need to use sudo to run Docker commands. Continue to Post-installation steps for Linux to allow non-privileged users to run Docker commands and for other optional configuration steps.

Upgrade Docker Engine

To upgrade Docker Engine, download the newer package file and repeat the installation procedure, using yum -y upgrade instead of yum -y install, and pointing to the new file.


Install Using the Convenience Script

Docker provides convenience scripts at get.docker.com and test.docker.com for installing edge and testing versions of Docker Engine - Community, into development environments quickly and non-interactively. The source code for the scripts is in the docker-install repository. Using these scripts is not recommended for production environments, and you should understand the potential risks before you use them:

  • The scripts require root or sudo privileges to run. Therefore, you should carefully examine and audit the scripts before running them.
  • The scripts attempt to detect your Linux distribution and version, and configure your package management system for you. In addition, the scripts do not allow you to customize any installation parameters. This may lead to an unsupported configuration, either from Docker’s point of view, or from your own organization’s guidelines and standards.
  • The scripts install all dependencies and recommendations of the package manager without asking for confirmation. This may install a large number of packages, depending on the current configuration of your host machine.
  • The script does not provide options to specify which version of Docker to install, and installs the latest version that is released in the “edge” channel.
  • Do not use the convenience script if Docker has already been installed on the host machine using another mechanism.

This example uses the script at get.docker.com to install the latest release of Docker Engine - Community on Linux. To install the latest testing version, use test.docker.com instead. In each of the commands below, replace each occurrence of get with test.

Warning:

Always examine scripts downloaded from the internet before running them locally.


$ curl -fsSL https://get.docker.com -o get-docker.sh

$ sudo sh get-docker.sh <output truncated>
BASH

If you would like to use Docker as a non-root user, you should now consider adding your user to the “docker” group with something like:

sudo usermod -aG docker your-user
BASH


Remember to log out and back in for this to take effect!


Setup Step 4: Installing Docker-Compose

Install Compose on Linux Systems

On Linux, you can download the Docker Compose binary from the Compose repository release page on GitHub. Follow the instructions from the link, which involve running the curl command in your terminal to download the binaries. These step-by-step instructions are also included below.

For alpine, the following dependency packages are needed: py-pip, python-dev, libffi-dev, openssl-dev, gcc, libc-dev, and make.

  1. Run this command to download the current stable release of Docker Compose:


    sudo curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    BASH


    To install a different version of Compose, substitute 1.26.2 with the version of Compose you want to use.

  2. Apply executable permissions to the binary:


    sudo chmod +x /usr/local/bin/docker-compose
    BASH


    Note
    : If the command docker-compose fails after installation, check your path. You can also create a symbolic link to /usr/bin or any other directory in your path.

    For example:

    sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
    

    1. Optionally, install command completion for the bash and ssh shell.

Test the installation.


$ docker-compose --version
BASH

docker-compose version 1.26.2, build 1110ad01

Setup Step 5: Open Required Ports

In computer networking, a port is a communication endpoint. At the software level, within an operating system, a port is a logical construct that identifies a specific process or a type of network service

The ports are by default open, but in case there is some firewall installed, we would require several ports to be opened in order to IDHUB function properly

List of IDHUB ports:

8443, 8888, 27017, 9200, 9300, 6379, 8091, 9091, 9097, 443, 9010, 8080, 8089, 9093, 9090, 8963, 8086, 8553, 8001, 8989, 9098, 9001, 9002, 9003, 9004, 9009, 9005, 3002, 3001, 9201, 9301, 5601, 9411, 9092, 5488
BASH

Setup Step 6: SSL Keys and Certificates

certificate contains a public key. The certificate, in addition to containing the public key, contains additional information such as issuer, what the certificate is supposed to be used for, and other types of metadata

Procure Self Signed Certificate

For Self Signed

Follow Step 1 in URL for Linux Ubuntu

OR you can use command:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/idhub-selfsigned.key -out /etc/ssl/certs/idhub-selfsigned.crt
BASH


Information only: 

  • Key will be located at /etc/ssl/private/idhub-selfsigned.key 
  • Cert is located at /etc/ssl/certs/idhub-selfsigned.crt

For Publicly Signed Certificate

For Publicly signed certificate, you would need to register with a DNS Provider

Click here for more information: Link 1 Link 2

Place Certificate in the /config/nginx Folder

Following will be the location to place the SSl key and certificate in the IDHub installed folder

/idhub-docker<version>/config/nginx/
BASH

This step is to be performed after installation of IDHub is completed. To know more, install IDHub by following steps here 

Setup Step 7: IDHub Download File

The final part of the document is the installation of the IDHub download file which can be downloaded from here.

Follow this document for the installation of the IDHub application.

Related content

Need more help?

Folks at IDHub are ready to support you.