You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[How to Generate and Serve dbt Docs Locally](#how-to-generate-and-serve-dbt-docs-locally)
6
+
-[Hosting Options](#hosting-options)
7
+
-[Github Pages](#github-pages)
8
+
-[Netlify](#netlify)
9
+
-[S3 and CloudFront](#s3-and-cloudfront)
10
+
-[S3, CloudFront, and Microsoft Entra ID SSO](#s3-cloudfront-and-microsoft-entra-id-sso)
11
+
-[S3, CloudFront, and Cognito](#s3-cloudfront-and-cognito)
12
+
-[Deployment Steps](#deployment-steps)
13
+
-[Reference](#reference)
13
14
14
-
# How to Generate and Serve dbt Docs Locally
15
+
## Overview
16
+
This repository contains demo code showcasing various options for hosting dbt (data build tool) documentation.
17
+
18
+
## How to Generate and Serve dbt Docs Locally
15
19
16
20
To generate and serve dbt docs locally, follow these simple steps:
17
21
18
-
1.**Generate the Document:** Open your terminal or command prompt and run the following command to generate the dbt document:
22
+
1.**Generate the Documentation:** Open your terminal or command prompt and run the following command to generate the dbt documentation:
19
23
20
-
`dbt docs generate`, This command will create the necessary documentation files based on your dbt project.
24
+
```
25
+
dbt docs generate
26
+
```
27
+
28
+
This command will create the necessary documentation files based on your dbt project.
21
29
22
-
2.**Serve the Document:** After generating the documentation, use the following command to serve it locally:
30
+
2.**Serve the Documentation:** After generating the documentation, use the following command to serve it locally:
31
+
32
+
```
33
+
dbt docs serve
34
+
```
35
+
36
+
By default, the documentation will be served on port 8080. To specify a custom port, use:
23
37
24
-
`dbt docs serve`. By default, the documentation will be served on port 8080. However, if you want to specify a custom port, you can use the following command `dbt docs serve --port 3000`. This will serve the documentation on port 3000 (you can replace "3000" with any port of your choice).
38
+
```
39
+
dbt docs serve --port 3000
40
+
```
41
+
42
+
This will serve the documentation on port 3000 (replace "3000" with any port of your choice).
25
43
26
-
3.**View the dbt Document:** Open your web browser and navigate to [http://localhost:8080/](http://localhost:8080/) (or the custom port you specified) to access and view your dbt document.
44
+
3.**View the Documentation:** Open your web browser and navigate to [http://localhost:8080/](http://localhost:8080/) (or your custom port) to access and view your dbt documentation.
27
45
28
-
That's it! Now you have your dbt documentation generated and served locally for easy access and review.
46
+
That's it! Now you have your dbt documentation generated and served locally for easy access and review.
29
47
30
-
# Hosting Options
31
-
Here are some user-friendly hosting options for static websites like dbt docs:
48
+
##Hosting Options
49
+
Here are several user-friendly hosting options for static websites like dbt docs:
32
50
33
-
## Github Pages
51
+
###Github Pages
34
52
The simplest and most straightforward option. It comes with no extra cost, but there's a limitation: sites hosted on Github Pages will be public in the free tier. For private access and authentication setup, an enterprise tier is required.
35
53
36
-
## Netlify
37
-
A powerful serverless platform with an intuitive git-based workflow. Netlify allows to host static websites with ease. This is simple as well but preferenced below github pages only because it sits outside github eco system.
54
+
###Netlify
55
+
A powerful serverless platform with an intuitive git-based workflow. Netlify allows you to host static websites with ease. This is simple as well but ranked below Github Pages only because it sits outside the GitHub ecosystem.
38
56
39
-
## S3 and CloudFront
57
+
###S3 and CloudFront
40
58
A cost-effective option that offers the ability to add basic authentication for restricted access. S3 (Simple Storage Service) provides reliable storage for your static content, and CloudFront serves as a content delivery network for faster and more efficient distribution.
41
59
42
-
## S3, CloudFront, and Cognito
43
-
The most robust option that provides the ability to let users sign up for access. In addition to S3 and CloudFront, Amazon Cognito is used to manage user identities and authentication. This setup allows you to control who can access your dbt docs by creating user pools and defining user sign-up and sign-in processes.
60
+
### S3, CloudFront, and Microsoft Entra ID SSO
61
+
A robust enterprise solution that leverages your existing Microsoft identity system. This option allows you to authenticate users with their Microsoft Entra ID (formerly Azure AD) credentials, making it ideal for organizations already using Microsoft services. The implementation uses Lambda@Edge for authentication at the edge, providing a seamless and secure user experience without requiring server-side components.
62
+
63
+
See the [cloudfront-microsoft-sso](./terraform/cloudfront-microsoft-sso/README.md) module for implementation details.
64
+
65
+
### S3, CloudFront, and Cognito
66
+
Another comprehensive option that provides the ability to let users sign up for access. In addition to S3 and CloudFront, Amazon Cognito is used to manage user identities and authentication. This setup allows you to control who can access your dbt docs by creating user pools and defining user sign-up and sign-in processes.
44
67
45
-
# Deployment Steps
68
+
##Deployment Steps
46
69
To deploy your dbt docs website, follow these steps:
47
70
48
71
1.**Configure AWS Credentials:**
@@ -53,27 +76,27 @@ To deploy your dbt docs website, follow these steps:
53
76
```
54
77
55
78
2.**Initialize Terraform:**
56
-
Initialize Terraform in the project directory using the following command:
79
+
Initialize Terraform in the project directory using the following command:
57
80
58
-
```
59
-
terraform init
60
-
```
81
+
```
82
+
terraform init
83
+
```
61
84
62
85
3.**Format Terraform Configuration:**
63
-
Ensure that your Terraform configuration files are properly formatted for consistency:
86
+
Ensure that your Terraform configuration files are properly formatted for consistency:
64
87
65
-
```
66
-
terraform fmt -recursive
67
-
```
88
+
```
89
+
terraform fmt -recursive
90
+
```
68
91
69
92
4.**Deploy the Infrastructure:**
70
-
Apply the Terraform configuration to deploy your infrastructure:
93
+
Apply the Terraform configuration to deploy your infrastructure:
71
94
72
-
```
73
-
terraform apply
74
-
```
95
+
```
96
+
terraform apply
97
+
```
75
98
76
-
# Reference
99
+
##Reference
77
100
Here are some useful references and resources related to hosting dbt docs and implementing authentication:
78
101
79
102
-[AWS Static Website Hosting with Cognito and S3](https://howtoember.wordpress.com/2020/06/11/aws-static-website-hosting-with-cognito-and-s3/)
@@ -82,3 +105,4 @@ Here are some useful references and resources related to hosting dbt docs and im
82
105
-[Cognito Auth Example (sashee GitHub)](https://github.com/sashee/cognito-auth-example)
0 commit comments