In Part A, we will set up the Domino server.
In Part B, we will setup NodeJS 10.
Ubuntu 18.04 only incudes the stable version 8.10.x LTS. We will use the NodeSource PPA to install version 10.x LTS.
In Part C, we will setup IAM.
In Part D, we'll cover App demo set-up.
Part A: Set-up the Proton add-on service:
1. Download the AppDevPack: ibm_domino_V10_appdev_pack_V1.0_linux64.tar
2. Expand the tar file into its components:
- proton-addin-0.1.0-5497660.tgz
- domino-domino-db-1.0.0.tgz
- domino-appdev-docs-site.tgz
- node-demo.nsf
Note: To expand the tar, I simply double clicked it on my Mac.
3. Expand the domino-appdev-docs-site.tgz archive file.
The will create a documentation folder. I then opened index.html and actually, yes, read the documentation -- there's only a few pages for the admin side.
4. On the administrative side, the first thing to do is to add the Proton add-in.
4a. Transfer the Proton archive to the server. We used FileZilla and transferred it to tmp folder w/in our server's home folder, for staging.
$ cd /home/notes/tmp
$ cd proton-addin-n.n.n/
$ sudo cp proton-addin-n.n.n.tgz /opt/ibm/domino/notes/latest/linux/
$ cd /opt/ibm/domino/notes/latest/linux/
4b. Verify the libnotes.so file exists in the folder.
$ ls -la libnotes.so
<file will display>
4c. Uncompress the tar file to the domino "../latest/linux" program folder. You can then remove the .tgz file.
# sudo su
# tar -xvf proton*.tgz
# rm proton*.tgz
Note: This creates 4 files:
- proton
- setup_proton.sh
- make_certs.sh
- make_keyring.sh
4d. Run the setup script that set's permissions:
# sh -v ./setup_proton.sh
# mv setup_proton.sh /home/notes/tmp/
# exit
Note: Alternately, you can change the setup_proton.sh to be executable and then run directly.
4e. Confirm that the proton file is now executable and owned by root:
$ ls -l pro*
-rwxr-xr-x 1 root root 32554568 Sep 20 14:42 proton
4f. Create soft link for proton and open port 3002.
We had issues with CentOS 7 and Ubuntu 18.04 where starting proton would fail because it could not find libnotes.so.
(You cannot start proton in the /opt/ibm/domino/notes/latest/linux/proton. It fails just like the other domino executable processes.
$ cd /opt/ibm/domino/bin/
$ sudo ln -s /opt/ibm/domino/bin/tools/startup proton
$ sudo ln -s /opt/ibm/domino/bin/tools/startup kyrtool
After making proton start with the tools/startup program, we were able to start proton from the terminal and from the Domino console.
$ ufw allow proto tcp to any port 3002
$ ufw status
5. Manually start and stop proton from the Domino console to confirm proton is loading and stopping successfully.
Domino Administrator client --> <server> --> Server (tab) --> Console (left option) --> Click Live button (looks like play button) --> enter the following console command:
> load proton
... watch console and confirm it loads.
> tell proton quit
... watch console and confirm it quits.
6. Back on the server's terminal, update notes.ini to start proton w/the server.
$ sudo systemctl stop domino
$ cd /local/notesdata/
$ sudo vi notes.ini
Update the ServerTasks line adding the proton option to the end, then save (write), and exit vi (quit).
ServerTasks=Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr,CA,SMTP,HTTP,IMAP,POP3,LDAP,DOTS,PROTON
PROTON_LISTEN_ADDRESS=0.0.0.0
PROTON_LISTEN_PORT=3002
<esc><wq>
7. Move the other two certificate and keyring files to the notes tmp folder.
(We are NOT leaving all this clutter in the ../latest/linux folder.)
$ sudo mv make_certs.sh /home/notes/tmp/
$ sudo mv make_keyring.sh /home/notes/tmp/
$ cd /home/notes/tmp/
$ sudo chown notes:notes make_*.sh
$ sudo chmod 770 make_.*sh
Edit the files and update them for your environment.
Notes:
make_certs.sh
- On the second openssl call, the ca.key is misspelled ca.ket. Change it to ca.key.
- Change the days to the number of days if desired, update all the instances. You may want longer than a year. We did.
- Around line 24, update the O= to your Notes domain and make up something for the CN (e.g. O=MWNet/CN=MWProtonCA)
- Around line 40 and 41, update the O= to your Notes domain and the common name prefix of your server's FQDN (e.g. O=MWNet/CN=Proton, if my server was proton.mindwatering.net)
- Around line 39 or 40, update the server FQDN/DNS address address. (e.g. proton.mindwatering.net )
- Update the app1 and app2 CNs near the end of the file if you want something custom for the app person docs that will be created to match these certs.
make_keyring
- Add the following underneath the #Sample script ... text under the banner, around line 14.
export NOTESDATA= /local/notesdata
export NOTESBIN = /opt/ibm/domino/notes/1000000/linux
- Update the kyr and sth filenames to something more sensible around line 22 and 23.
readonly keyring=/home/notes/tmp/protonsvr.kyr
readonly sthfile=/home/notes/tmp/protonsvr.sth
Verify again that scripts are owned by notes.
$ su - notes
$ ./make_certs.sh
$ ./make_protons.sh
$ cp protonsvr.kyr /local/notesdata/
$ cp protonsvr.sth /local/notesdata/
Notes:
The kyr and sth had the notes user rw for both, and the notes group was rw for only the kyr file. It was not readable by anyone else. So the permissions looked okay.
We copied all the crt and key files from the tmp folder to our IT backup store. We also put a copy of the kyr and sth there, as well.
The app1.crt and app2.crt should match the common name of a person document. If you didn't update them, you will be creating a person named app1 (e.g. app1/MWNet).
8. Update the notes.ini to add the kyr file and enable SSL.
If you don't want restrict Proton access only to the server, and you want to authenticate, you should also add some Proton notes.ini entries, as well. Something like this (still as user notes):
$ vi /local/notesdata/notes.ini
...
PROTON_SSL=1
PROTON_KEYFILE=protonsvr.kyr
PROTON_AUTHENTICATION=client_cert
Note:
By enabling client_cert authentication, the Proton server (person doc) must use a client certificate (X509 cert) that matches the one stored in the person doc for the user.
9. Log out of the Notes user
$ exit
(This puts us back to our sudo administrative user id.)
10. Transfer/backup the crt, key files back to your admin workstation, if not done in step 7 above.
$ mkdir /home/myadmin/certs/
$ sudo mv /home/notes/tmp/*.crt /home/myadmin/certs/
$ sudo mv /home/notes/tmp/*.key /home/myadmin/certs/
$ sudo mv /home/notes/tmp/*.seq /home/myadmin/certs/
$ sudo cp /home/notes/tmp/*.kyr /home/myadmin/certs/
$ sudo cp /home/notes/tmp/*.sth /home/myadmin/certs/
11. On your regular workstation, create the App1 Person document.
a. Domino Admin Client --> People & Groups --> MWNet Directory --> People view
b. Click the Add Person button.
c. Complete the main fields on the Basic tab:
Last Name: App1
Full Name:
App1/MWNet
App1
Give it an internet password.
d. Import the certificate.
(menu) Action --> Import Internet Certificates --> navigate and select app1.crt (change selection to *.* as needed). Click Open.
Accept the dialog twice as prompted, and wait for the success message.
Click the Save & Close button.
e. Confirm the certificate is in the Person document by re-opening, and going to the Certificates (tab) --> Internet Certificates (sub tab).
12. Give a copy of app1.crt, app1.key, and ca.crt to your app developer to be included in the Node.JS apps using domino-db (AppDevPack).
Logging: (Optional)
If you have issues, you can increase the logging using the following server Notes.ini parameters.
PROTON_TRACE_REQUEST=1
PROTON_TRACE_SESSION=1
PROTON_TRACE_SEARCH=1
PROTON_TRACE_SESSION_CACHE=1
Part B: Install Node.js.
We are going to install on the same server since this machine will be for a internal production pilot.
Login to the Ubuntu server with the administrative sudo account.
Note: You can get the versions of Node.js at: https://github.com/nodesource/distributions#deb
1. Get the current LTS version of NodeJS.
$ cd /home/myadmin/tmp
$ sudo apt-get install curl
$ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
$ sudo apt-get install nodejs
2. Verify the installed version:
$ node -v
3. Add Memcache, the Node.js process manager, PM2, and the change monitor, nodemon. The first is a system package, the other two are Node.js.
$ sudo apt-get install mc
$ sudo apt-get install -g mp2 nodemon
You may want to install:
Restler - Consume REST services - you could use the Domino (DAS) REST services with this and not even use the AppDevPack for simpler Get/Post/Update/Delete calls.
Express - App framework so Node.js apps are "lighter".
Async - Handles asynchronous tasks like "promises" (Promise = do first, then second, then third, etc, and waits to start each next one).
Cron - Similar to LInux Cron or the scheduled Domino agent, it's how apps set tasks to run on schedule.
Passport - App authentication handler
Pdfkit - Generate PDFs on the fly
Part C: Install IAM
IAM allows us to use OAuth authentication tokens for our Domino Directory users.
Via scp or FileZilla:
1a. Using the myadmin id, transfer the domino-iam-service-1.0.13.tgz to the server (e.g. /home/myadmin/iam/).
$ mkdir /home/myadmin/iam/
<file transferred to this folder>
1b. Uncompress the archive:
$ cd /home/myadmin/iam/
$ tar -xvf /domino-iam-service-1.0.13.tgz
1c. Using the notes user, transfer the iam-store.ntf to /local/notesdata/.
$ sudo mv /home/myadmin/iam/template/iamstore.ntf /local/notesdata/
$ sudo chown notes:notes /local/notesdata/iamstore.ntf
2. Sign and Set-up a new app from template just transferred.
a. Sign:
Domino Administrator client --> Files tab --> Set selection to Templates only (or All Databases Types) right-click iam-store.ntf, choose Sign, in the Sign Database dialog, choose to sign by Active Server's ID, leave the what to sign on All design documents, and the Update existing signatures only (faster) option. Click Ok.
b. Create new app and set-up the ACL:
- File --> New --> Database
- Choose your Domino (proton) server, and click the OK button.
- Refresh the Files tab, right click the app (e.g. MWIAM.nsf), and select Manage ACL option.
- - Add LocalDomainServers and LocalDomainAdmins groups to the ACL afterwards with Manager Access.
- - Add a pre-existing ID for IAM, or create a new admin ID (IAM Admin and add, to the ACL with Manager access with the [_ReadAllItems] role.
c. Add the IAM app to the design catalog. Use the Domino Administration console, enter:
> load updall MWIAM.nsf -e
3. Set-up Transaction Logging if it is not installed on the server. IAM requires it.
a. Using vSphere client, select the Domino/Proton server, right-click and select Edit Settings.
In the Edit Settings dialog, click the Add Device button, select the Disk option. Make the disk at least 1 GB.
b. Add the disk to the server, by rescan, fdisk, mount, and add permanently to to fstab.
In this set-up, we have three disks, one for the OS, one for Domino, and now one for the transaction logging. The latter is /dev/sdc.
$ cat /proc/partitions
$ sudo rescan-scsi-bus.sh
(If that command doesn't exist...)
$ sudo apt-get install scsitools
$ sudo rescan-scsi-bus.sh
$ cat /proc/partitions
(Now I can see /dev/sdc. Note: If you are using physical SAS/RAID, you would need: sudo bash -c "echo1 > /sys/block/sdd/device/rescan )
$ sudo fdisk /dev/sdc
(verify the size is correct by listing the unpartitioned space)
F
(choose Primary partition that uses up all the disk, and save.)
n --> p --> 1 --> default start (2048) default end (2097151) --> w
$ sudo mkfs.ext3 /dev/sdc1/
$ mkdir local2/
$ cd /local2/
$ sudo mount /dev/sdc1 /local2/
$ sudo vi /etc/fstab
. . .
/dev/sdc1 /local/domlogs/ ext4 defaults 0 1
. . .
<esc>:wq
c: Using the Domino Administrator client, update the server document adding Transaction Logging support.
- Domino Administrator client --> Configuration --> Server (twistie on left) --> All Server Documents --> Select your Domino Proton server --> Click the Edit Server button.
- Select the Transaction Logging tab.
- Enable transaction logging, set the folder /local2, set to Circular, set to 900 MB. Click the Save and Close button.
- At the Domino console, Domino Administrator client --> Server--> Status (tab) --> Server Console (left) --> Live button (right), in the Domino Command field, enter the command below and click Send:
> rest server
4. Extend the ID Vault to the Proton server (if not created on this sever).
- Domino Administrator client --> Configuration --> Security (twistie on left) --> ID Vaults --> Select the IDVault document (in view on right) --> Expand Tools (right) --> Expand ID Vaults (lower right) --> Click Manage.
- In the Manage Notes ID Vault dialog, click Next.
- Select Manage vault replica servers, click Next.
- Click Add or Remove button.
- In the Vault Servers pop-up dialog, select Proton on the left, click the Add button to make it display on the right. Click OK to close the pop-up.
- Click Next. Confirm the action completed okay. Close the window.
5. Install the IAM dependencies and IAM. You will issue the command npm ci, the scripts will run the others installation commands.
$ cd /home/myadmin/iam/
$ sudo npm ci
If successful, you will see some install notes similar to below. In the middle is an important message: "[grpc] Success ...".
The install extracted the installation files, and entered the following commands to install the packages.
> grpc@1.19.0 install /home/myadmin/tmp/node_modules/grpc
> node-pre-gyp install --fallback-to-build --library=static_library
node-pre-gyp WARN using request for node-pre-gyp https download
[prpc] Success: "/home/myadmin/tmp/node_modules/grpc/src/node/extension_binary/mode-v64-linux-x64-glibc/grpc_node.node" is installed via remote.
> @domino/domino-db@1.20 install /home/myadmin/tmp/node_modules/@domino/domino-db
> node install.js
6. Create the IAM key file, encrypt the key, and create the CSR (certificate request), and sign the request reusing the CA from the Proton server set-up.
( I did my Proton cert set-up in the /home/notes/tmp folder. I moved them to /home/myadmin/certs/ )
$ cd /home/myadmin/certs/
a. Create the keyring:
$ sudo openssl genrsa -aes256 -out iamserver.key 2048
... enter pass phrase for iamserver.key: password123
$ sudo openssl rsa -aes256 -in iamserver.key -out rsa_encrypted_iamserver.key
... enter the pass phrase, and then the PEM pass phrase twice in the command we just entered above.
b. Create the CSR configuration file:
$ vi iamserver.cnf
[req]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
[req_distinguished_name]
countryName = Country Name - US
stateOrProvinceName = State - North Carolina
localityName = Locality - Wake Forest
organizationName = Org Name - MWNet
commonName = Common Name - proton.mindwatering.net
[req_ext]
subjectAltName = @alt_names
[alt_names]
DNS.1 = iam.mindwatering.net
DNS.2 = proton.mindwatering.local
DNS.3 = iam.mindwatering.local
<esc>:wq
$ sudo openssl req -new -out iamserver.csr -key iamserver.key -nodes -config iamserver.cnf
<enter the passphrase of the private key entered in step a above>
c. Create the iamserver.crt certificate.
Note: Update the command to the same number of days and same password you used for the original make_certs.sh file (Part A. Step 7).
$ sudo openssl x509 -passin pass:1234 -req -days 3650 -in iamserver.csr -CA ca.crt -CAkey ca.key -out iamserver.crt -CAcreateserial -CAserial ca.seq -sha256 -extfile <(printf "[SAN]\nsubjectAltName=DNS:iam.mindwatering.net") -extensions SAN
d. Create the IAMAccessor client certificate for IAM.
Note: Later we are creating a person named: IAMAccessor/MWNet. So we will enter the name in the CSR (backwards). Also, we have to update the number of days, and match the Proton script password again just like step c above. We are re-using the Proton Domino certificate and keyring (ca.crt and ca.key) again.
$ sudo openssl genrsa -des3 -out iamapp.key 4096
<enter a new password, re-enter password to verify>
$ sudo openssl req -new -key iamapp.key -out iamapp.csr -subj "/O=MWNet/CN=IAMAccessor" -sha256
$ sudo openssl x509 -passin pass:1234 -req -days 3650 -in iamapp.csr -CA ca.crt -CAkey ca.key -out iamapp.crt -CAserial ca.seq
7. Return to the Domino administrator, create the IAMAccessor/MWNet person doc, and import the iamapp.crt file.
a. Domino Admin Client --> People & Groups --> MWNet Directory --> People view
b. Click the Add Person button.
c. Complete the main fields on the Basic tab:
Last Name: IAMAccessor
Full Name:
IAMAccessor/MWNet
IAMAccessor
Give it an internet password.
d. Import the certificate.
(menu) Action --> Import Internet Certificates --> navigate and select iamapp.crt (change selection to *.* as needed). Click Open.
Accept the dialog twice as prompted, and wait for the success message.
Click the Save & Close button.
e. Confirm the certificate is in the Person document by re-opening, and going to the Certificates (tab) --> Internet Certificates (sub tab).
8. Copy the certs to the install config folder for IAM.
$ cp /home/myadmin/certs/iamapp.crt /home/myadmin/iam/config/certs/
$ cp /home/myadmin/certs/iamapp.key /home/myadmin/iam/config/certs/
$ cp /home/myadmin/certs/iamserver.key /home/myadmin/iam/config/certs/
$ cp /home/myadmin/certs/iamserver.crt /home/myadmin/iam/config/certs/
$ cp /home/myadmin/certs/ca.crt /home/myadmin/iam/config/certs/ca/
9. Run the IAM set-up.
Note: If you have load balancers, then you would put their address for IAM Service ISSUER section below. Include port if 443 is in use already.
$ cd /home/myadmin/iam/
$ sudo npm run setup
( The next lines are answering questions... )
Welcome to IAM Setup
? Choose setup mode Production
> Production
> Pilot
? IAM Admin username: admin
? Enter IAM Admin password: <enterdesiredpassword>
? Enter IAM Admin password again: <enterdesiredpassword>
Admin password is set successfully
? Enter IAM server password: <enteredsamepasswordasforitscrtfile>
? Enter IAM server password again: <enteredsamepasswordasforitscrtfile>
Server password is set successfully
? IAM Service ISSUER: https://proton.mindwatering.net:6443
? Confirm? Yes
About to config Address Settings.
? IAM service's host: [default]
? IAM service's port: 6443
? Admin service's host: [default]
? Admin service's port: 8443
Following configurations have been input for Address Settings --
IAM service's host - [default]
IAM service's port - 6443
ADMIN service's host - [default]
ADMIN service's port - 8443
? Confirm? (Y/n) Y
About to config SSL Settings.
? IAM server's SSL key file path: iamserver.key
? Server's SSL key password: <enterkeyringpassword>
? Server's SSL cert file path: iamserver.crt
Following configuration have been input for SSL Settings --
IAM server's SSL key file path - config/certs/iamserver.key
Server's SSL key password - ***
Server's SSL cert file path - config/certs/iamserver.crt
? Confirm? Y
About to config Storage Settings.
? Hostname of the Domino server: proton.mindwatering.net
? Domino's Proton service port: 3002
? IAM's storage nsf file path, a relative path to Domino data path: MWIAM.nsf
? IAM's Proton client cert key file path (relative to 'config/certs' folder): iamapp.key
? The key file's protection passphrase: <enterkeyringpassword>
? IAM's Proton client cert file path (relative to 'config/certs' folder): iamapp.crt
? The cert's bounded functional ID's Notes password: <entercertpassword>
Following configuration have been input for Storage Settings --
Domino server hostname - proton.mindwatering.net
Domino Proton service port - 3002
Storage nsf file - MWIAM.nsf
key for the client cert - config/cert/iamapp.key
The key file's protection passphrase: - ***
Domino Proton client cert - config/certs/iamapp.crt
Functional ID's Notes password - ***
? Confirm? Y
? Do you want to change some configuration? No
10. Run the IAM Server.
$ sudo npm start
11. Set-up the LDAP configuration to Domino (Proton).
a . Set-up the LDAP (IDP) password.
Open your web browser, enter https://proton.mindwatering.net:8443. At the self-certification warning, continue/accept anyway. Login using "admin" and the password entered at the start of the IAM set-up.
Click the Configuration option in the left menu.
On the Identity Provider Configuration page, enter the following:
URL: ldaps://proton.mindwatering.com:636
Search base DN: O=MWNet
Search field: mail
(left at default)
Bind DN: cn=iamaccessor,o=mwnet
Password: <enter the person doc password>
Test user: anotheremailindirectory@mindwatering.net
Click the Verify button.
If it verifies okay, click the Save button.
b. Restart IAM.
Back in the myadmin terminal window:
$ <cntl+c>
Since we might want to not leave up a terminal window or remote SSH session forever, we can use screen to keep IAM running.
$ apt-get install screen
$ screen
$ npm start
<enter the IAM password>
... wait till the server is loaded ...
<ctrl+a> --> d
Note:
To get back to that screen, login as the myadmin user again, and recall the screen session with:
$ screen -r
Then just kill it with <cntl+c>
Part D: Test App.
1. Using the IAM management program, create a server-side application.
- Login to IAM with "admin" and it's password.
- On the Dashboard, click Manage Applications.
- Click + Create. Complete as following:
- - Application Type: Server-Side application
- - Application Name: IAMClientTst
- - Application homepage URL: https://proton.mindwatering.net
- - Application callback URL: https://proton.mindwatering.net/cb
- - Application description: IAM Client test app.
- - Click Save.
- Once the app is saved, we can view it again to see the App id and the App secret. We also need the URL and callback URL.
(I retrieved those URLs from the config.js file in the app files. We'll go over it in step 3 and 4 below.)
2. Transfer the test application.
On our Mac workstation, we uncompressed the node-iam-client-1.1.1.package. This creates a folder named package.
We renamed the folder package to iamclient111test, and transferred it to the Proton Domino server.
3. Run the npm test / demo app.
$ cd /home/myadmin/iamclient111test/
We ran the npm and found that the test demo app had dependencies on kao packages.
$ cd examples/
$ vi authorization_code_flow/config.js
<esc> :q!
There we found that the app has missing modules which are required. The index.js requires koa, koa-body, koa-router, koa-session, koa-ejs, and uuid. The config.js also requires got. loader.js requires openid-client.
$ nmp install koa koa-body koa-router koa-session koa-ejs uuid got openid-client
Notes:
At the end of the koa installs. We received two warnings regarding "@domino/node-iam-client@1.1.1 No repository field" and "@domino/node-iam-client@1.1.1 No license field". The app doesn't have its download location and its license terms. It can be ignored.
4. Update the app index.js file to its current install.
The documentation said nothing about updating the main index.js. Sure enough, running printed out a message saying to "provide your specific IAM settings in /home/myadmin/iamclient111test/examples/authorization_code_flow/config.js before executing this example".
$ vi authorization_code_flow/config.js
. . .
iam_server: 'https://proton.mindwatering.net:6443',
. . .
iam_server_ca_cert: '/home/myadmin/iam/config/certs/ca/ca.crt',
. . .
client_id: '1235123-12423-123512-123532-1235',
client_secret: 'sadf2151235sdafadsf23151235sdaadfadf21125234dsafdsfljklj',
. . .
redirect_url: 'https://proton.mindwatering.net:3002/cb',
. . .
<esc> :wq
Part E: Apps.
1. Create the Notes.JS project.
2. Add the domino-db certs and archive to the project:
Make a certs folder within the project, and add the app1.crt, app1.key, and ca.crt files.
To the vendor folder, add the domino-domino-db.1.2.x.tgz archive file.
Create the DQL design catalog app:
Create the DQL catalog by adding any application to it. (There is a demo app included with the AppDevPack if you aren't creating your own version of "hello world".)
e.g. Open the console and use the command below to add the MWApp.nsf app to the catalog, and create the catalog if it doesn't exist.
> load updall MWApp.nsf -e
The result should be similar to below.
10/31/2018 03:12:18 PM Index update process started: MWApp.nsf -e
10/31/2018 03:12:18 PM Updating views in /local/notesdata/MWApp.nsf
10/31/2018 03:12:18 PM On setting preserved for Database Option: LARGE_UNKTABLE for database /local/notesdata/GQFDsgn.cat
10/31/2018 03:12:18 PM 0 catalog documents removed, 10 view designs catalogued out of 15 total with 42 collations in 50.123 msecs
10/31/2018 03:12:18 PM Index update process shutdown
previous page
|