Installation option 1 & 2

The following instructions describe how to deploy Prelude with option 1 or 2 on a single host.

Note

If you are installing the demo version of Prelude, you won't need the registry account

Before starting, make sure :

your host is matching the minimum requirements
docker and docker compose are installed (Docker Installation Guide)
you have your registry account credentials (if you don't have an Arolo registry account, contact us)
downloading Cisco NSO 6.1 container from cisco.com

Note

For the demo version of Prelude, you can get Cisco NSO trial version from NSO website.

You are ready to start !

The following guide is considering that you are installing Prelude in the /opt/prelude folder.

Validate registry authentication

If you are not installing the demo version of Prelude, start by validating that you can connect to Arolo container registry.

docker login registry.arolo-solutions.com

Then, enter you username and password. If authentication failed, please contact us.

Get installation boilerplate

We are providing ready to use docker and config files, get them from gitlab.com

cd /opt
sudo git clone https://gitlab.com/arolo-solutions/prelude-aio-installation
mv prelude-aio-installation prelude
cd prelude

And you might end up with the following folder tree in /opt:

└── prelude
    ├── docker-compose.yml
    ├── gateway.env
    ├── gateway-config.json
    ├── oneboard.env
    ├── oneboard-config.json
    ├── ssl/
    └── volumes
        ├── gateway-db/
        ├── gateway-storage/
        ├── nats
        │   └── nats-server.conf
        ├── nso/
        ├── oneboard-db/
        └── oneboard-storage/

Config variables

In order to set up your environment, you need to replace in the config files the following variables:

domain-cert-file The name of the cert & key files for HTTPS (by default, these files should be in /opt/prelude/ssl)
gateway-postgre-password Random string of at least 32 characters to authenticate on the gateway database
host-fqdn The Fully Qualified Domain Name of the host. It must match with the TLS certificate
host-ip The IP address of the host. In case of option 2 installation, use the southbound interface IP
nats-gateway-user-key and nats-gateway-secret-key Gateway keys to authenticate with NATS. Generate nkeys guide
nats-oneboard-user-key and nats-oneboard-secret-key OneBoard keys to authenticate with NATS. Generate nkeys guide
oneboard-postgre-password Random string of at least 32 characters to authenticate on the oneboard database
prelude-key Random string of 16 characters to authenticate between Prelude components. It must be the same on for all components of the same Prelude instance

These variables have to be replaced in the following files:

gateway.env gateway-postgre-password
gateway-config.json domain-cert-file, gateway-postgre-password, host-fqdn, host-ip & prelude-key
gateway-seed.txt nats-gateway-secret-key
oneboard.env oneboard-postgre-password
oneboard-config.json domain-cert-file, host-fqdn, oneboard-postgre-password & prelude-key
oneboard-seed.txt nats-oneboard-secret-key
volumes/nats/nats-server.conf nats-gateway-user-key & nats-oneboard-user-key

Installation option 2 config

To get the installation option 2 up and running, you need to do additional change to the configuration.

In the gateway-config.json file, in the gweb.routers section, you need to change the HTTP server listening address:

Router default replace 0.0.0.0:4020 by <northbound-ip>:4020
Router file-server replace 0.0.0.0:4021 by <southbound-ip>:4021

This will make sure, that you can't access the southbound API from northbound interface and vice versa.

Select Prelude version

The docker compose file is ready to use for the Prelude demo version installation. To install your production version, replace the image's name by the one that your Arolo contact shared with you.

Make sure that the docker-compose.yml file is using the latest version of Prelude or the one you want to install, here v1.2.

For Prelude demo version install

services:
  ...
  oneboard:
    image: registry.arolo-solutions.com/self-test/prelude-oneboard:1.2
  ...
  gateway:
    image: registry.arolo-solutions.com/self-test/prelude-gateway:1.2
  ...

For Prelude production install

services:
  ...
  oneboard:
    image: registry.arolo-solutions.com/<customer>/prelude-<customer>-oneboard:1.2
  ...
  gateway:
    image: registry.arolo-solutions.com/prelude/prelude-gateway:1.2
  ...

Finally, pull all the containers images:

docker compose pull

Make sure, that all images have been pulled, except for NSO.

$ docker compose pull
[+] Pulling 6/6
 ✔ gateway-db Skipped - Image is already being pulled by oneboard-db
 ✔ oneboard-db Pulled
 ✔ gateway Pulled
 ✔ nats Pulled
 ✔ oneboard Pulled
 ! nso Warning

The following error message is expected:

pull access denied for cisco-nso-prod, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

Setup Cisco NSO

You will have to adapt the NSO version to the one you got from Cisco.

Extract NSO image and load it in docker local registry:

cd ~
sh nso-6.1.12.container-image-prod.linux.x86_64.signed.bin
docker load -i nso-6.1.12.container-image-prod.linux.x86_64.tar.gz
cd /opt/prelude

Prepare NSO configuration files. This will create the NSO admin user with the given password. You will need this password to configure the NSO connector oin OneBoard.

docker run -itd --name cisco-nso \
-v /opt/prelude/volumes/nso-logs:/log \
-e ADMIN_USERNAME=admin \
-e ADMIN_PASSWORD='<admin-password>' \
cisco-nso-prod:6.1.12

sudo docker cp cisco-nso:/nso ./volumes/
sudo docker cp cisco-nso:/etc/ncs/ncs.conf ./ncs.conf

docker kill cisco-nso
docker rm cisco-nso

Edit NSO configuration file /opt/prelude/ncs.conf to move from pam authentication to local authentication and enable NETCONF northbound API :

<aaa>
  <pam>
    <enabled>false</enabled>
    <service>system-auth</service>
  </pam>

  <local-authentication>
    <enabled>true</enabled>
  </local-authentication>
</aaa>
<netconf-north-bound>
  <enabled>true</enabled>

  <transport>
    <ssh>
      <enabled>true</enabled>
      <ip>0.0.0.0</ip>
      <port>2022</port>
    </ssh>
  </transport>
</netconf-north-bound>

In the same file, add the auto-wizard setting at the end of the xml:

<auto-wizard>
  <enabled>false</enabled>
</auto-wizard>

Copy Prelude NSO packages in the NSO folder:

sudo cp /home/user/ncs-6.1-prelude-*-1.0.tar.gz /opt/prelude/volumes/nso/run/packages

To get the Prelude NSO packages, please contact us.

The same is needed for the NEDs, that you can get from Cisco or the NSO website for the NSO trial version

Run Prelude

cd /opt/prelude
docker compose up -d
docker compose ps

Expected output :

NAME                    IMAGE                     COMMAND                  SERVICE       CREATED       STATUS                 PORTS
prelude-gateway-db-1    postgres:16.1-alpine      "docker-entrypoint.s…"   db-gateway    6 hours ago   Up 6 hours             5432/tcp
prelude-oneboard-db-1   postgres:16.1-alpine      "docker-entrypoint.s…"   db-oneboard   6 hours ago   Up 6 hours             5432/tcp
prelude-nats-1          nats:2.10-linux           "/nats-server -c /et…"   nats          6 hours ago   Up 6 hours             6222/tcp, 0.0.0.0:4222->4222/tcp, [::]:4222->4222/tcp, 8222/tcp
prelude-nso-1           cisco-nso-prod:6.1.12     "/run-nso.sh"            nso           6 hours ago   Up 6 hours (healthy)   0.0.0.0:2022->2022/tcp, [::]:2022->2022/tcp

Migrate the database models :

docker compose run --entrypoint="/app/prelude-oneboard migrate" oneboard
docker compose run --entrypoint="/app/prelude-gateway migrate" gateway
docker compose up -d --remove-orphans

Expected output :

NAME                    IMAGE                                                        COMMAND                  SERVICE       CREATED       STATUS                 PORTS
prelude-db-gateway-1    postgres:16.1-alpine                                         "docker-entrypoint.s…"   db-gateway    6 hours ago   Up 6 hours             5432/tcp
prelude-db-oneboard-1   postgres:16.1-alpine                                         "docker-entrypoint.s…"   db-oneboard   6 hours ago   Up 6 hours             5432/tcp
prelude-gateway-1       registry.arolo-solutions.com/self-test/prelude-gateway:1.2   "/app/prelude-gatewa…"   gateway       6 hours ago   Up 6 hours             0.0.0.0:67->67/udp, [::]:67->67/udp, 0.0.0.0:4020-4021->4020-4021/tcp, [::]:4020-4021->4020-4021/tcp
prelude-nats-1          nats:2.10-linux                                              "/nats-server -c /et…"   nats          6 hours ago   Up 6 hours             6222/tcp, 0.0.0.0:4222->4222/tcp, [::]:4222->4222/tcp, 8222/tcp
prelude-nso-1           cisco-nso-prod:6.1.12                                        "/run-nso.sh"            nso           6 hours ago   Up 6 hours (healthy)   0.0.0.0:2022->2022/tcp, [::]:2022->2022/tcp
prelude-prelude-1       registry.arolo-solutions.com/self-test/prelude-oneboard:1.2  "/app/prelude-oneboa…"   prelude       6 hours ago   Up 6 hours             0.0.0.0:443->443/tcp, [::]:443->443/tcp, 0.0.0.0:4010->4010/tcp, [::]:4010->4010/tcp

Create Prelude OneBoard superuser:

docker compose exec -it prelude /app/prelude-oneboard user create -u admin -e john.doe@arolo-solutions.com -p <password>

Open https://host-fqdn/ in your web browser and try to log in with the superuser credentials.

Initial Configuration

Finally, you need to register Cisco NSO connector and Prelude Gateway connector in Prelude OneBoard.

Success

Congratulations, you are now ready to enjoy Prelude features !!