1.Prerequisites:
- Debian workstation
- Docker, Docker-compose
2.Get your MicroX, newer than 2025 version
Figure 1: MicroX generator
Go to https://www.snap4city.org/docker-generator/selecting_model (see Figure 1)
- Select “Micro X” among the available models
- Set a number of IoT-Apps (e.g., 1)
- Set the IP address of the host (e.g., 192.168.1.113)
- Click on “Fill placeholders” button
Figure 2: placeholder page
In the new page (see Figure 2),
- Set the base hostname (e.g., dashboard-113)
- Set whether to use HTTP or HTTPS protocol. Note that the automatic setup of the HTTPS protocol is still in a work-in-progress phase and could not work without additional manual intervention. We suggest keeping the HTTP protocol as set by default.
- In the right panel, use the map to select the host location
- Finally, click on “Save configuration” and then on “Download configuration”. A zip file will be downloaded.
The obtained zip file contains all the file required to install the MicroX on your workstation. This configuration includes a single organization (named, Organization) and a single Orion broker. In order to add additional organization and broker, please follow the remaining sections.
Additional information on standard MicroX deployment and installation can be found at https://www.snap4city.org/drupal/node/738.
The obtained zip file must be moved and unzipped in the workstation, the machine having the IP set in the previous steps.
In the zip file you will find:
- A placeholder_used.tsv file in which are listed all the users and passwords used for the several services included in the microX
- An <IP> folder (e.g., 192.168.1.113) containing the docker-compose.yml file together whit the setup.sh and postsetup.sh scripts, and all the folder with configuration files for the several containers used in the compose
- A checker folder [TO BE COMPLETED]
3.Add a new Orion Broker for the novel organization
In the docker-compose.yml file, new container for Orion, Orionbrokerfiler and Mongo must be created. To do this, the original code for the containers must be copied, pasted and slightly changed (for example, new names and new ports must be set). Such changes are highlighted in yellow for quick identification.
The orionbrokerfilter-001-conf folder must be copied and renamed, e.g. orionbrokerfilter-002-conf.
Finally, a new volume must be added for the novel Mongo container.
In the following we reported examples for the three containers showing the original container followed by the new one. Note that, in the case additional organizations have to be added these steps must be repeated accordingly.
Examples:
Mongo
# Original Mongo Container
mongo-001:
container_name: mongo-001
image: mongo:3.6
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 27017
target: 27017
restart: unless-stopped
volumes:
- mongodb-001:/data/db:rw
# New Mongo Container
mongo-002: # Change the container name in the compose
container_name: mongo-002 # Change the container name
image: mongo:3.6
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 27018 # Change the published port of the container
target: 27017
restart: unless-stopped
volumes:
- mongodb-002:/data/db:rw # Change the associated volume name with the name of the new volume
Orion broker
# Original Orion Container
orion-001:
command: -dbhost mongo-001
container_name: orion-001
depends_on:
mongo-001:
condition: service_started
entrypoint:
- sh
- -c
- rm /tmp/contextBroker.pid; /usr/bin/contextBroker -fg -multiservice -ngsiv1Autocast
-disableFileLog -dbhost mongo-001
image: fiware/orion:3.12.0
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 1026
target: 1026
restart: unless-stopped
# New Orion Container
orion-002: # Change the container name in the compose
command: -dbhost mongo-002 # Change the associated Mongo DB with the new one
container_name: orion-002 # Change the container name
depends_on:
mongo-002: # Change the associated Mongo DB with the new one
condition: service_started
entrypoint:
- sh
- -c
- rm /tmp/contextBroker.pid; /usr/bin/contextBroker -fg -multiservice -ngsiv1Autocast
-disableFileLog -dbhost mongo-002 # Change the associated Mongo DB with the new one
image: fiware/orion:3.12.0
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 1027 # Change the published port of the container
target: 1026
restart: unless-stopped
Orionbrokerfilter
# Original Orion Broker Filter Container
orionbrokerfilter-001:
container_name: orionbrokerfilter-001
depends_on:
orion-001:
condition: service_started
environment:
JAVA_OPTS: -DlogFileFolder=/usr/local/tomcat/logs -Dmytruststorepass=password
-Dmykeystorepass=password
connection.max: '100'
connection.timeout: '10000'
multitenancy: "false"
spring.context_broker_name: orion-1
spring.delegation_endpoint: http://dashboard-113/datamanager/api
spring.elapsingcache.minutes: '3'
spring.openidconnect.clientid: orionfilter
spring.openidconnect.password: rIp4TwG0SjbaRICl
spring.openidconnect.token_endpoint: http://dashboard-113/auth/realms/master/protocol/openid-connect/token
spring.openidconnect.username: userrootadmin
spring.organization: Organization
spring.orionbroker_endpoint: http://orion-001:1026
spring.ownership_endpoint: http://dashboard-113/ownership-api/v1/list
spring.prefix_serviceuri: http://www.disit.org/km4city/resource/iot
spring.prefixelementID: Organization:orion-1
spring.profiles.active: deploy
image: disitlab/orionbrokerfilter:v5.3
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 8443
target: 8443
restart: unless-stopped
volumes:
- ./orionbrokerfilter-001-conf:/usr/local/tomcat/credentials:rw
# New Orion Broker Filter Container
orionbrokerfilter-002: # Change the container name in the compose
container_name: orionbrokerfilter-002 # Change the container name
depends_on:
orion-002: # Change the associated Orion broker name with the new one
condition: service_started
environment:
JAVA_OPTS: -DlogFileFolder=/usr/local/tomcat/logs -Dmytruststorepass=password
-Dmykeystorepass=password
connection.max: '100'
connection.timeout: '10000'
multitenancy: "false"
spring.context_broker_name: orion-2 # Change the associated Orion broker name with the new one
spring.delegation_endpoint: http://dashboard-113/datamanager/api
spring.elapsingcache.minutes: '3'
spring.openidconnect.clientid: orionfilter
spring.openidconnect.password: rIp4TwG0SjbaRICl
spring.openidconnect.token_endpoint: http://dashboard-113/auth/realms/master/protocol/openid-connect/token
spring.openidconnect.username: userrootadmin
spring.organization: Firenze # Set the name of the new organization, in this case is Firenze
spring.orionbroker_endpoint: http://orion-002:1026 # Set the new orion endpoint (note the target port is used)
spring.ownership_endpoint: http://dashboard-113/ownership-api/v1/list
spring.prefix_serviceuri: http://www.disit.org/km4city/resource/iot
spring.prefixelementID: Firenze:orion-2 # Set the association between the new ORG and the new Orion
spring.profiles.active: deploy
image: disitlab/orionbrokerfilter:v5.3
logging:
driver: json-file
options:
max-file: '10'
max-size: 100m
ports:
- published: 8444 # Change the published port of the container
target: 8443
restart: unless-stopped
volumes:
- ./orionbrokerfilter-002-conf:/usr/local/tomcat/credentials:rw # Change the path host folder bind
Volumi
volumes:
dashboard-img: {}
dashboarddb: {}
datatable-uploads: {}
elastic-data: {}
geo-db-data: {}
geoserver-data: {}
kafka: {}
keycloak: {}
ldap_etc: {}
ldap_lib: {}
mongodb-001: {}
mongodb-002: {} # New volume for Mongo, set as the volume name used above
od-postgis-data: {}
opensearch-data: {}
poitable-uploads: {}
postgres-volume: {}
solr-data: {}
virtuoso: {}
4.Add the new Orion Broker Filer to the Nginx proxy
The new Orion Broker Filer must be mapped in the Nginx broker. In the following, as an example, a mapping of the previously created new filter is added. Nginx config file can be found in <IP>/nginx-proxy-conf/nginx.conf.
Esempio
#Original Orion Broker Filter mapping
location /orion-filter/orion-1/v2 {
proxy_pass "https://orionbrokerfilter-001:8443/orionbrokerfilter/v2";
}
location /orion-filter/orion-1/v1 {
proxy_pass "https://orionbrokerfilter-001:8443/orionbrokerfilter/v1";
}
rewrite ^/orion-filter/orion-1/?$ /orion-filter/orion-1/v2 permanent;
# New Orion Broker Filter mapping
location /orion-filter/orion-2/v2 {
proxy_pass "https://orionbrokerfilter-002:8443/orionbrokerfilter/v2";
}
location /orion-filter/orion-2/v1 {
proxy_pass "https://orionbrokerfilter-002:8443/orionbrokerfilter/v1";
}
rewrite ^/orion-filter/orion-2/?$ /orion-filter/orion-2/v2 permanent;
5.Micro X Setup
After modifying the docker-compose.yml and the nginx.conf file, we can proceed to setup of the microX.
- Run the setup.sh script
- Start the docker compose ($ docker-compose up -d)
- Run the post-setup.sh script
Note that, if docker has not been configured to be managed by non-root users (see https://docs.docker.com/engine/install/linux-postinstall/) all these commands must be run with sudo or as root.
Sometimes, error can appear during the post-setup run. This is due to the host machine not being able to recognize its hostname (e.g., dashboard-113). To solve this problem, use one of the following possible solutions:
- Change the hostname in localhost in the post-setup.sh script, otherwise
- Run the following commands using SSH from a machine able to solve the host hostname (setting the passwords as reported in the placeholder_used.tsv file):
- curl -u admin:<postgre-geo-password> -XPOST -H "Content-type: text/xml" -d "<workspace><name>traffic</name></workspace>" http://dashboard-113/geoserver/rest/workspaces
- curl -u admin:<postgre-geo-password> -XPOST -H "Content-type: text/xml" -d "<workspace><name>Snap4City</name></workspace>" http://dashboard-113/geoserver/rest/workspaces
- python3 keycloak-conf/keycloak-rest.py http://dashboard-113/auth admin <keycloak-admin-pwd>
- python3 keycloak-conf/keycloak-step-2.py
- python3 keycloak-conf/keycloak-step-2.py
Clearly, in this second option, Python interpreter and the invoked Python files must be present on the machine running the command and the
6.Create the new organization in the MicroX
At this point the Snap4City MicroX should be running and can be accessed from the url http:<base-hostname>/ (e.g. http://dashboard-113/), see Figure 3.
Figure 3: Snap4City MicroX homepage
Now, at first you must login as userrootadmin (with the associated password reported in the placeholder_used.tsv file).
Once logged-in, using the left bar menu, go to supersetting => organization manager and click on Create New Organization (see Fig. 4), and fill the form the required data. An example is provided in Fig. 5, for the Firenze organization used in the examples above.
|
Figure 4: Create new organization interface |
Figure 5: Example data for new org |
Once the organization has been created, new user must be added to it. In this case navigate to User Management and Auditing => Dashboard Builder Local Users and click on the top-right plus (+) to add new users (see Fig. 6). We suggest to at least create a rootadmin and an areamanager users for the new organization.
At first create a new admin user:
- Click on the (+)
- Fill the data in the popup form
- Select Root admin as role
- Choose the newly created organization
Once create the new rootadmin, logout and login with the new rootadmin of the new organization and to repeat these passages to create an additional user for the new organization with role Area manager.
Figure 6: Add new user interface
Note that, an email must be provided to create a new user. A dummy, fake email can work too.
7.Setup the Orion broker
The final step is the setup of the broker.
OPTIONAL: even if not required for the new organization, we suggest checking the broker also for the default organization. To do that, login with the default rootadmin (userrootadmin), go to Entity Directory and Devices -> IoT Brokers. The page should list a single broker (orion-1) for the organization Organization. Click on EDIT and then on Confirm to take possess of the broker. Next, click on MYOWNPRIVATE in the Ownership column, and in the opened popup select the Group Delegations tab, and delegate the broker to the org Organization (see Fig. 7). In this way all the user of the org Organization will be able to use the broker.
Figure 7: Broker delegation
Now, login as the new org rootadmin, go to Entity Directory and Devices -> IoT Brokers, and click on Register new IOT Broker. Then fill all the required information as shown in the example below for the org Firenze and broker orion-2, see Fig. 8. Note that the Subscription id appear after the broker registration.
Finally, delegate the broker to the new org, as describe above for the Organization org.
Figure 8: Broker registration
8.Final test
Completed all the steps, a test can be done by creating a new Entity Instance:
- Log in as areamanger of the new org
- Go to Entity Directory and Devices -> Entity Instances, IoT Devices
- Click on Add new device
- Fill all the required data in the various tabs
- Click confirm
If successful, the new device will appear in the table.
By clicking on the (+) icon near the device name, specifics of the device can be viewed. Then, by clicking on NEW DATA IN <nome device>, data can be sent to the created device.
Figure 9: Created device
