@goldstack/template-lambda-http-cli 0.5.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -0
- package/bin/template +12 -0
- package/bin/template.ts +6 -0
- package/dist/scripts/generateSchemas.d.ts +2 -0
- package/dist/scripts/generateSchemas.d.ts.map +1 -0
- package/dist/scripts/generateSchemas.js +5 -0
- package/dist/scripts/generateSchemas.js.map +1 -0
- package/dist/src/templateLambdaHttp.d.ts +3 -0
- package/dist/src/templateLambdaHttp.d.ts.map +1 -0
- package/dist/src/templateLambdaHttp.js +56 -0
- package/dist/src/templateLambdaHttp.js.map +1 -0
- package/dist/src/types/LambdaHttpPackage.d.ts +61 -0
- package/dist/src/types/LambdaHttpPackage.d.ts.map +1 -0
- package/dist/src/types/LambdaHttpPackage.js +3 -0
- package/dist/src/types/LambdaHttpPackage.js.map +1 -0
- package/docs/index.html +970 -0
- package/docs/template-configure.html +66 -0
- package/docs/template.html +106 -0
- package/package.json +83 -0
package/docs/index.html
ADDED
|
@@ -0,0 +1,970 @@
|
|
|
1
|
+
<p></p>
|
|
2
|
+
<div class="markdown-fragment">
|
|
3
|
+
<p>
|
|
4
|
+
Goldstack's Lambda Express module provides a basic Express.js server that is
|
|
5
|
+
deployed as an AWS lambda function.
|
|
6
|
+
</p>
|
|
7
|
+
</div>
|
|
8
|
+
<p></p>
|
|
9
|
+
<h2 class="heading">
|
|
10
|
+
<span id="features"></span><a href="#features">Features</a
|
|
11
|
+
><span class="permalink"
|
|
12
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
13
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
14
|
+
<path
|
|
15
|
+
fill="none"
|
|
16
|
+
stroke-linecap="round"
|
|
17
|
+
stroke-linejoin="round"
|
|
18
|
+
stroke-miterlimit="10"
|
|
19
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
20
|
+
></path>
|
|
21
|
+
<path
|
|
22
|
+
fill="none"
|
|
23
|
+
stroke="#000000"
|
|
24
|
+
stroke-linecap="round"
|
|
25
|
+
stroke-linejoin="round"
|
|
26
|
+
stroke-miterlimit="10"
|
|
27
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
28
|
+
></path>
|
|
29
|
+
</g></svg
|
|
30
|
+
></span>
|
|
31
|
+
</h2>
|
|
32
|
+
<p></p>
|
|
33
|
+
<div class="markdown-fragment">
|
|
34
|
+
<ul>
|
|
35
|
+
<li>Express.js server running on AWS Lambda</li>
|
|
36
|
+
<li>Very low cost, scalability out of the box</li>
|
|
37
|
+
<li>
|
|
38
|
+
Server packaged up using Webpack for small deployment size and quick
|
|
39
|
+
on-demand start in Lambda
|
|
40
|
+
</li>
|
|
41
|
+
<li>All infrastructure defined in Terraform, easy to change and extend</li>
|
|
42
|
+
<li>Infrastructure easily rolled out with dedicated npm script</li>
|
|
43
|
+
<li>Deployment automated using Node.js module</li>
|
|
44
|
+
<li>TypeScript, ESLint and Prettier configured</li>
|
|
45
|
+
</ul>
|
|
46
|
+
</div>
|
|
47
|
+
<p></p>
|
|
48
|
+
<h2 class="heading">
|
|
49
|
+
<span id="configure"></span><a href="#configure">Configure</a
|
|
50
|
+
><span class="permalink"
|
|
51
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
52
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
53
|
+
<path
|
|
54
|
+
fill="none"
|
|
55
|
+
stroke-linecap="round"
|
|
56
|
+
stroke-linejoin="round"
|
|
57
|
+
stroke-miterlimit="10"
|
|
58
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
59
|
+
></path>
|
|
60
|
+
<path
|
|
61
|
+
fill="none"
|
|
62
|
+
stroke="#000000"
|
|
63
|
+
stroke-linecap="round"
|
|
64
|
+
stroke-linejoin="round"
|
|
65
|
+
stroke-miterlimit="10"
|
|
66
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
67
|
+
></path>
|
|
68
|
+
</g></svg
|
|
69
|
+
></span>
|
|
70
|
+
</h2>
|
|
71
|
+
<p></p>
|
|
72
|
+
<div class="markdown-fragment">
|
|
73
|
+
<p>The following key properties need to be configured for this module:</p>
|
|
74
|
+
<ul>
|
|
75
|
+
<li>
|
|
76
|
+
<strong>Lambda Name</strong>: The
|
|
77
|
+
<a
|
|
78
|
+
href="https://docs.aws.amazon.com/lambda/latest/dg/API_CreateFunction.html#SSS-CreateFunction-request-FunctionName"
|
|
79
|
+
class="absolute"
|
|
80
|
+
target="_blank"
|
|
81
|
+
rel="noopener noreferrer"
|
|
82
|
+
>name</a
|
|
83
|
+
>
|
|
84
|
+
to be used for this lambda. Lambda names need to be unique for the AWS
|
|
85
|
+
Region. It is not possible to have two lambdas with the same name in the
|
|
86
|
+
same region.
|
|
87
|
+
</li>
|
|
88
|
+
<li>
|
|
89
|
+
<strong>API Domain</strong>: The domain where the API should be deployed
|
|
90
|
+
to. For instance, to be able to call the API endpoint
|
|
91
|
+
<code class="inline">https://api.mydomain.com/</code> the API domain
|
|
92
|
+
<code class="inline">api.mydomain.com</code> needs to be configured.
|
|
93
|
+
</li>
|
|
94
|
+
<li>
|
|
95
|
+
<strong>Hosted Zone Domain</strong>: A Route 53 hosted zone that will
|
|
96
|
+
allow adding the <em>API Domain</em> as a record. For instance, in order
|
|
97
|
+
to configure the API domain <code class="inline">api.mydomain.com</code>,
|
|
98
|
+
the hosted zones <code class="inline">api.mydomain.com</code> or
|
|
99
|
+
<code class="inline">mydomain.com</code> would be valid. For more details,
|
|
100
|
+
please check
|
|
101
|
+
<a
|
|
102
|
+
href="https://docs.goldstack.party/docs/goldstack/configuration#hosted-zone-configuration"
|
|
103
|
+
class="absolute"
|
|
104
|
+
target="_blank"
|
|
105
|
+
rel="noopener noreferrer"
|
|
106
|
+
>Hosted Zone Configuration</a
|
|
107
|
+
>
|
|
108
|
+
in the Goldstack documentation.
|
|
109
|
+
</li>
|
|
110
|
+
<li>
|
|
111
|
+
<strong>CORS Header</strong>: An optional CORS header to enable a UI that
|
|
112
|
+
is hosted on a different domain to access this API. For instance, for a UI
|
|
113
|
+
that is deployed to the domain
|
|
114
|
+
<code class="inline">ui.mydomain.com</code> the CORS header
|
|
115
|
+
<code class="inline">https://ui.mydomain.com</code> should be supplied. To
|
|
116
|
+
learn more about CORS, see the
|
|
117
|
+
<a
|
|
118
|
+
href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"
|
|
119
|
+
class="absolute"
|
|
120
|
+
target="_blank"
|
|
121
|
+
rel="noopener noreferrer"
|
|
122
|
+
>Cross-Origin Resource Sharing (CORS)</a
|
|
123
|
+
>
|
|
124
|
+
in the MDN docs.
|
|
125
|
+
</li>
|
|
126
|
+
</ul>
|
|
127
|
+
</div>
|
|
128
|
+
<p></p>
|
|
129
|
+
<h2 class="heading">
|
|
130
|
+
<span id="getting-started"></span
|
|
131
|
+
><a href="#getting-started">Getting Started</a
|
|
132
|
+
><span class="permalink"
|
|
133
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
134
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
135
|
+
<path
|
|
136
|
+
fill="none"
|
|
137
|
+
stroke-linecap="round"
|
|
138
|
+
stroke-linejoin="round"
|
|
139
|
+
stroke-miterlimit="10"
|
|
140
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
141
|
+
></path>
|
|
142
|
+
<path
|
|
143
|
+
fill="none"
|
|
144
|
+
stroke="#000000"
|
|
145
|
+
stroke-linecap="round"
|
|
146
|
+
stroke-linejoin="round"
|
|
147
|
+
stroke-miterlimit="10"
|
|
148
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
149
|
+
></path>
|
|
150
|
+
</g></svg
|
|
151
|
+
></span>
|
|
152
|
+
</h2>
|
|
153
|
+
<p></p>
|
|
154
|
+
<div class="markdown-fragment">
|
|
155
|
+
<p></p>
|
|
156
|
+
<div class="markdown-fragment">
|
|
157
|
+
<h3 class="heading">
|
|
158
|
+
<span id="infrastructure-2"></span
|
|
159
|
+
><a href="#infrastructure-2"
|
|
160
|
+
><span id="infrastructure-1"></span
|
|
161
|
+
><a href="#infrastructure-1" class="relative"
|
|
162
|
+
><span id="infrastructure"></span></a
|
|
163
|
+
><a href="#infrastructure" class="relative">Infrastructure</a
|
|
164
|
+
><span class="permalink"
|
|
165
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
166
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
167
|
+
<path
|
|
168
|
+
fill="none"
|
|
169
|
+
stroke-linecap="round"
|
|
170
|
+
stroke-linejoin="round"
|
|
171
|
+
stroke-miterlimit="10"
|
|
172
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
173
|
+
></path>
|
|
174
|
+
<path
|
|
175
|
+
fill="none"
|
|
176
|
+
stroke="#000000"
|
|
177
|
+
stroke-linecap="round"
|
|
178
|
+
stroke-linejoin="round"
|
|
179
|
+
stroke-miterlimit="10"
|
|
180
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
181
|
+
></path>
|
|
182
|
+
</g></svg></span
|
|
183
|
+
><span class="permalink"
|
|
184
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
185
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
186
|
+
<path
|
|
187
|
+
fill="none"
|
|
188
|
+
stroke-linecap="round"
|
|
189
|
+
stroke-linejoin="round"
|
|
190
|
+
stroke-miterlimit="10"
|
|
191
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
192
|
+
></path>
|
|
193
|
+
<path
|
|
194
|
+
fill="none"
|
|
195
|
+
stroke="#000000"
|
|
196
|
+
stroke-linecap="round"
|
|
197
|
+
stroke-linejoin="round"
|
|
198
|
+
stroke-miterlimit="10"
|
|
199
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
200
|
+
></path>
|
|
201
|
+
</g></svg></span></a
|
|
202
|
+
><span class="permalink"
|
|
203
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
204
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
205
|
+
<path
|
|
206
|
+
fill="none"
|
|
207
|
+
stroke-linecap="round"
|
|
208
|
+
stroke-linejoin="round"
|
|
209
|
+
stroke-miterlimit="10"
|
|
210
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
211
|
+
></path>
|
|
212
|
+
<path
|
|
213
|
+
fill="none"
|
|
214
|
+
stroke="#000000"
|
|
215
|
+
stroke-linecap="round"
|
|
216
|
+
stroke-linejoin="round"
|
|
217
|
+
stroke-miterlimit="10"
|
|
218
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
219
|
+
></path>
|
|
220
|
+
</g></svg
|
|
221
|
+
></span>
|
|
222
|
+
</h3>
|
|
223
|
+
<p>
|
|
224
|
+
The first thing we recommend to do with a new module is to stand up the
|
|
225
|
+
infrastructure for the module. For this, find the directory for this
|
|
226
|
+
module in the <code class="inline">packages/</code> folder and navigate to
|
|
227
|
+
this folder in the command line. Then identify the name of the deployment
|
|
228
|
+
you have defined in the Goldstack configuration tool. This can be found in
|
|
229
|
+
the <code class="inline">packages/[moduleName]/goldstack.json</code> file.
|
|
230
|
+
Look for the <code class="inline">"deployments"</code> property and there
|
|
231
|
+
for the <code class="inline">"name"</code> of the first deployment. The
|
|
232
|
+
name should either be <code class="inline">dev</code> or
|
|
233
|
+
<code class="inline">prod</code>.
|
|
234
|
+
</p>
|
|
235
|
+
<p>In order to stand up the infrastructure, run the following command:</p>
|
|
236
|
+
<pre
|
|
237
|
+
class="language-bash language-bash language-bash"
|
|
238
|
+
><code class="language-bash"><span class="token function">yarn</span> infra up <span class="token punctuation">[</span>deploymentName<span class="token punctuation">]</span>
|
|
239
|
+
</code></pre>
|
|
240
|
+
<p>
|
|
241
|
+
This will be either <code class="inline">yarn infra up dev</code> or
|
|
242
|
+
<code class="inline">yarn infra up prod</code> depending on your choice of
|
|
243
|
+
deployment. Note that running this command can take a while.
|
|
244
|
+
</p>
|
|
245
|
+
</div>
|
|
246
|
+
<p></p>
|
|
247
|
+
<p>
|
|
248
|
+
Note that your API will not work yet. It first needs to be deployed as per
|
|
249
|
+
instructions below.
|
|
250
|
+
</p>
|
|
251
|
+
<p></p>
|
|
252
|
+
<div class="markdown-fragment">
|
|
253
|
+
<h3 class="heading">
|
|
254
|
+
<span id="deployment-2"></span
|
|
255
|
+
><a href="#deployment-2"
|
|
256
|
+
><span id="deployment-1"></span
|
|
257
|
+
><a href="#deployment-1" class="relative"
|
|
258
|
+
><span id="deployment"></span></a
|
|
259
|
+
><a href="#deployment" class="relative">Deployment</a
|
|
260
|
+
><span class="permalink"
|
|
261
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
262
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
263
|
+
<path
|
|
264
|
+
fill="none"
|
|
265
|
+
stroke-linecap="round"
|
|
266
|
+
stroke-linejoin="round"
|
|
267
|
+
stroke-miterlimit="10"
|
|
268
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
269
|
+
></path>
|
|
270
|
+
<path
|
|
271
|
+
fill="none"
|
|
272
|
+
stroke="#000000"
|
|
273
|
+
stroke-linecap="round"
|
|
274
|
+
stroke-linejoin="round"
|
|
275
|
+
stroke-miterlimit="10"
|
|
276
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
277
|
+
></path>
|
|
278
|
+
</g></svg></span
|
|
279
|
+
><span class="permalink"
|
|
280
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
281
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
282
|
+
<path
|
|
283
|
+
fill="none"
|
|
284
|
+
stroke-linecap="round"
|
|
285
|
+
stroke-linejoin="round"
|
|
286
|
+
stroke-miterlimit="10"
|
|
287
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
288
|
+
></path>
|
|
289
|
+
<path
|
|
290
|
+
fill="none"
|
|
291
|
+
stroke="#000000"
|
|
292
|
+
stroke-linecap="round"
|
|
293
|
+
stroke-linejoin="round"
|
|
294
|
+
stroke-miterlimit="10"
|
|
295
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
296
|
+
></path>
|
|
297
|
+
</g></svg></span></a
|
|
298
|
+
><span class="permalink"
|
|
299
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
300
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
301
|
+
<path
|
|
302
|
+
fill="none"
|
|
303
|
+
stroke-linecap="round"
|
|
304
|
+
stroke-linejoin="round"
|
|
305
|
+
stroke-miterlimit="10"
|
|
306
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
307
|
+
></path>
|
|
308
|
+
<path
|
|
309
|
+
fill="none"
|
|
310
|
+
stroke="#000000"
|
|
311
|
+
stroke-linecap="round"
|
|
312
|
+
stroke-linejoin="round"
|
|
313
|
+
stroke-miterlimit="10"
|
|
314
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
315
|
+
></path>
|
|
316
|
+
</g></svg
|
|
317
|
+
></span>
|
|
318
|
+
</h3>
|
|
319
|
+
<p>
|
|
320
|
+
Once the infrastructure is successfully set up in AWS using
|
|
321
|
+
<code class="inline">yarn infra up</code>, we can deploy the module. For
|
|
322
|
+
this, simply run the following command:
|
|
323
|
+
</p>
|
|
324
|
+
<pre
|
|
325
|
+
class="language-bash language-bash language-bash"
|
|
326
|
+
><code class="language-bash"><span class="token function">yarn</span> deploy <span class="token punctuation">[</span>deploymentName<span class="token punctuation">]</span>
|
|
327
|
+
</code></pre>
|
|
328
|
+
<p>
|
|
329
|
+
This will either be <code class="inline">yarn deploy dev</code> or
|
|
330
|
+
<code class="inline">yarn deploy prod</code> depending on your choice of
|
|
331
|
+
deployment during project configuration.
|
|
332
|
+
</p>
|
|
333
|
+
</div>
|
|
334
|
+
<p></p>
|
|
335
|
+
<p>
|
|
336
|
+
You should now be able to access your API. The domain under which the API is
|
|
337
|
+
deployed is configured in <code class="inline">goldstack.json</code> under
|
|
338
|
+
<code class="inline">"deployments[*].apiDomain"</code>. You can access this
|
|
339
|
+
API domain with a browser since the default API provided in the template
|
|
340
|
+
allows for GET requests to the root.
|
|
341
|
+
</p>
|
|
342
|
+
<h3 class="heading">
|
|
343
|
+
<span id="development-1"></span
|
|
344
|
+
><a href="#development-1"
|
|
345
|
+
><span id="development"></span
|
|
346
|
+
><a href="#development" class="relative">Development</a
|
|
347
|
+
><span class="permalink"
|
|
348
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
349
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
350
|
+
<path
|
|
351
|
+
fill="none"
|
|
352
|
+
stroke-linecap="round"
|
|
353
|
+
stroke-linejoin="round"
|
|
354
|
+
stroke-miterlimit="10"
|
|
355
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
356
|
+
></path>
|
|
357
|
+
<path
|
|
358
|
+
fill="none"
|
|
359
|
+
stroke="#000000"
|
|
360
|
+
stroke-linecap="round"
|
|
361
|
+
stroke-linejoin="round"
|
|
362
|
+
stroke-miterlimit="10"
|
|
363
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
364
|
+
></path>
|
|
365
|
+
</g></svg></span></a
|
|
366
|
+
><span class="permalink"
|
|
367
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
368
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
369
|
+
<path
|
|
370
|
+
fill="none"
|
|
371
|
+
stroke-linecap="round"
|
|
372
|
+
stroke-linejoin="round"
|
|
373
|
+
stroke-miterlimit="10"
|
|
374
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
375
|
+
></path>
|
|
376
|
+
<path
|
|
377
|
+
fill="none"
|
|
378
|
+
stroke="#000000"
|
|
379
|
+
stroke-linecap="round"
|
|
380
|
+
stroke-linejoin="round"
|
|
381
|
+
stroke-miterlimit="10"
|
|
382
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
383
|
+
></path>
|
|
384
|
+
</g></svg
|
|
385
|
+
></span>
|
|
386
|
+
</h3>
|
|
387
|
+
<p>
|
|
388
|
+
The source code for the express server is defined in the
|
|
389
|
+
<code class="inline">src/</code> folder. The entry point for defining new
|
|
390
|
+
routes is in <code class="inline">src/server.ts</code>. The easiest way to
|
|
391
|
+
get started extending the API is to modify or add new routes to the server
|
|
392
|
+
here.
|
|
393
|
+
</p>
|
|
394
|
+
</div>
|
|
395
|
+
<p></p>
|
|
396
|
+
<h2 class="heading">
|
|
397
|
+
<span id="infrastructure-3"></span
|
|
398
|
+
><a href="#infrastructure-3">Infrastructure</a
|
|
399
|
+
><span class="permalink"
|
|
400
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
401
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
402
|
+
<path
|
|
403
|
+
fill="none"
|
|
404
|
+
stroke-linecap="round"
|
|
405
|
+
stroke-linejoin="round"
|
|
406
|
+
stroke-miterlimit="10"
|
|
407
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
408
|
+
></path>
|
|
409
|
+
<path
|
|
410
|
+
fill="none"
|
|
411
|
+
stroke="#000000"
|
|
412
|
+
stroke-linecap="round"
|
|
413
|
+
stroke-linejoin="round"
|
|
414
|
+
stroke-miterlimit="10"
|
|
415
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
416
|
+
></path>
|
|
417
|
+
</g></svg
|
|
418
|
+
></span>
|
|
419
|
+
</h2>
|
|
420
|
+
<p></p>
|
|
421
|
+
<div class="markdown-fragment">
|
|
422
|
+
<p>
|
|
423
|
+
All infrastructure for this module is defined in Terraform. You can find the
|
|
424
|
+
Terraform files for this module in the directory
|
|
425
|
+
<code class="inline">[moduleDir]/infra/aws</code>. You can define multiple
|
|
426
|
+
deployments for this module, for instance for development, staging and
|
|
427
|
+
production environments.
|
|
428
|
+
</p>
|
|
429
|
+
<p>
|
|
430
|
+
If you configured AWS deployment before downloading your project, the
|
|
431
|
+
deployments and their respective configurations are defined in
|
|
432
|
+
<code class="inline">[moduleDir]/goldstack.json</code>.
|
|
433
|
+
</p>
|
|
434
|
+
<p>
|
|
435
|
+
The configuration tool will define one deployment. This will be either
|
|
436
|
+
<code class="inline">dev</code> or
|
|
437
|
+
<code class="inline">prod</code> depending on your choice during project
|
|
438
|
+
configuration. In the example
|
|
439
|
+
<code class="inline">goldstack.json</code> below, a deployment with the name
|
|
440
|
+
<code class="inline">dev</code> is defined.
|
|
441
|
+
</p>
|
|
442
|
+
<pre
|
|
443
|
+
class="language-json language-json"
|
|
444
|
+
><code class="language-json"><span class="token punctuation">{</span>
|
|
445
|
+
<span class="token property">"$schema"</span><span class="token operator">:</span> <span class="token string">"./schemas/package.schema.json"</span><span class="token punctuation">,</span>
|
|
446
|
+
<span class="token property">"name"</span><span class="token operator">:</span> <span class="token string">"..."</span><span class="token punctuation">,</span>
|
|
447
|
+
<span class="token property">"template"</span><span class="token operator">:</span> <span class="token string">"..."</span><span class="token punctuation">,</span>
|
|
448
|
+
<span class="token property">"templateVersion"</span><span class="token operator">:</span> <span class="token string">"..."</span><span class="token punctuation">,</span>
|
|
449
|
+
<span class="token property">"configuration"</span><span class="token operator">:</span> <span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
450
|
+
<span class="token property">"deployments"</span><span class="token operator">:</span> <span class="token punctuation">[</span>
|
|
451
|
+
<span class="token punctuation">{</span>
|
|
452
|
+
<span class="token property">"name"</span><span class="token operator">:</span> <span class="token string">"dev"</span><span class="token punctuation">,</span>
|
|
453
|
+
<span class="token property">"awsRegion"</span><span class="token operator">:</span> <span class="token string">"us-west-2"</span><span class="token punctuation">,</span>
|
|
454
|
+
<span class="token property">"awsUser"</span><span class="token operator">:</span> <span class="token string">"awsUser"</span><span class="token punctuation">,</span>
|
|
455
|
+
<span class="token property">"configuration"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
|
456
|
+
...
|
|
457
|
+
<span class="token punctuation">}</span>
|
|
458
|
+
<span class="token punctuation">}</span>
|
|
459
|
+
<span class="token punctuation">]</span>
|
|
460
|
+
<span class="token punctuation">}</span>
|
|
461
|
+
</code></pre>
|
|
462
|
+
<h3 class="heading">
|
|
463
|
+
<span id="infrastructure-commands-1"></span
|
|
464
|
+
><a href="#infrastructure-commands-1"
|
|
465
|
+
><span id="infrastructure-commands"></span
|
|
466
|
+
><a href="#infrastructure-commands" class="relative"
|
|
467
|
+
>Infrastructure Commands</a
|
|
468
|
+
><span class="permalink"
|
|
469
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
470
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
471
|
+
<path
|
|
472
|
+
fill="none"
|
|
473
|
+
stroke-linecap="round"
|
|
474
|
+
stroke-linejoin="round"
|
|
475
|
+
stroke-miterlimit="10"
|
|
476
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
477
|
+
></path>
|
|
478
|
+
<path
|
|
479
|
+
fill="none"
|
|
480
|
+
stroke="#000000"
|
|
481
|
+
stroke-linecap="round"
|
|
482
|
+
stroke-linejoin="round"
|
|
483
|
+
stroke-miterlimit="10"
|
|
484
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
485
|
+
></path>
|
|
486
|
+
</g></svg></span></a
|
|
487
|
+
><span class="permalink"
|
|
488
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
489
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
490
|
+
<path
|
|
491
|
+
fill="none"
|
|
492
|
+
stroke-linecap="round"
|
|
493
|
+
stroke-linejoin="round"
|
|
494
|
+
stroke-miterlimit="10"
|
|
495
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
496
|
+
></path>
|
|
497
|
+
<path
|
|
498
|
+
fill="none"
|
|
499
|
+
stroke="#000000"
|
|
500
|
+
stroke-linecap="round"
|
|
501
|
+
stroke-linejoin="round"
|
|
502
|
+
stroke-miterlimit="10"
|
|
503
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
504
|
+
></path>
|
|
505
|
+
</g></svg
|
|
506
|
+
></span>
|
|
507
|
+
</h3>
|
|
508
|
+
<p>
|
|
509
|
+
Infrastructure commands for this module can be run using
|
|
510
|
+
<code class="inline">yarn</code>. There are four commands in total:
|
|
511
|
+
</p>
|
|
512
|
+
<ul>
|
|
513
|
+
<li>
|
|
514
|
+
<code class="inline">yarn infra up</code>: For standing up infrastructure.
|
|
515
|
+
</li>
|
|
516
|
+
<li>
|
|
517
|
+
<code class="inline">yarn infra init</code>: For
|
|
518
|
+
<a
|
|
519
|
+
href="https://www.terraform.io/docs/commands/init.html"
|
|
520
|
+
class="absolute"
|
|
521
|
+
target="_blank"
|
|
522
|
+
rel="noopener noreferrer"
|
|
523
|
+
>initialising Terraform</a
|
|
524
|
+
>.
|
|
525
|
+
</li>
|
|
526
|
+
<li>
|
|
527
|
+
<code class="inline">yarn infra plan</code>: For running
|
|
528
|
+
<a
|
|
529
|
+
href="https://www.terraform.io/docs/commands/plan.html"
|
|
530
|
+
class="absolute"
|
|
531
|
+
target="_blank"
|
|
532
|
+
rel="noopener noreferrer"
|
|
533
|
+
>Terraform plan</a
|
|
534
|
+
>.
|
|
535
|
+
</li>
|
|
536
|
+
<li>
|
|
537
|
+
<code class="inline">yarn infra apply</code>: For running
|
|
538
|
+
<a
|
|
539
|
+
href="https://www.terraform.io/docs/commands/apply.html"
|
|
540
|
+
class="absolute"
|
|
541
|
+
target="_blank"
|
|
542
|
+
rel="noopener noreferrer"
|
|
543
|
+
>Terraform apply</a
|
|
544
|
+
>.
|
|
545
|
+
</li>
|
|
546
|
+
<li>
|
|
547
|
+
<code class="inline">yarn infra destroy</code>: For destroying all
|
|
548
|
+
infrastructure using
|
|
549
|
+
<a
|
|
550
|
+
href="https://www.terraform.io/docs/commands/destroy.html"
|
|
551
|
+
class="absolute"
|
|
552
|
+
target="_blank"
|
|
553
|
+
rel="noopener noreferrer"
|
|
554
|
+
>Terraform destroy</a
|
|
555
|
+
>.
|
|
556
|
+
</li>
|
|
557
|
+
</ul>
|
|
558
|
+
<p>
|
|
559
|
+
For each command, the deployment they should be applied to must be
|
|
560
|
+
specified.
|
|
561
|
+
</p>
|
|
562
|
+
<pre
|
|
563
|
+
class="language-bash language-bash"
|
|
564
|
+
><code class="language-bash"><span class="token function">yarn</span> infra <span class="token punctuation">[</span>command<span class="token punctuation">]</span> <span class="token punctuation">[</span>deploymentName<span class="token punctuation">]</span>
|
|
565
|
+
</code></pre>
|
|
566
|
+
<p>
|
|
567
|
+
For instance, to stand up the infrastructure for the
|
|
568
|
+
<code class="inline">dev</code> deployment, the following command would need
|
|
569
|
+
to be issued:
|
|
570
|
+
</p>
|
|
571
|
+
<pre
|
|
572
|
+
class="language-bash language-bash"
|
|
573
|
+
><code class="language-bash"><span class="token function">yarn</span> infra up dev
|
|
574
|
+
</code></pre>
|
|
575
|
+
<p>
|
|
576
|
+
Generally you will only need to run
|
|
577
|
+
<code class="inline">yarn infra up</code>. However, if you are familiar with
|
|
578
|
+
Terraform and want more fine-grained control over the deployment of your
|
|
579
|
+
infrastructure, you can also use the other commands as required.
|
|
580
|
+
</p>
|
|
581
|
+
<h3 class="heading">
|
|
582
|
+
<span id="customizing-terraform-1"></span
|
|
583
|
+
><a href="#customizing-terraform-1"
|
|
584
|
+
><span id="customizing-terraform"></span
|
|
585
|
+
><a href="#customizing-terraform" class="relative"
|
|
586
|
+
>Customizing Terraform</a
|
|
587
|
+
><span class="permalink"
|
|
588
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
589
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
590
|
+
<path
|
|
591
|
+
fill="none"
|
|
592
|
+
stroke-linecap="round"
|
|
593
|
+
stroke-linejoin="round"
|
|
594
|
+
stroke-miterlimit="10"
|
|
595
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
596
|
+
></path>
|
|
597
|
+
<path
|
|
598
|
+
fill="none"
|
|
599
|
+
stroke="#000000"
|
|
600
|
+
stroke-linecap="round"
|
|
601
|
+
stroke-linejoin="round"
|
|
602
|
+
stroke-miterlimit="10"
|
|
603
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
604
|
+
></path>
|
|
605
|
+
</g></svg></span></a
|
|
606
|
+
><span class="permalink"
|
|
607
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
608
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
609
|
+
<path
|
|
610
|
+
fill="none"
|
|
611
|
+
stroke-linecap="round"
|
|
612
|
+
stroke-linejoin="round"
|
|
613
|
+
stroke-miterlimit="10"
|
|
614
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
615
|
+
></path>
|
|
616
|
+
<path
|
|
617
|
+
fill="none"
|
|
618
|
+
stroke="#000000"
|
|
619
|
+
stroke-linecap="round"
|
|
620
|
+
stroke-linejoin="round"
|
|
621
|
+
stroke-miterlimit="10"
|
|
622
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
623
|
+
></path>
|
|
624
|
+
</g></svg
|
|
625
|
+
></span>
|
|
626
|
+
</h3>
|
|
627
|
+
<p>
|
|
628
|
+
Goldstack modules make it very easy to customize infrastructure to your
|
|
629
|
+
specific needs. The easiest way to do this is to simply edit the
|
|
630
|
+
<code class="inline">*.tf</code> files in the
|
|
631
|
+
<code class="inline">infra/aws</code> folder. You can make the changes you
|
|
632
|
+
need and then run
|
|
633
|
+
<code class="inline">yarn infra up [deploymentName]</code> to apply the
|
|
634
|
+
changes.
|
|
635
|
+
</p>
|
|
636
|
+
<p>
|
|
637
|
+
The <code class="inline">infra/aws</code> folder contains a file
|
|
638
|
+
<code class="inline">variables.tf</code> that contains the variables
|
|
639
|
+
required for your deployment; for instance the domain name for a website.
|
|
640
|
+
The values for these variables are defined in the module's
|
|
641
|
+
<code class="inline">goldstack.json</code> file in the
|
|
642
|
+
<code class="inline">"configuration"</code> property. There is one global
|
|
643
|
+
<code class="inline">configuration</code> property that applies for all
|
|
644
|
+
deployments and each deployment also has its own
|
|
645
|
+
<code class="inline">configuration</code> property. In order to add a new
|
|
646
|
+
variable, add the variable to <code class="inline">variables.tf</code> and
|
|
647
|
+
then add it to the configuration for your module or to the configurations
|
|
648
|
+
for the deployments.
|
|
649
|
+
</p>
|
|
650
|
+
<p>
|
|
651
|
+
Note that due to JavaScript and Terraform using different conventions for
|
|
652
|
+
naming variables, Goldstack applies a basic transformation to variable
|
|
653
|
+
names. Camel-case variables names are converted to valid variables names for
|
|
654
|
+
Terraform by replacing every instance of a capital letter
|
|
655
|
+
<code class="inline">C</code> with <code class="inline">_c</code> in the
|
|
656
|
+
variable name. For instance:
|
|
657
|
+
</p>
|
|
658
|
+
<p>
|
|
659
|
+
<code class="inline">myVariableName</code> in the Goldstack configuration
|
|
660
|
+
will translate to the Terraform variable
|
|
661
|
+
<code class="inline">my_variable_name</code> as defined in
|
|
662
|
+
<code class="inline">variables.tf</code>.
|
|
663
|
+
</p>
|
|
664
|
+
<h3 class="heading">
|
|
665
|
+
<span id="terraform-state-1"></span
|
|
666
|
+
><a href="#terraform-state-1"
|
|
667
|
+
><span id="terraform-state"></span
|
|
668
|
+
><a href="#terraform-state" class="relative">Terraform State</a
|
|
669
|
+
><span class="permalink"
|
|
670
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
671
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
672
|
+
<path
|
|
673
|
+
fill="none"
|
|
674
|
+
stroke-linecap="round"
|
|
675
|
+
stroke-linejoin="round"
|
|
676
|
+
stroke-miterlimit="10"
|
|
677
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
678
|
+
></path>
|
|
679
|
+
<path
|
|
680
|
+
fill="none"
|
|
681
|
+
stroke="#000000"
|
|
682
|
+
stroke-linecap="round"
|
|
683
|
+
stroke-linejoin="round"
|
|
684
|
+
stroke-miterlimit="10"
|
|
685
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
686
|
+
></path>
|
|
687
|
+
</g></svg></span></a
|
|
688
|
+
><span class="permalink"
|
|
689
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
690
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
691
|
+
<path
|
|
692
|
+
fill="none"
|
|
693
|
+
stroke-linecap="round"
|
|
694
|
+
stroke-linejoin="round"
|
|
695
|
+
stroke-miterlimit="10"
|
|
696
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
697
|
+
></path>
|
|
698
|
+
<path
|
|
699
|
+
fill="none"
|
|
700
|
+
stroke="#000000"
|
|
701
|
+
stroke-linecap="round"
|
|
702
|
+
stroke-linejoin="round"
|
|
703
|
+
stroke-miterlimit="10"
|
|
704
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
705
|
+
></path>
|
|
706
|
+
</g></svg
|
|
707
|
+
></span>
|
|
708
|
+
</h3>
|
|
709
|
+
<p>
|
|
710
|
+
In order to manage your infrastructure, Terraform maintains a state for each
|
|
711
|
+
deployment; to calculate required changes when the infrastructure is updated
|
|
712
|
+
and also for destroying the infrastructure if it is no longer required.
|
|
713
|
+
Goldstack by default will store the terraform state in the
|
|
714
|
+
<code class="inline">infra/aws</code> folder as simple files.
|
|
715
|
+
</p>
|
|
716
|
+
<p>
|
|
717
|
+
This works well for deploying infrastructure from your local development
|
|
718
|
+
environment but is not a good choice when building a CI/CD pipeline for the
|
|
719
|
+
infrastructure definition. In that case, it is better to define
|
|
720
|
+
<a
|
|
721
|
+
href="https://www.terraform.io/docs/state/remote.html"
|
|
722
|
+
class="absolute"
|
|
723
|
+
target="_blank"
|
|
724
|
+
rel="noopener noreferrer"
|
|
725
|
+
>Remote State</a
|
|
726
|
+
>. A popular choice many projects adopt here is to store the
|
|
727
|
+
<a
|
|
728
|
+
href="https://www.terraform.io/docs/backends/types/s3.html"
|
|
729
|
+
class="absolute"
|
|
730
|
+
target="_blank"
|
|
731
|
+
rel="noopener noreferrer"
|
|
732
|
+
>state in an S3 bucket</a
|
|
733
|
+
>. Please see the Terraform documentation for further details.
|
|
734
|
+
</p>
|
|
735
|
+
</div>
|
|
736
|
+
<p></p>
|
|
737
|
+
<h2 class="heading">
|
|
738
|
+
<span id="deployment-3"></span><a href="#deployment-3">Deployment</a
|
|
739
|
+
><span class="permalink"
|
|
740
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
741
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
742
|
+
<path
|
|
743
|
+
fill="none"
|
|
744
|
+
stroke-linecap="round"
|
|
745
|
+
stroke-linejoin="round"
|
|
746
|
+
stroke-miterlimit="10"
|
|
747
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
748
|
+
></path>
|
|
749
|
+
<path
|
|
750
|
+
fill="none"
|
|
751
|
+
stroke="#000000"
|
|
752
|
+
stroke-linecap="round"
|
|
753
|
+
stroke-linejoin="round"
|
|
754
|
+
stroke-miterlimit="10"
|
|
755
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
756
|
+
></path>
|
|
757
|
+
</g></svg
|
|
758
|
+
></span>
|
|
759
|
+
</h2>
|
|
760
|
+
<p></p>
|
|
761
|
+
<div class="markdown-fragment">
|
|
762
|
+
<p>
|
|
763
|
+
This module can be packaged up and deployed to the deployments specified in
|
|
764
|
+
<code class="inline">goldstack.json</code>. Note that deployment will only
|
|
765
|
+
work <em>after</em> the infrastructure for the respective deployment has
|
|
766
|
+
been stood up. To deploy your module, run the following script:
|
|
767
|
+
</p>
|
|
768
|
+
<pre
|
|
769
|
+
class="language-bash language-bash"
|
|
770
|
+
><code class="language-bash"><span class="token function">yarn</span> deploy <span class="token punctuation">[</span>deploymentName<span class="token punctuation">]</span>
|
|
771
|
+
</code></pre>
|
|
772
|
+
</div>
|
|
773
|
+
<p></p>
|
|
774
|
+
<h2 class="heading">
|
|
775
|
+
<span id="guides-and-how-to"></span
|
|
776
|
+
><a href="#guides-and-how-to">Guides and How To</a
|
|
777
|
+
><span class="permalink"
|
|
778
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
779
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
780
|
+
<path
|
|
781
|
+
fill="none"
|
|
782
|
+
stroke-linecap="round"
|
|
783
|
+
stroke-linejoin="round"
|
|
784
|
+
stroke-miterlimit="10"
|
|
785
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
786
|
+
></path>
|
|
787
|
+
<path
|
|
788
|
+
fill="none"
|
|
789
|
+
stroke="#000000"
|
|
790
|
+
stroke-linecap="round"
|
|
791
|
+
stroke-linejoin="round"
|
|
792
|
+
stroke-miterlimit="10"
|
|
793
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
794
|
+
></path>
|
|
795
|
+
</g></svg
|
|
796
|
+
></span>
|
|
797
|
+
</h2>
|
|
798
|
+
<h3 class="heading">
|
|
799
|
+
<span id="adding-environment-variables"></span
|
|
800
|
+
><a href="#adding-environment-variables">Adding environment variables</a
|
|
801
|
+
><span class="permalink"
|
|
802
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
803
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
804
|
+
<path
|
|
805
|
+
fill="none"
|
|
806
|
+
stroke-linecap="round"
|
|
807
|
+
stroke-linejoin="round"
|
|
808
|
+
stroke-miterlimit="10"
|
|
809
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
810
|
+
></path>
|
|
811
|
+
<path
|
|
812
|
+
fill="none"
|
|
813
|
+
stroke="#000000"
|
|
814
|
+
stroke-linecap="round"
|
|
815
|
+
stroke-linejoin="round"
|
|
816
|
+
stroke-miterlimit="10"
|
|
817
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
818
|
+
></path>
|
|
819
|
+
</g></svg
|
|
820
|
+
></span>
|
|
821
|
+
</h3>
|
|
822
|
+
<p>
|
|
823
|
+
Environment variables are defined in the Terraform source code for this
|
|
824
|
+
module. Specifically they are defined in the
|
|
825
|
+
<code class="inline">infra/aws/lambda.tf</code> file in the resource
|
|
826
|
+
<code class="inline">resource "aws_lambda_function" "main"</code>. By default,
|
|
827
|
+
there is one environment variable specified that identifies the Goldstack
|
|
828
|
+
deployment used.
|
|
829
|
+
</p>
|
|
830
|
+
<pre
|
|
831
|
+
class="language-hcl"
|
|
832
|
+
><code class="language-hcl"> <span class="token keyword">environment</span> <span class="token punctuation">{</span>
|
|
833
|
+
<span class="token property">variables</span> <span class="token punctuation">=</span> <span class="token punctuation">{</span>
|
|
834
|
+
<span class="token property">GOLDSTACK_DEPLOYMENT</span> <span class="token punctuation">=</span> var.name
|
|
835
|
+
<span class="token punctuation">}</span>
|
|
836
|
+
<span class="token punctuation">}</span>
|
|
837
|
+
</code></pre>
|
|
838
|
+
<p>
|
|
839
|
+
Add your environment variables into the
|
|
840
|
+
<code class="inline">variables</code> map:
|
|
841
|
+
</p>
|
|
842
|
+
<pre
|
|
843
|
+
class="language-hcl"
|
|
844
|
+
><code class="language-hcl"> <span class="token keyword">environment</span> <span class="token punctuation">{</span>
|
|
845
|
+
<span class="token property">variables</span> <span class="token punctuation">=</span> <span class="token punctuation">{</span>
|
|
846
|
+
<span class="token property">GOLDSTACK_DEPLOYMENT</span> <span class="token punctuation">=</span> var.name
|
|
847
|
+
<span class="token property">YOUR_ENV_VAR</span> <span class="token punctuation">=</span> 'your env var value'
|
|
848
|
+
<span class="token punctuation">}</span>
|
|
849
|
+
<span class="token punctuation">}</span>
|
|
850
|
+
</code></pre>
|
|
851
|
+
<p>
|
|
852
|
+
Usually environment variables should have different values depending on which
|
|
853
|
+
environment the server is deployed to. This can be accomplished using
|
|
854
|
+
Terraform variables. Change your variable declaration to the following:
|
|
855
|
+
</p>
|
|
856
|
+
<pre
|
|
857
|
+
class="language-hcl"
|
|
858
|
+
><code class="language-hcl"><span class="token property">YOUR_ENV_VAR</span> <span class="token punctuation">=</span> var.my_env
|
|
859
|
+
</code></pre>
|
|
860
|
+
<p>
|
|
861
|
+
Then go into the file <code class="inline">infra/aws/variables.tf</code> and
|
|
862
|
+
add the following definition:
|
|
863
|
+
</p>
|
|
864
|
+
<pre
|
|
865
|
+
class="language-hcl"
|
|
866
|
+
><code class="language-hcl"><span class="token keyword">variable<span class="token type variable"> "my_env" </span></span><span class="token punctuation">{</span>
|
|
867
|
+
<span class="token property">description</span> <span class="token punctuation">=</span> <span class="token string">"My environment variable"</span>
|
|
868
|
+
<span class="token property">type</span> <span class="token punctuation">=</span> string
|
|
869
|
+
<span class="token punctuation">}</span>
|
|
870
|
+
</code></pre>
|
|
871
|
+
<p>
|
|
872
|
+
And finally add this variable to all deployment configurations in
|
|
873
|
+
<code class="inline">goldstack.json</code>:
|
|
874
|
+
</p>
|
|
875
|
+
<pre
|
|
876
|
+
class="language-json"
|
|
877
|
+
><code class="language-json"> <span class="token property">"configuration"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
|
878
|
+
<span class="token property">"lambdaName"</span><span class="token operator">:</span> <span class="token string">"my-lambda"</span><span class="token punctuation">,</span>
|
|
879
|
+
<span class="token property">"apiDomain"</span><span class="token operator">:</span> <span class="token string">"api.mysite.com"</span><span class="token punctuation">,</span>
|
|
880
|
+
<span class="token property">"hostedZoneDomain"</span><span class="token operator">:</span> <span class="token string">"mysite.com"</span><span class="token punctuation">,</span>
|
|
881
|
+
<span class="token property">"cors"</span><span class="token operator">:</span> <span class="token string">"https://mysite.com"</span><span class="token punctuation">,</span>
|
|
882
|
+
<span class="token property">"myEnv"</span><span class="token operator">:</span> <span class="token string">"Value for deployment"</span>
|
|
883
|
+
<span class="token punctuation">}</span>
|
|
884
|
+
</code></pre>
|
|
885
|
+
<p>
|
|
886
|
+
Note that the Terraform variable <code class="inline">my_env</code> translates
|
|
887
|
+
to <code class="inline">myEnv</code> in the JSON definition (Just remove all
|
|
888
|
+
<code class="inline">_</code> and make the first character after
|
|
889
|
+
<code class="inline">_</code> uppercase for your variable definitions).
|
|
890
|
+
</p>
|
|
891
|
+
<p>
|
|
892
|
+
Lastly, to support local development make sure to define the variable
|
|
893
|
+
correctly in all <code class="inline">scripts</code> in
|
|
894
|
+
<code class="inline">package.json</code>. Specifically, you may want to define
|
|
895
|
+
them for <code class="inline">"test"</code>,
|
|
896
|
+
<code class="inline">"test:ci"</code> and <code class="inline">"watch"</code>.
|
|
897
|
+
</p>
|
|
898
|
+
<pre
|
|
899
|
+
class="language-json"
|
|
900
|
+
><code class="language-json"> <span class="token property">"test"</span><span class="token operator">:</span> <span class="token string">"MY_ENV=localvalue jest --passWithNoTests --watch --config=jest.config.js"</span><span class="token punctuation">,</span>
|
|
901
|
+
<span class="token property">"test:ci"</span><span class="token operator">:</span> <span class="token string">"MY_ENV=localvalue jest --passWithNoTests --config=jest.config.js --detectOpenHandles"</span><span class="token punctuation">,</span>
|
|
902
|
+
<span class="token property">"watch"</span><span class="token operator">:</span> <span class="token string">"PORT=8731 MY_ENV=localvalue nodemon --config nodemon.json --exec 'yarn node dist/src/local.js'"</span>
|
|
903
|
+
</code></pre>
|
|
904
|
+
<p>
|
|
905
|
+
Note that for credentials and other values that should not be committed to
|
|
906
|
+
source code, it may be better to store these in AWS Secrets Manager and
|
|
907
|
+
retrieve them using the AWS SDK based on the
|
|
908
|
+
<code class="inline">process.env.GOLDSTACK_DEPLOYMENT</code> value provided.
|
|
909
|
+
</p>
|
|
910
|
+
<p>
|
|
911
|
+
It is also possible to provide the value of Terraform variables through
|
|
912
|
+
environment variables during build time. For instance, if you have defined the
|
|
913
|
+
variable <code class="inline">my_env</code>, simply provide the environment
|
|
914
|
+
variable <code class="inline">MY_ENV</code> when calling
|
|
915
|
+
<code class="inline">yarn infra</code>.
|
|
916
|
+
</p>
|
|
917
|
+
<pre
|
|
918
|
+
class="language-bash"
|
|
919
|
+
><code class="language-bash"><span class="token assign-left variable">MY_ENV</span><span class="token operator">=</span>value <span class="token function">yarn</span> infra up prod
|
|
920
|
+
</code></pre>
|
|
921
|
+
<p>This works very well in combination with secrets for GitHub actions.</p>
|
|
922
|
+
<pre
|
|
923
|
+
class="language-yaml"
|
|
924
|
+
><code class="language-yaml"><span class="token punctuation">-</span> <span class="token key atrule">name</span><span class="token punctuation">:</span> Deploy API
|
|
925
|
+
<span class="token key atrule">run</span><span class="token punctuation">:</span> <span class="token punctuation">|</span><span class="token scalar string">
|
|
926
|
+
yarn workspace my-api infra up prod</span>
|
|
927
|
+
<span class="token key atrule">env</span><span class="token punctuation">:</span>
|
|
928
|
+
<span class="token key atrule">MY_ENV</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span><span class="token punctuation">{</span>secrets.MY_ENV<span class="token punctuation">}</span><span class="token punctuation">}</span>
|
|
929
|
+
<span class="token key atrule">AWS_USER_NAME</span><span class="token punctuation">:</span> goldstack<span class="token punctuation">-</span>prod
|
|
930
|
+
<span class="token key atrule">AWS_ACCESS_KEY_ID</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span><span class="token punctuation">{</span>secrets.PROD_AWS_ACCESS_KEY_ID<span class="token punctuation">}</span><span class="token punctuation">}</span>
|
|
931
|
+
<span class="token key atrule">AWS_SECRET_ACCESS_KEY</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span><span class="token punctuation">{</span>secrets.PROD_AWS_SECRET_ACCESS_KEY<span class="token punctuation">}</span><span class="token punctuation">}</span>
|
|
932
|
+
<span class="token key atrule">AWS_DEFAULT_REGION</span><span class="token punctuation">:</span> us<span class="token punctuation">-</span>west<span class="token punctuation">-</span><span class="token number">2</span>
|
|
933
|
+
</code></pre>
|
|
934
|
+
<h2 class="heading">
|
|
935
|
+
<span id="security-hardening"></span
|
|
936
|
+
><a href="#security-hardening">Security Hardening</a
|
|
937
|
+
><span class="permalink"
|
|
938
|
+
><svg viewBox="0 0 16 16" width="16" height="16">
|
|
939
|
+
<g stroke-width="1" fill="#000000" stroke="#000000">
|
|
940
|
+
<path
|
|
941
|
+
fill="none"
|
|
942
|
+
stroke-linecap="round"
|
|
943
|
+
stroke-linejoin="round"
|
|
944
|
+
stroke-miterlimit="10"
|
|
945
|
+
d="M8.995,7.005 L8.995,7.005c1.374,1.374,1.374,3.601,0,4.975l-1.99,1.99c-1.374,1.374-3.601,1.374-4.975,0l0,0c-1.374-1.374-1.374-3.601,0-4.975 l1.748-1.698"
|
|
946
|
+
></path>
|
|
947
|
+
<path
|
|
948
|
+
fill="none"
|
|
949
|
+
stroke="#000000"
|
|
950
|
+
stroke-linecap="round"
|
|
951
|
+
stroke-linejoin="round"
|
|
952
|
+
stroke-miterlimit="10"
|
|
953
|
+
d="M7.005,8.995 L7.005,8.995c-1.374-1.374-1.374-3.601,0-4.975l1.99-1.99c1.374-1.374,3.601-1.374,4.975,0l0,0c1.374,1.374,1.374,3.601,0,4.975 l-1.748,1.698"
|
|
954
|
+
></path>
|
|
955
|
+
</g></svg
|
|
956
|
+
></span>
|
|
957
|
+
</h2>
|
|
958
|
+
<p>
|
|
959
|
+
This module requires further security hardening when deployed in critical
|
|
960
|
+
production applications. Specifically the lambda is given the role
|
|
961
|
+
<code class="inline">arn:aws:iam::aws:policy/AdministratorAccess"</code> and
|
|
962
|
+
this will grant the lambda access to all resources on the AWS account,
|
|
963
|
+
including the ability to create and destroy infrastructure. It is therefore
|
|
964
|
+
recommended to grant this lambda only rights to resources it needs access to,
|
|
965
|
+
such as read and write permissions for an S3 bucket. This can be modified in
|
|
966
|
+
<code class="inline">infra/aws/lambda.tf</code> in the resource
|
|
967
|
+
<code class="inline"
|
|
968
|
+
>resource "aws_iam_role_policy_attachment" "lambda_admin_role_attach"</code
|
|
969
|
+
>.
|
|
970
|
+
</p>
|