Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit 66417d4

Browse files
davemooreuwsjyecuschHomelessDinosaur
authored
add website docs (#709)
Co-authored-by: Jye Cusch <[email protected]> Co-authored-by: Ryan Cartwright <[email protected]>
1 parent 6c5cfe6 commit 66417d4

File tree

9 files changed

+464
-0
lines changed

9 files changed

+464
-0
lines changed

‎dictionary.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,8 @@ Trivy's
252252
KMS
253253
deployable
254254
VMs
255+
CDN
256+
subdirectories
255257
[0-9]+px
256258
^.+[-:_]\w+$
257259
[a-z]+([A-Z0-9]|[A-Z0-9]\w+)

‎docs/architecture/websites.mdx‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
description: 'Learn how Nitric provisions and manages websites with Terraform and Pulumi across AWS, GCP, and Azure.'
3+
---
4+
5+
# Websites
6+
7+
## 1. System Context
8+
9+
**Developers** use Nitric to define required websites within their application.
10+
11+
- App code uses the [Website resource](/websites) defined in `nitric.yaml` to specify the websites and their configurations.
12+
- Developers can configure base path, index pages, error pages, and other settings in their `nitric.yaml` file.
13+
- When a website is defined, a single CDN endpoint is automatically created to serve the website content globally, including APIs as proxies.
14+
15+
**Operations** use default or overridden IaC (e.g., Terraform modules) to provision the necessary resources for their target cloud.
16+
17+
<details>
18+
<summary>Example AWS Provider</summary>
19+
20+
- **AWS S3** serves as the storage backend for static files (e.g., HTML, CSS, JS, images).
21+
- **AWS CloudFront** is used to distribute the website globally and serve as a single entry point for the whole application.
22+
- **AWS IAM** providers roles for access to the Website bucket
23+
24+
```mermaid
25+
flowchart TD
26+
Developer["Developer"]
27+
NitricUp["nitric up"]
28+
S3["AWS S3 Bucket"]
29+
CloudFront["AWS CloudFront"]
30+
Rewrite["AWS API Gateway"]
31+
32+
Developer -->|Deploy| NitricUp
33+
NitricUp -->|Upload Assets| S3
34+
NitricUp -->|Create CDN| CloudFront
35+
CloudFront -->|Serve Static Files| S3
36+
CloudFront -->|Rewrite /api/* to API| Rewrite
37+
38+
classDef default line-height:1;
39+
classDef edgeLabel line-height:2;
40+
```
41+
42+
</details>
43+
44+
<details>
45+
<summary>Example Azure Provider</summary>
46+
- **Static Website in Azure Blob Storage** serves as the storage backend for static files (e.g., HTML, CSS, JS, images).
47+
- **Azure Front Door** is used to distribute the website globally and serve as a single entry point for the whole application.
48+
49+
```mermaid
50+
flowchart TD
51+
Developer["Developer"]
52+
NitricUp["nitric up"]
53+
Storage["Azure Storage"]
54+
FrontDoor["Azure Front Door"]
55+
Rewrite["Azure API Management"]
56+
57+
Developer -->|Deploy| NitricUp
58+
NitricUp -->|Upload Assets| Storage
59+
NitricUp -->|Create CDN| FrontDoor
60+
FrontDoor -->|Serve Static Files| Storage
61+
FrontDoor -->|Rewrite /api/* to API| Rewrite
62+
63+
classDef default line-height:1;
64+
classDef edgeLabel line-height:2;
65+
```
66+
67+
</details>
68+
69+
## 2. Sequence
70+
71+
### Build Sequence
72+
73+
Below is the sequence of events that occur when a developer registers a website with Nitric:
74+
75+
```mermaid
76+
sequenceDiagram
77+
participant Config as nitric.yaml
78+
participant CLI as Nitric CLI
79+
participant Provider as Nitric Provider<br>(plugin)
80+
participant IAC as IaC (e.g. Terraform)
81+
82+
CLI->>Config: Parse website configuration
83+
CLI->>Provider: Forward Nitric Spec
84+
Provider->>IAC: Provision Website
85+
Provider->>IAC: Provision IAM
86+
```
87+
88+
## 3. Component
89+
90+
### Website Module
91+
92+
- Deploys website assets to a cloud-based storage solution for flexible and scalable hosting.
93+
- Configures a distribution layer to serve the site globally, rewriting API endpoints to `/api/{apiName}` for consistent routing.
94+
- Automatically invalidates the cache based on file changes, ensuring users always receive the latest content.
95+
96+
## 4. Code
97+
98+
**Developers** write yaml configuration to define the website and implement logic to serve static files.
99+
100+
### Nitric website configuration - nitric.yaml
101+
102+
```yaml
103+
name: service-name
104+
services:
105+
- match: ./services/*.js
106+
start: npm run dev:services $SERVICE_PATH
107+
runtime: node
108+
runtimes:
109+
node:
110+
dockerfile: ./node.dockerfile
111+
args: {}
112+
# The website configuration
113+
websites:
114+
- basedir: ./my-website
115+
index: index.html
116+
error: 404.html
117+
build:
118+
command: npm run build
119+
output: ./dist
120+
dev:
121+
command: npm run dev -- --port 4322
122+
url: http://localhost:4322
123+
```
124+
125+
### Access an API from the website frontend
126+
127+
```javascript
128+
async function fetchData() {
129+
// due to apis being served from the same domain thanks to rewrites, no CORS is required
130+
const response = await fetch('/api/main/hello')
131+
const data = await response.json()
132+
console.log(data)
133+
}
134+
```
135+
136+
**Operations** will use or extend the Nitric infrastructure modules, including both Terraform and Pulumi:
137+
138+
- Terraform Modules:
139+
- Not yet available
140+
- Pulumi Modules:
141+
- [AWS Website Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/aws/deploy/website.go)
142+
- [Azure Website Pulumi Module](https://github.com/nitrictech/nitric/blob/main/cloud/azure/deploy/website.go)

‎docs/get-started/foundations/projects/configuration.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,3 +234,61 @@ runtimes:
234234
args:
235235
GO_VERSION: 1.16
236236
```
237+
238+
### `websites` (optional)
239+
240+
A list of [website](/websites) types that make up your project. Websites are used to serve static files and assets.
241+
242+
```yaml
243+
websites:
244+
- basedir: ./my-website
245+
path: /
246+
index: index.html
247+
error: 404.html
248+
build:
249+
command: npm run build
250+
output: ./dist
251+
dev:
252+
command: npm run dev
253+
url: http://localhost:4322
254+
```
255+
256+
#### `basedir`
257+
258+
The base directory to search for website assets. If not provided, the base directory is the root of the project. This is useful when you want to group websites under a specific directory or you're working with a monorepo.
259+
260+
#### `path`
261+
262+
The path to serve the website at. If not provided, the default is `/`. This is useful when you want to serve multiple websites under different paths.
263+
264+
#### `index`
265+
266+
The name of the index file to serve. If not provided, the default is `index.html`.
267+
268+
#### `error`
269+
270+
The name of the error file to serve. If not provided, the default is `404.html`.
271+
272+
#### `build`
273+
274+
A map of build configuration options for the website. This is used to build the website assets before deployment.
275+
276+
##### `command`
277+
278+
The command to build the website assets. This command will be executed in the base directory of the website.
279+
280+
##### `output`
281+
282+
The output directory for the built website assets. This is relative to the base directory of the website.
283+
284+
#### `dev`
285+
286+
A map of development configuration options for the website. This is used to run the website in development mode.
287+
288+
##### `command`
289+
290+
The command to run the website in development mode. This command will be executed in the base directory of the website.
291+
292+
##### `url`
293+
294+
The URL to access the website in development mode. This is used to configure the Nitric CLI to proxy requests to the website during local development.

‎docs/get-started/foundations/projects/local-development.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ The Nitric CLI also hosts a Local Development Dashboard, which provides a graphi
6161
- **Topics**: View topics and subscriptions, and publish messages to topics.
6262
- **Secrets**: View and manage your application secrets.
6363
- **WebSockets**: Dive deep into connection details, connecting, and sending messages.
64+
- **Websites**: View your websites.
6465

6566
Many of these features make it possible to build and testing modules of your application in isolation. For example, you can could create and test a topic and subscriber without needing to first write the publisher.
6667

‎docs/providers/mappings/aws/websites.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
description: 'How Nitric deploys Websites to AWS'
3+
---
4+
5+
# AWS Resources - Websites
6+
7+
Nitric Websites are deployed to AWS using [Amazon S3](https://aws.amazon.com/s3/) and [Amazon CloudFront](https://aws.amazon.com/cloudfront/).
8+
9+
## AWS Resources
10+
11+
The following resources are created when deploying Websites to AWS:
12+
13+
- S3 Bucket
14+
- IAM Policies and Permissions
15+
- CloudFront Distribution
16+
- CloudFront Functions
17+
18+
## Deployment
19+
20+
During deployment the Nitric CLI creates a bucket for your website assets and a CloudFront distribution to serve them:
21+
22+
- The declared website is created in S3
23+
- A CloudFront distribution is created to serve your website and rewrite all APIs to `/api/{apiName}` using CloudFront Functions
24+
- Cache invalidation is automatic based on changed files

‎docs/providers/mappings/azure/websites.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
description: 'How Nitric deploys Websites to Azure'
3+
---
4+
5+
# Azure Resources - Websites
6+
7+
Nitric Websites are deployed to Azure using [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) and [Azure Front Door](https://azure.microsoft.com/en-us/services/frontdoor/).
8+
9+
## Azure Resources
10+
11+
The following resources are created when deploying Websites to Azure:
12+
13+
- Blob Storage Account with Static Website
14+
- Front Door Endpoint (with Front Door Classic)
15+
- Delivery Rules for API rewrites
16+
17+
## Deployment
18+
19+
During deployment the Nitric CLI creates a storage account for your website assets and a Front Door distribution to serve them:
20+
21+
- The declared website is created in Blob Storage
22+
- A Front Door endpoint is created to serve your website and rewrite all APIs to `/api/{apiName}` using Delivery Rules
23+
- Cache invalidation is automatic based on changed files

‎docs/reference/preview-features/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Each preview feature will have its own documentation page, which will include in
1717
| [docker-providers](/providers/custom/docker) | CLI v1.39.0 | [feedback](https://github.com/nitrictech/nitric/issues/605) |
1818
| [sql-databases](/sql) | CLI v1.42.0<br/>AWS Provider v1.6.0<br/>Azure Provider v1.9.0<br/>AWS Terraform Provider v1.8.0 | [feedback](https://github.com/nitrictech/nitric/issues/684) |
1919
| [batch-services](/batch) | CLI v1.54.0<br/>AWS Provider v1.14.0<br/>GCP Provider v1.14.0 | [feedback](https://github.com/nitrictech/nitric/issues/685) |
20+
| [websites](/websites) | CLI v1.58.0<br/>AWS Provider v1.18.0<br/>Azure Provider v1.18.0 | [feedback](https://github.com/nitrictech/nitric/issues/748) |
2021

2122
## Released Preview Features
2223

0 commit comments

Comments
 (0)