1 | # QEWD-IRIS: Running QEWD on the InterSystems IRIS Community Edition for AWS
|
2 |
|
3 | Rob Tweed <rtweed@mgateway.com>
|
4 | 22 November 2019, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com)
|
5 |
|
6 | Twitter: @rtweed
|
7 |
|
8 | Google Group for discussions, support, advice etc: [http://groups.google.co.uk/group/enterprise-web-developer-community](http://groups.google.co.uk/group/enterprise-web-developer-community)
|
9 |
|
10 | # QEWD-IRIS
|
11 |
|
12 | The instructions below explain how you can run QEWD with the InterSystems IRIS Community Edition for AWS.
|
13 |
|
14 | The instructions should be easily applied to other cloud versions of IRIS (eg Azure, Google)
|
15 |
|
16 | # Provisioning the EC2 Server
|
17 |
|
18 | On AWS, select and provision a InterSystems IRIS Community Edition EC2 instance.
|
19 |
|
20 | For testing purposes and to try QEWD out, a *t2.micro* EC2 instance will be sufficient.
|
21 |
|
22 | During the provisioning steps, configure it manually to customise the Security Group.
|
23 | Specifically, add a new Rule as follows:
|
24 |
|
25 | - Custom TCP
|
26 | - Protocol: TCP
|
27 | - Port Range: 8080-8084
|
28 | - Source: Custom 0.0.0.0/0
|
29 |
|
30 | These ports will be used by QEWD's Web Server
|
31 |
|
32 |
|
33 | # Preparing the EC2 Image
|
34 |
|
35 | Once the EC2 instance is up and running, you need to:
|
36 |
|
37 | - change your IRIS *_SYSTEM* user password
|
38 | - enable the C Callin interface
|
39 |
|
40 | The easiest way to do both steps is to start the IRIS System Management Portal.
|
41 | The first time you start this, you'll be forced to change the password for the
|
42 | *_SYSTEM* user.
|
43 |
|
44 | Make sure you change it, for now, to *secret123*
|
45 |
|
46 |
|
47 | Next, navigate the System Management Portal menus as follows:
|
48 |
|
49 |
|
50 | - System Administration
|
51 | - Security
|
52 | - Services
|
53 | - %Service_Callin: Click on the link, then:
|
54 |
|
55 | - Check the *Service Enabled* box and Click *Save*
|
56 |
|
57 |
|
58 |
|
59 |
|
60 | Next, SSH into it as the user *ubuntu*.
|
61 |
|
62 | Install *subversion*:
|
63 |
|
64 | sudo apt-get update
|
65 | sudo apt-get install -y subversion
|
66 |
|
67 |
|
68 | The IRIS container maps its internal directory */ISC* to the host
|
69 | EC2 Image's */opt/ISC* directory. So any changes we make to files and subdirectories
|
70 | on the host's */opt/ISC* directory are immediately reflected within the container.
|
71 |
|
72 | However, before we can make any changes, you'll need to change the permissions to the
|
73 | directory:
|
74 |
|
75 | sudo chown ubuntu:ubuntu /opt/ISC
|
76 |
|
77 | Now download the QEWD installation resources
|
78 |
|
79 | cd /opt/ISC
|
80 | svn export https://github.com/robtweed/qewd/trunk/docker-server-iris-ce-aws /opt/ISC/qewd-install
|
81 |
|
82 |
|
83 | # Stop the IRIS Docker Container
|
84 |
|
85 | cd /opt/ISC
|
86 | sudo docker-compose stop
|
87 |
|
88 |
|
89 | # Update the IRIS Container Docker Compose Configuration
|
90 |
|
91 | cd /opt/ISC/qewd-install
|
92 | source update_container.sh
|
93 |
|
94 |
|
95 | This replaces the IRIS Container's *docker-compose.yml* file with a new version that:
|
96 |
|
97 | - exposes port 8080 for the QEWD Web Server interface
|
98 | - changes the Container's name to qewd-iris
|
99 |
|
100 |
|
101 | # Restart the IRIS Docker Container
|
102 |
|
103 |
|
104 | Now restart the IRIS container to use the new configuration
|
105 |
|
106 | cd /opt/ISC
|
107 | sudo docker-compose up -d
|
108 |
|
109 |
|
110 | # Run the QEWD Installer / Configurator Script
|
111 |
|
112 |
|
113 | The next steps need to be done within the IRIS Container, so you need
|
114 | to shell into it. Note that you need to
|
115 | be working as the *root* user:
|
116 |
|
117 |
|
118 | sudo docker exec --user="root" -it qewd-iris bash
|
119 |
|
120 |
|
121 | You should now be in the IRIS Container's shell. Now set up the
|
122 | correct run-time environment for running QEWD:
|
123 |
|
124 |
|
125 | cd /ISC/qewd-install
|
126 | source enable_qewd.sh
|
127 |
|
128 |
|
129 | The script takes a few minutes to run, but once it completes, you can
|
130 | begin to build and run QEWD Applications
|
131 |
|
132 | You can now exit the Container's shell by typing:
|
133 |
|
134 | exit
|
135 |
|
136 |
|
137 |
|
138 | # Create a QEWD-Up Application
|
139 |
|
140 | We'll just use a simple demo application that I've created for you to test.
|
141 |
|
142 | In the host system (ie **NOT** in the Container's shell), type:
|
143 |
|
144 | svn export https://github.com/robtweed/qewd/trunk/up/examples/iris-ce-aws/simple /opt/ISC/qewd-example
|
145 |
|
146 | You'll now see a directory named */opt/ISC/qewd-example* that contains a very simple
|
147 | QEWD-Up Application definition
|
148 |
|
149 |
|
150 | # Install the QEWD Application
|
151 |
|
152 | This step only needs doing once. It installs all the Node.js modules used by QEWD.
|
153 |
|
154 | Shell into the IRIS container as *root*:
|
155 |
|
156 |
|
157 | sudo docker exec --user="root" -it qewd-iris bash
|
158 |
|
159 |
|
160 | Once you're into the container's shell, type:
|
161 |
|
162 | cd /ISC/qewd-example
|
163 | npm install
|
164 |
|
165 |
|
166 | You're now ready to start the QEWD Application
|
167 |
|
168 |
|
169 |
|
170 | # Start the QEWD Application
|
171 |
|
172 | Each time you want to start the QEWD application, first make sure you're in the IRIS container's
|
173 | shell and in the */ISC/qewd-example* directory.
|
174 |
|
175 | cd /ISC/qewd-example
|
176 |
|
177 |
|
178 | Then, start the QEWD Application by typing:
|
179 |
|
180 | npm start
|
181 |
|
182 |
|
183 | QEWD is ready for use when you see this:
|
184 |
|
185 | ========================================================
|
186 | ewd-qoper8 is up and running. Max worker pool size: 2
|
187 | ========================================================
|
188 | ========================================================
|
189 | QEWD.js is listening on port 8080
|
190 | ========================================================
|
191 |
|
192 |
|
193 |
|
194 | # Try the QEWD-Up Application's REST APIs
|
195 |
|
196 | Everthing should now be ready, so you can try out the simple demo QEWD-Up Application.
|
197 |
|
198 | If you look in the file *~/qewd-example/configuration/routes.json* you'll see that it just defines a single REST API:
|
199 |
|
200 |
|
201 | [
|
202 | {
|
203 | "uri": "/api/info",
|
204 | "method": "GET",
|
205 | "handler": "getInfo"
|
206 | }
|
207 | ]
|
208 |
|
209 | Let's try it from your browser:
|
210 |
|
211 | http://x.x.x.x:8080/api/info
|
212 |
|
213 | and you should get back a JSON response that looks something like this:
|
214 |
|
215 | {
|
216 | "info": {
|
217 | "server": "QEWD-Up Monolith",
|
218 | "arch": "x64",
|
219 | "platform": "linux",
|
220 | "versions": {
|
221 | "http_parser": "2.8.0",
|
222 | "node": "8.15.0",
|
223 | "v8": "6.2.414.75",
|
224 | "uv": "1.23.2",
|
225 | "zlib": "1.2.11",
|
226 | "ares": "1.10.1-DEV",
|
227 | "modules": "57",
|
228 | "nghttp2": "1.33.0",
|
229 | "napi": "3",
|
230 | "openssl": "1.0.2q",
|
231 | "icu": "60.1",
|
232 | "unicode": "10.0",
|
233 | "cldr": "32.0",
|
234 | "tz": "2017c"
|
235 | },
|
236 | "memory": {
|
237 | "rss": 46526464,
|
238 | "heapTotal": 18169856,
|
239 | "heapUsed": 9761680,
|
240 | "external": 177752
|
241 | }
|
242 | }
|
243 | }
|
244 |
|
245 |
|
246 | # Try the QEWD-Monitor Application
|
247 |
|
248 | Start the QEWD-Monitor application in your browser using the URL:
|
249 |
|
250 | http://x.x.x.x:8080/qewd-monitor
|
251 |
|
252 | You'll need to enter the QEWD Management password which, by default, is *keepThisSecret!*.
|
253 |
|
254 | You'll now see the Overview panel, from where you can monitor your QEWD run-time environment, view the master and worker process activity.
|
255 |
|
256 | Click the tabs in the banner to view your IRIS USER namespace Global Storage and inspect any QEWD Sessions.
|
257 |
|
258 |
|
259 | # Further Information on Developing using QEWD-Up
|
260 |
|
261 | You now have a fully-working IRIS-based QEWD-Up environment, and you can begin to try building your own applications.
|
262 |
|
263 | For further information about QEWD-Up:
|
264 |
|
265 | - [Information and background to QEWD-Up](https://github.com/robtweed/qewd/tree/master/up)
|
266 | - [Detailed QEWD-Up Documentation](https://github.com/robtweed/qewd/tree/master/up/docs)
|
267 |
|
268 |
|
269 |
|
270 | # QEWD Application Run-Time Modes
|
271 |
|
272 | ## Interactive Mode
|
273 |
|
274 | Using the *npm start* command above, the QEWD process will have started in *interactive* mode
|
275 | and you will see its log output appearing in your terminal window.
|
276 |
|
277 | In this mode you can manually start, stop and restart QEWD without having to restart the Container,
|
278 | which is ideal for QEWD-Up application development.
|
279 |
|
280 | ### Start QEWD
|
281 |
|
282 | npm start
|
283 |
|
284 | ### Stop QEWD
|
285 |
|
286 | CTRL&C
|
287 |
|
288 | or use the QEWD-Monitor application.
|
289 |
|
290 | You'll return to the *bash shell* prompt.
|
291 |
|
292 |
|
293 | ### Exit/shut down the Container
|
294 |
|
295 | exit
|
296 |
|
297 |
|
298 | ## Background Mode
|
299 |
|
300 | You can detach the QEWD process and run it as a background job by starting it as follows:
|
301 |
|
302 | nohup npm start
|
303 |
|
304 | In this mode, you can safely exit the Container's shell and the QEWD process will continue to
|
305 | run. However:
|
306 |
|
307 | - I've not been able to discover a way to monitor its output log
|
308 | - To shut down the QEWD Process, you'll need to use the QEWD Monitor application
|
309 |
|
310 |
|
311 | # Changing the IRIS and QEWD Monitor Passwords
|
312 |
|
313 | If you remember, we changed the password to *secret123*. You'll probably want to change this
|
314 | again to something more secure. If you do, you'll need to change the password used by your
|
315 | QEWD application when it connects to the IRIS Callin interface. This is specified in the
|
316 | */configuration/config.json* file, eg the one for the *qewd-example* application looks like this:
|
317 |
|
318 | {
|
319 | "qewd": {
|
320 | "poolSize": 2,
|
321 | "port": 8080,
|
322 | "database": {
|
323 | "type": "dbx",
|
324 | "params": {
|
325 | "database": "IRIS",
|
326 | "path": "/ISC/dur/mgr",
|
327 | "username": "_SYSTEM",
|
328 | "password": "secret123", <=== PASSWORD IS HERE
|
329 | "namespace": "USER"
|
330 | }
|
331 | }
|
332 | }
|
333 | }
|
334 |
|
335 |
|
336 | So, if you change your IRIS password, make sure you change your QEWD application *config.json* files
|
337 | accordingly and restart the QEWD process with *npm start*.
|
338 |
|
339 | While you're at it, you should also change your QEWD Monitor password to something more secure.
|
340 | This is also specified in the *config.json* file
|
341 |
|
342 |
|
343 | {
|
344 | "qewd": {
|
345 | "poolSize": 2,
|
346 | "managementPassword": "myNewPassword", <=== QEWD MONITOR PASSWORD IS HERE
|
347 | "port": 8080,
|
348 | "database": {
|
349 | "type": "dbx",
|
350 | "params": {
|
351 | "database": "IRIS",
|
352 | "path": "/ISC/dur/mgr",
|
353 | "username": "_SYSTEM",
|
354 | "password": "secret123",
|
355 | "namespace": "USER"
|
356 | }
|
357 | }
|
358 | }
|
359 | }
|
360 |
|