Skip to content

Commit

Permalink
Release v2.1.2
Browse files Browse the repository at this point in the history
  • Loading branch information
npeditto committed Nov 2, 2018
1 parent 1e96a6a commit 0bd4302
Show file tree
Hide file tree
Showing 30 changed files with 6,884 additions and 1,466 deletions.
3 changes: 2 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ RUN apt-get update && apt-get install -y \
git python-dev python-setuptools libyaml-dev libpython2.7-dev nmap unzip socat bridge-utils python-pip python-httplib2 libssl-dev libffi-dev \
&& rm -rf /var/lib/apt/lists/*

RUN npm install -g --unsafe @mdslab/wstun [email protected] requestify mysql nconf ip express node-uuid autobahn q body-parser ps-node nodemailer nodemailer-smtp-transport swagger-jsdoc cors bcrypt optimist jsonwebtoken \
RUN npm install -g --unsafe @mdslab/wstun [email protected] requestify mysql nconf ip express node-uuid autobahn q body-parser ps-node nodemailer nodemailer-smtp-transport swagger-jsdoc cors bcrypt optimist jsonwebtoken md5\
&& npm cache --force clean

RUN mkdir -p /var/lib/iotronic/plugins \
&& mkdir -p /var/lib/iotronic/drivers/ \
&& mkdir -p /var/lib/iotronic/.node-red/ \
&& mkdir -p /var/log/iotronic/ \
&& touch /var/log/iotronic/s4t-iotronic.log

Expand Down
2 changes: 1 addition & 1 deletion bin/server
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ nconf.file ({file: IotronicHome + '/settings.json'});

var wampR_url = nconf.get('config:wamp:url')+":"+nconf.get('config:wamp:port');
var wamp_realm = nconf.get('config:wamp:realm');
console.log(wampR_url)
//console.log(wampR_url);

var server = new iotronic.server;
server.start(wampR_url, wamp_realm);
140 changes: 108 additions & 32 deletions docs/installation_ubuntu_14.04.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ We tested this procedure on a Ubuntu 14.04 (within a LXD container also). Everyt

##### Install dependencies via apt-get
```
apt -y install python-dev python-setuptools libyaml-dev libpython2.7-dev mysql-server nmap apache2 unzip socat bridge-utils python-pip python-httplib2 libssl-dev libffi-dev
apt -y install build-essential python-dev python-setuptools libyaml-dev libpython2.7-dev mysql-server nmap apache2 unzip socat bridge-utils python-pip python-httplib2 libssl-dev libffi-dev
```

#### Install Crossbar.io router
Expand All @@ -21,17 +21,30 @@ pip install crossbar
```

##### Install latest NodeJS (and npm) distribution:
Execute the following procedures only if are not already installed:

- NodeJS installation:
```
curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
apt-get install -y nodejs
node -v
```
- NPM installation:
```
npm install -g npm
npm config set python `which python2.7`
npm -v
```
- Check if the NODE_PATH variable is not already set:
```
echo $NODE_PATH
```

otherwise, locate the global "node_modules" folder in your system ()usually in "/usr/lib/node_modules" or "/usr/local/lib/node_modules")
and edit the path in the following command:
```
echo "NODE_PATH=/usr/lib/node_modules" | tee -a /etc/environment
source /etc/environment > /dev/null
. /etc/environment > /dev/null
echo $NODE_PATH
```

Expand All @@ -41,9 +54,9 @@ You can choose to install IoTronic via NPM or from source-code via Git.

#### Install via NPM
```
npm install -g --unsafe @mdslab/iotronic-standalone
npm install -g --unsafe @mdslab/wstun
npm install -g @mdslab/wstun
npm install -g --unsafe @mdslab/iotronic-standalone
```
during the installation the procedure asks the following information:

Expand All @@ -54,7 +67,7 @@ during the installation the procedure asks the following information:

* ##### Install dependencies using npm
```
npm install -g --unsafe [email protected] requestify mysql nconf ip express node-uuid autobahn q body-parser ps-node nodemailer nodemailer-smtp-transport swagger-jsdoc cors bcrypt optimist jsonwebtoken
npm install -g --unsafe [email protected] requestify mysql nconf ip express node-uuid autobahn q body-parser ps-node nodemailer nodemailer-smtp-transport swagger-jsdoc cors bcrypt optimist jsonwebtoken md5
npm install -g --unsafe @mdslab/wstun
```
Expand All @@ -71,8 +84,8 @@ cp /usr/lib/node_modules/@mdslab/iotronic-standalone/etc/init.d/s4t-iotronic /et
chmod +x /etc/init.d/s4t-iotronic
sed -i '/^ *#/b; s%exit 0%/etc/init.d/s4t-iotronic start\nexit 0%g' /etc/rc.local
mkdir /var/lib/iotronic/drivers/
mkdir /var/lib/iotronic/plugins/
mkdir -p /var/lib/iotronic/drivers/
mkdir -p /var/log/iotronic/plugins/
echo "IOTRONIC_HOME=/var/lib/iotronic" >> /etc/environment
source /etc/environment
Expand Down Expand Up @@ -149,6 +162,7 @@ if you would like to use HTTPS to expose them you have to specify the "https" se
```
"db":{
"host":"localhost",
"port":3306,
"user":"root",
"password":"<MYSQL-PASSWORD>",
"db_name": "s4t-iotronic"
Expand All @@ -161,9 +175,13 @@ if you would like to use HTTPS to expose them you have to specify the "https" se
"email": {
"address": "<SENDER-EMAIL>",
"password": "<SENDER-PASSWORD-EMAIL>"
"smtp":{
"smtp_server": "<SMTP-MAIL-SERVER>"",
"smtp_port": "<SMTP-PORT>"",
"smtp_secure": "[ true | false ]"
}
},
"enable_notify":"[ true | false ]",
"retry":<ATTEMPTS-NUMBER>
}
```

Expand All @@ -178,7 +196,7 @@ node /usr/lib/node_modules/@mdslab/iotronic-standalone/utils/createAdminToken.js
"encryptKey": "<ENC-KEY>",
"adminToken": "<GENERATED-BEFORE>",
"backend": "iotronic",
"expire_time": 60
"expire_time": "30m"
}
```
The "encryptKey" field is a user-defined keyword/password used to encrypt/decrypt the users passwords during authentication procedures.
Expand Down Expand Up @@ -245,57 +263,115 @@ RESPONSE:


## API documentation management
IoTronic releases its APIs documentation by means of Swagger framework. In particular we used ["swagger-jsdoc"](https://www.npmjs.com/package/swagger-jsdoc) and ["swagger-ui"](https://swagger.io/swagger-ui/) respectively to describe each RESTful API in the source code and publish the produced documentation.
IoTronic releases its APIs documentation by means of Swagger framework. In particular we used ["swagger-jsdoc"](https://www.npmjs.com/package/swagger-jsdoc) and ["swagger-ui"](https://swagger.io/swagger-ui/)
respectively to describe each RESTful API in the source code and publish the produced documentation.

To use swagger-ui we need to clone the git repository from [here](https://github.com/swagger-api/swagger-ui)
and move the "dist" folder where you prefer and specify it inside the "settings.json" configuration file
as showed below:
Iotronic is able to expose the documentation:
1. embedded mode: generate and expose runtime the API documentation
2. exposed mode: only specify the URLs of the web-server that is exposing the documentation

In both cases we need to get the "swagger-ui" cloning the git repository from [here](https://github.com/swagger-api/swagger-ui)
and rename the "dist/" folder in "iotronic-api-docs/".

#### 1. Embedded mode
```
"docs": {
"enable": [ true | false ],
"path": "<SWAGGER-DIST-PATH>"
"embedded":{
"enable": true,
"path": "<SWAGGER-DIST-PATH>"
},
"exposed":{
"enable": false,
"url":"",
"url_spec":""
}
}
```
We have to move the "iotronic-api-docs/" folder in the "/var/lib/iotronic/docs/" and we need to specify it inside the
"settings.json" configuration file, as showed above, in the "path" section substituting "<SWAGGER-DIST-PATH>" variable
and setting to "true" the "enable" flag in the "embedded" section.

You have to edit the "index.html" in <SWAGGER-DIST-PATH> as described in the [official guide](https://swagger.io/docs/swagger-tools/#download-33):
The API documentation will be available at:
```
window.swaggerUi = new SwaggerUi({
url: <URL-SWAGGER-JSON>,
});
http(s)://<IOTRONIC-IP>:<HTTP(S)-API-PORT>/v1/iotronic-api-docs/ (<URL-API-DOCS>)
```
where
and the location of the Swagger JSON file will be:
```
<URL-SWAGGER-JSON> = http(s)://<IOTRONIC-IP>:<HTTP(S)-API-PORT>/<SWAGGER-JSON-LOCATION>/iotronic-swagger.json
http(s)://<IOTRONIC-IP>:<HTTP(S)-API-PORT>/v1/iotronic-swagger.json (<URL-SWAGGER-JSON>)
```

[Link to Official guide](https://swagger.io/docs/swagger-tools/#download-33)

#### Embedded API management
Enabling the above flag ("enable":true) IoTronic will generate end expose the API documentation.
#### 2. Exposed mode
```
"docs": {
"embedded":{
"enable": false,
"path": "<SWAGGER-DIST-PATH>"
},
"exposed":{
"enable": true,
"url":"<URL-API-DOCS>",
"url_spec":"<URL-SWAGGER-JSON>"
}
The docs will be available at:
}
```
In this case we have to
1. move the "iotronic-api-docs/" folder in the web-server public folder to expose the "swagger-ui" (e.g. in Apache we
have to move "iotronic-api-docs/" in "/var/www/html/");
2. generate the swagger json file "iotronic-swagger.json" executing the the script "iotronic-docs-gen.js" provided
by Iotronic in the "docs/" folder; e.g.:
```
node iotronic-docs-gen.js --iotronic=$NODE_PATH"/@mdslab/iotronic-standalone/" -e false -w /var/www/html/iotronic-api-docs/
```
For more information see the below section "Standalone API management".

3. configure the "settings.json" configuration file:
- set to "true" the "enable" flag in the "exposed" section;
- specify the urls of the documentation (<URL-API-DOCS>) and the url that exposes the "iotronic-swagger.json" file
(<URL-SWAGGER-JSON>);

The API documentation will be available at:
```
<URL-API-DOCS> = http(s)://<IOTRONIC-IP>:<HTTP(S)-API-PORT>/v1/iotronic-api-docs/
http(s)://<WEB-SERVER-URL>/iotronic-api-docs/ (<URL-API-DOCS>)
```
and the location of the Swagger JSON file will be:
```
<URL-SWAGGER-JSON> = http(s)://<IOTRONIC-IP>:<HTTP(S)-API-PORT>/v1/iotronic-swagger.json
http(s)://<WEB-SERVER-URL>/iotronic-api-docs/iotronic-swagger.json (<URL-SWAGGER-JSON>)
```


In both the cases you have to edit the "index.html" in <SWAGGER-DIST-PATH> as described in the
[official guide](https://swagger.io/docs/swagger-tools/#download-33):
```
window.swaggerUi = new SwaggerUi({
url: <URL-SWAGGER-JSON>,
});
```
[Link to Official guide](https://swagger.io/docs/swagger-tools/#download-33)




#### Standalone API management
We also provided a NodeJS script ([iotronic-docs-gen.js](iotronic-docs-gen.js)) to do that without using directly IoTronic (we need to set "enable" to false). This script will generate the documentation and will publish it by means of "swagger-ui".
We also provided a NodeJS script ([iotronic-docs-gen.js](iotronic-docs-gen.js)) to do that without using directly
IoTronic or a web-server. This script will generate the documentation and will publish it by means of "swagger-ui".

Script usage:
```
node iotronic-docs-gen.js --iotronic="<IOTRONIC_SOURCE_CODE_PATH>" -e [true|false] [ -p <API_DOCS_PORT> ]
node iotronic-docs-gen.js --iotronic="<IOTRONIC_SOURCE_CODE_PATH>" -e [true|false] [ -p <API_DOCS_PORT> ] [ -w <SWAGGER-JSON-SAVE-PATH>]
```
options:
- -i, --iotronic IoTronic suorce code path. (e.g. "/usr/lib/node_modules/@mdslab/iotronic-standalone/")
- -e, --embedded true | false to spawn API webpage documentation; if "false" the "iotronic-swagger.json" will be created in the <SWAGGER-DIST-PATH> folder specified in the "settings.json" file in the "docs" section.
- -p, --port [only with --embedded=true] Listening port. (this port has to be different from the ports used by IoTronic "http(s)_port")
- -w, --web Web server path: where will be created the swagger json file "iotronic-swagger.json".

The docs will be available at:
```
Expand Down
Loading

0 comments on commit 0bd4302

Please sign in to comment.