Skip to content

Commit 04e2d42

Browse files
davidcheungdavidcheung
authored
Documentation Site (#208)
* doc-site: initial setup for eks stack * doc-site: static files and docs * doc-site: build and deploy via gha * doc-site: using packaged common elements * doc-site: update common elements * doc-site: sidebar target self * doc-site: update docusaurus version
1 parent 0a1a276 commit 04e2d42

51 files changed

Lines changed: 21845 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/doc-site.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: "Build Documentation Site"
2+
on:
3+
push:
4+
branches:
5+
- main
6+
- doc-site
7+
paths:
8+
- doc-site/**
9+
10+
env:
11+
region: us-west-2
12+
s3_sync_path: /docs/modules/aws-eks-stack
13+
BUILD_DOMAIN: ${{ secrets.ZERO_DOC_SITE_DOMAIN_NAME }}
14+
jobs:
15+
build:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v2
19+
- name: Setup node.js
20+
uses: actions/setup-node@v1
21+
with:
22+
node-version: 14.x
23+
- name: Install Dependencies
24+
working-directory: doc-site
25+
run: npm install
26+
- name: Build website
27+
working-directory: doc-site
28+
run: |
29+
npm run build
30+
ls -la
31+
- name: Upload build artifact to Github
32+
uses: actions/upload-artifact@v2
33+
with:
34+
name: build-artifact
35+
path: doc-site/build
36+
37+
deploy:
38+
name: Deploy
39+
runs-on: ubuntu-latest
40+
needs: build
41+
42+
steps:
43+
# Once github action supports nested composite actions (anything `uses` is a composite action)
44+
# Therefore we cannot reuse the code as a separate composite action until it supports it,
45+
# current the deploy logic is in this file twice because of it
46+
## https://github.com/actions/runner/issues/862
47+
- uses: actions/checkout@v2
48+
- name: Configure AWS credentials for S3 sync
49+
uses: aws-actions/configure-aws-credentials@v1
50+
with:
51+
aws-access-key-id: ${{ secrets.ZERO_DOC_SITE_AWS_ACCESS_KEY_ID }}
52+
aws-secret-access-key: ${{ secrets.ZERO_DOC_SITE_AWS_SECRET_ACCESS_KEY }}
53+
aws-region: ${{ env.region }}
54+
- name: Download build artifact from Github
55+
uses: actions/download-artifact@v1
56+
with:
57+
name: build-artifact
58+
path: build/
59+
- name: Sync with S3
60+
shell: bash
61+
run: |
62+
cd build
63+
aws s3 sync . "s3://${{ secrets.ZERO_DOC_SITE_BUCKET_NAME }}${{ env.s3_sync_path }}" --delete
64+
- name: Invalidate Cloudfront
65+
shell: bash
66+
run: |
67+
export DIST_ID=$(aws cloudfront list-distributions --query "DistributionList.Items[?Aliases.Items[?@=='${{ secrets.ZERO_DOC_SITE_BUCKET_NAME }}']].Id | [0]" | tr -d '"')
68+
aws cloudfront create-invalidation --distribution-id ${DIST_ID} --paths "${{ env.s3_sync_path }}*"

‎doc-site/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*
21+
22+
# This is downloaded during build time
23+
# to sync with zero core styles
24+
src/css/zero-downloaded-global-custom.css

‎doc-site/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
4+
5+
## Installation
6+
7+
```console
8+
yarn install
9+
```
10+
11+
## Local Development
12+
13+
```console
14+
yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
## Build
20+
21+
```console
22+
yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
## Deployment
28+
29+
```console
30+
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
31+
```
32+
33+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎doc-site/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎doc-site/docs/about/architecture-overview.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Architecture Overview
3+
sidebar_label: Architecture Overview
4+
sidebar_position: 2
5+
---
6+
7+
## Architecture Diagram
8+
9+
10+
This diagram is a high-level overview of components that are setup in the default scenario as a reference.
11+
![Architecture diagram](./architecture-overview.svg)
12+
13+
:::note Updating the diagram
14+
The diagram is generated using [draw.io] and the source file is committed to the docs, to make updates to the diagram please create pull-request with **both the Svg and the source file**.
15+
:::
16+
17+
[draw.io]: https://www.diagrams.net/

‎doc-site/docs/about/architecture-overview.svg‎

Lines changed: 3 additions & 0 deletions
Loading

‎doc-site/docs/about/module-file-structure.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Repository structure
3+
sidebar_label: Repository Structure
4+
sidebar_position: 3
5+
---
6+
7+
The root folder is used for declaring parameters required by the templates, and [Zero][zero] will gather the required parameters and parse the templates as individual repositories for user to maintain.
8+
```shell
9+
/ # file in the root directory is for initializing the user's repo and declaring metadata
10+
|-- Makefile #make command triggers the initialization of repository
11+
|-- zero-module.yml #module declares required parameters and credentials
12+
|
13+
| # files in templates become the repo for users
14+
| templates/
15+
| | # this makefile is used both during init and
16+
| | # on-going needs/utilities for user to maintain their infrastructure
17+
| |-- Makefile
18+
| |-- terraform/
19+
| | |-- bootstrap/ #initial setup
20+
| | |-- environments/ #infrastructure setup
21+
| | | |-- prod/
22+
| | | |-- stage/
23+
| |-- kubernetes
24+
| | |-- terraform
25+
| | | |-- environments #k8s-ultities
26+
| | | | |-- prod/
27+
| | | | |-- stage/
28+
```

‎doc-site/docs/about/module-parameters.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Module Parameters
3+
sidebar_label: Module Parameters
4+
sidebar_position: 4
5+
---
6+
7+
## Parameters
8+
9+
| Parameter | Label | Env-var(apply) | Default |
10+
|--|---|---|---|
11+
| useExistingAwsProfile | Use credentials from an existing AWS profile? | n/a | null |
12+
| profilePicker | n/a | n/a | null |
13+
| awsProfile | Profile to use with terraform AWS provider | AWS_PROFILE | null |
14+
| accessKeyId | AWS AccessKeyId | AWS_ACCESS_KEY_ID | null |
15+
| secretAccessKey | AWS SecretAccessKey | AWS_SECRET_ACCESS_KEY | null |
16+
| githubAccessToken | Github API Key to setup your repository and optionally CI/CD | GITHUB_ACCESS_TOKEN | null |
17+
| region | Select AWS Region | n/a | null |
18+
| productionHostRoot | Production Root Host Name (e.g. mydomain.com) - this must be the root of the chosen domain, not a subdomain. | n/a | null |
19+
| productionFrontendSubdomain | Production Frontend Host Name (e.g. app.) | n/a | app. |
20+
| productionBackendSubdomain | Production Backend Host Name (e.g. api.) | n/a | api. |
21+
| stagingHostRoot | Staging Root Host Name (e.g. mydomain-staging.com) - this must be the root of the chosen domain, not a subdomain. | n/a | null |
22+
| stagingFrontendSubdomain | Staging Frontend Host Name (e.g. app.) | n/a | app. |
23+
| stagingBackendSubdomain | Staging Backend Host Name (e.g. api.) | n/a | api. |
24+
| CIVendor | Using either circleCI or github Actions to build / test your repository | n/a | circleci |
25+
| circleciApiKey | Circle CI API Key to setup your CI/CD for repositories | CIRCLECI_API_KEY | null |
26+
| database | Database engine to use (postgres) | n/a | null |
27+
| cacheStore | Cache store to use (default: no cache) | n/a | null |
28+
| loggingType | Application logging to configure. Cloudwatch is cheaper with a more limited feature set. Elasticsearch + Kibana will set up more infrastructure but enable a much richer logging search and visualization experience. | n/a | null |
29+
| metricsType | Additional application metrics method to configure. Metrics are available through CloudWatch, but choosing prometheus will install Prometheus and Grafana, for a richer metrics experience. No additional infrastructure is required, but a number of prometheus pods will need to exist in the cluster, utilizing some resources. | n/a | null |
30+
| notificationServiceEnabled | Install the Zero Notification Service in your cluster? | n/a | true |
31+
| sendgridApiKey | API key to setup email integration (optional: leave blank to opt-out of Sendgrid setup) | n/a | null |
32+
| notificationServiceSlackApiKey | API key of your Slack bot if you want to use Slack with the Zero Notification Service. Leave blank if not applicable. | n/a | null |
33+
| accountId | AWS Account ID | n/a | null |
34+
| randomSeed | Random seed that will be shared between projects to come up with deterministic resource names | n/a | null |
35+
| fileUploads | Enable file uploads using S3 and Cloudfront signed URLs? (Will require manual creation of a Cloudfront keypair in AWS) | n/a | true |
36+
| userAuth | Enable user management using Kratos and authentication using the Oathkeeper access proxy? | n/a | true |
37+
38+
39+
:::info
40+
Content generated by
41+
```shell
42+
## requires binary: `yq`
43+
which yqq >/dev/null || echo "Please install yq"
44+
cat <<EOF
45+
| Parameter | Label | Env-var(apply) | Default |
46+
|--|---|---|---|
47+
EOF
48+
cat zero-module.yml | yq -r '.parameters[] | "| " + .field + " | " + (.label//"n/a") + " | " + (.envVarName //"n/a") + " | " + ((.default)|tostring //"n/a") + " | "'
49+
```
50+
:::

‎doc-site/docs/about/overview.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Overview
3+
sidebar_label: Overview
4+
sidebar_position: 1
5+
---
6+
7+
The Zero-awk-eks stack is designed with scalability and maintainability in mind, this repo is a series of templates indented to be filled in with modules parameters, and executed by zero
8+
This is a [Zero][zero] module which sets up a
9+
hosting environment on AWS running Kubernetes. It will generate terraform output
10+
which describes the environment mapped in this [architecture diagram][arch-diagram].
11+
12+
### **Resource List**:
13+
[Link][resource-list]
14+
15+
### **Prerequisites**
16+
- Terraform installed
17+
- Kubectl installed
18+
- Wget installed
19+
- A valid AWS account
20+
- [Set up the AWS CLI][aws-cli]
21+
- [A domain registered with Route53][aws-route53]
22+
- Note: if you want to use different domain per environment (staging/production), you need to have multiple hosted zones. The available zones in Route53 can be found by running this command. `aws route53 list-hosted-zones`
23+
24+
_Optional Prerequisites_
25+
- [Sendgrid account][sendgrid] with developer [API key][sendgrid-apikey]: this will enable transactional email sending with simple API calls.
26+
27+
28+
<!-- Links -->
29+
[zero]: https://github.com/commitdev/zero
30+
[arch-diagram]: ./architecture-overview
31+
[resource-list]: ../components/resources
32+
<!-- External Links -->
33+
[aws-cli]: https://docs.aws.amazon.com/polly/latest/dg/setup-aws-cli.html
34+
[aws-route53]: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html
35+
[zenhub-board]: https://app.zenhub.com/workspaces/commit-zero-5da8decc7046a60001c6db44/board?filterLogic=any&repos=203630543,247773730,257676371,258369081
36+
[sendgrid]: https://signup.sendgrid.com
37+
[sendgrid-apikey]: https://app.sendgrid.com/settings/api_keys

‎doc-site/docs/components/aws/cost.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Understanding the infrastructure cost
3+
sidebar_label: AWS Infrastructure Cost
4+
sidebar_position: 1
5+
---
6+
7+
:::note TODO
8+
To have a better breakdown / updated version
9+
:::
10+
11+
## How much does this stack cost?
12+
The expected total monthly cost: $ 0.202 USD / hr or ~$150USD / month. The most expensive component will be the EKS cluster as well as the instances that it spins up. Costs will vary depending on the region selected but based on us-west-2 the following items will contribute to the most of the cost of the infrastructure:
13+
14+
EKS Cluster: $0.1 USD / hr
15+
NAT Gateway: $0.045 USD / hr
16+
RDS (db.t3.small): $0.034 USD / hr
17+
EC2 (t2.small): $0.023 USD / hr
18+
EC2 instance sizing can be configured in terraform/environments/stage/main.tf

0 commit comments

Comments
 (0)