Installing the Device Portal ============================ Create the installation directory and unpack the installation package on your target server. .. parsed-literal:: mkdir -p -m 755 /opt/conscia/install (copy onboarding_app_bundle_v\ |version|\ .tar.gz to /opt/conscia/install) cd /opt/conscia/install tar -xzvf onboarding_app_bundle_v\ |version|\ .tar.gz cd onboarding-v\ |version|\ 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. .. code-block:: text ./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`. .. code-block:: bash ./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`. .. code-block:: bash ./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. .. code-block:: bash ./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 :doc:`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: .. code-block:: text /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 :doc:`configuration section `. .. note:: Since any file starting with dot (.) is a hidden file on Linux, to see it use ``ls -a`` .. _deploy-anchor: 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 :doc:`Changelog ` page for any breaking changes, that is needed to be applied, before running the upgrade process. 1. Unpack the installation package 2. Run the script to build the new containers (build-images.sh) 3. Run the script to install the new deployment files (install.sh) 4. Optionally modify the environment file with any new parameters that have been introduced. 5. Deploy the new stack in the same way as you installed it using "./deploy.sh".