Installing the Device Portal¶

Create the installation directory and unpack the installation package on your target server.

mkdir -p -m 755 /opt/conscia/install
(copy onboarding_app_bundle_v2.0.3.tar.gz to /opt/conscia/install)
cd /opt/conscia/install
tar -xzvf onboarding_app_bundle_v2.0.3.tar.gz
cd onboarding-v2.0.3

Build the Docker containers¶

The Device Portal is run from Docker containers that need to be build for each release of the application. Start of by building the Docker images needed to run the current version of the app.

The build-images.sh program allows for two options. The options will be the choice of what kind of database server the portal will connect to. If your organization has an existing MS-SQL server that is to be used, the remote-db option should be selected. When running the database server locally within a Docker container managed by the application stack the local-db option is used.

Warning

If local-db is used then SA_PASSWORD must be set in .env file.

./build-images.sh --local-db
./build-images.sh --remote-db

Executing the program will create all the needed containers.

Note

Only relevant on Debian Linux: If you receive a permission denied error stating that you can’t connect to the Docker socket, be aware that by default only the root user, or members of the “docker” group are allowed access. You might need to execute the build-images.sh script using sudo.

Note

Only relevant on Fedora Linux: Sometime when downloading a docker image from the internet, Podman will ask you to select a repository

  ? Please select an image:
  registry.access.redhat.com/redis:6.0.16-alpine
  registry.redhat.io/redis:6.0.16-alpine
> docker.io/library/redis:6.0.16-alpine

Always select docker.io repository.

Default installation path for rootless Podman is /home/$USER/

Warning

Only relevant on Fedora Linux: if you prepend sudo in front of the command, then container images will be created for root user not for the current user. Podman default runs containers rootless.

Installing the required files¶

The install.sh program takes the same two parameters as the build-images.sh script and two more parameters if running under Fedora distribution, to allow podman running root or rootless. Executing the install.sh program under Debian distribution creates the required directories under /opt/conscia/onboarding along with the Docker Compose deployment file /opt/conscia/onboarding/docker-compose.yml.

./install.sh -l (when running the MS-SQL server locally within Docker)
./install.sh -r (when using an external MS-SQL database)
sudo ./install.sh --local-db (to create the folders and files as the root user)

While under Fedora distribution in rootless mode, install.sh program creates the required directories under current users home directory /home/$USER/conscia/onboarding along with the Docker Compose deployment file /home/$USER/conscia/onboarding/podman-compose.yml.

./install.sh -l -u  (when running the MS-SQL server locally within Docker)
./install.sh -r -u (when using an external MS-SQL database)

If Podman is running in root mode, then directories will be created in the same path as Debian distribution.

./install.sh -l -s  (when running the MS-SQL server locally within Docker)
./install.sh -r -s (when using an external MS-SQL database)

Certificates for the Device Portal¶

If Cisco pxGrid is used the files containing the client certificate along with the key should be copied to /opt/conscia/onboarding/certs/ise or /home/$USER/conscia/onboarding/certs/ise . The names of the pxGrid certificate and key files must match the entries in the configuration for DEVICE_ONBOARDING_ISE_PXGRID_CLIENT_CERT and DEVICE_ONBOARDING_ISE_PXGRID_CLIENT_KEY from the configuration section.

To protect the traffic between users of the portal and the portal a TLS certificate is required. The certificate file needs to have a .pem extension, with the full chain and must be named deviceportal.pem, the key file will use deviceportal.key.

Both of these files need to be in the PEM file format, and the web server needs to be able to read the key file while loading, so the file can’t be encrypted by a password.

The files to protect the web traffic should be placed under /opt/conscia/onboarding/certs/ingress or /home/$USER/conscia/onboarding/certs/ingress.

For example the required files would be:

/opt/conscia/onboarding/certs/ingress/deviceportal.pem
/opt/conscia/onboarding/certs/ingress/deviceportal.key

or in Podman rootless

/home/$USER/conscia/onboarding/certs/ingress/deviceportal.pem
/home/$USER/conscia/onboarding/certs/ingress/deviceportal.key

The ingress container will check for the existence of the application certificate files each time it starts up, so if the files are missing at the time of the installation of the application only the HTTP interface will be available. If the certificate files are added later the ingress container (or entire stack) needs to be restarted.

The backend ingress image will mount the cert folder, so if the certificates are changed (e.g. on expiry) simply copy the new certs to the relevant folders and restart the application.

Prepare an environment file¶

The installation ships with a sample .env file that needs to be modified to your environment. For a full list of options please consult the documentation’s configuration section.

Note

Since any file starting with dot (.) is a hidden file on Linux, to see it use ls -a

Deploying the Onboarding Stack¶

Once the certificates are in place and you have the environment file in order it is time to deploy the application. The deployment step is handled using the deploy.sh script found in /opt/conscia/onboarding/ or /home/$USER/conscia/onboarding/.

Note

Only relevant on Debian Linux: Remember that you might need to prepend sudo in front of the deploy.sh command.

Changing the environment variable¶

Changes to the environment variable are done by first modifying your source environment file and then running the deploy.sh script.

Note

Please be aware that changes to the application configuration will cause a restart.

Upgrading an existing portal¶

Upgrading an existing portal follows most of the same steps as installing the portal for the first time.

Warning

Remember to read Changelog page for any breaking changes, that is needed to be applied, before running the upgrade process.

Unpack the installation package
Run the script to build the new containers (build-images.sh)
Run the script to install the new deployment files (install.sh)
Optionally modify the environment file with any new parameters that have been introduced.
Deploy the new stack in the same way as you installed it using “./deploy.sh”.