Skip to content

Commit cd7276b

Browse files
davidcheungdavidcheung
authored
Documentation website (#69)
* doc-site: initial setup * doc-site: static assets and doc files * 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 524a958 commit cd7276b

Some content is hidden

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

46 files changed

+21106
-0
lines changed

‎.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/backend-go
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/module-life-cycle.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Module Life cycle
3+
sidebar_label: Module Life cycle
4+
sidebar_position: 4
5+
---
6+
7+
8+
## Prerequisites
9+
The CI/CD pipeline of the module requires AWS EKS cluster to be available as the deployment destination, it setups a namespace / ingress / service / deployment during the pipeline.
10+
11+
## Scaffold
12+
Based on Parameters in Project definition(`zero-project.yml`), module will be scaffolded and templated out during Zero create
13+
14+
Options that alter the templated repository
15+
- `database`: whether to include `mysql`/`postgresql` database driver
16+
- `userAuth`: Determines whether user auth provider is included in your repository
17+
- `CIVendor`: Scaffolds one of CircleCI / Github actions deployment pipeline
18+
- `billingEnabled`: Includes billing page to load products and api calls to communicated with backend service, and API key in `config.json`
19+
20+
21+
## Module Initialize phase
22+
_Run once only during `zero apply`_
23+
- Sets up CI pipeline with `env-vars` and secrets containing CI-user's AWS Credentials
24+
- Github Actions will rerun the initial commit since it was first ran without the credentials (during `zero create`)
25+
26+
## On-going
27+
### Pull request
28+
- Unit test
29+
### Push to master branch
30+
- Unit test
31+
- Build docker image
32+
- Deploy image to Staging cluster using Kustomize
33+
- Deploy image to Production cluster using Kustomize

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Module Parameters
3+
sidebar_label: Module Parameters
4+
sidebar_position: 2
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+
| accessKeyId | AWS AccessKeyId | AWS_ACCESS_KEY_ID | null |
14+
| secretAccessKey | AWS SecretAccessKey | AWS_SECRET_ACCESS_KEY | null |
15+
| githubAccessToken | Github API Key to setup your repository and optionally CI/CD | GITHUB_ACCESS_TOKEN | null |
16+
| region | Select AWS Region | n/a | null |
17+
| productionHostRoot | Production Root Host Name (e.g. mydomain.com) - this must be the root of the chosen domain, not a subdomain. | n/a | null |
18+
| productionFrontendSubdomain | Production Frontend Host Name (e.g. app.) | n/a | app. |
19+
| productionBackendSubdomain | Production Backend Host Name (e.g. api.) | n/a | api. |
20+
| 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 |
21+
| stagingFrontendSubdomain | Staging Frontend Host Name (e.g. app.) | n/a | app. |
22+
| stagingBackendSubdomain | Staging Backend Host Name (e.g. api.) | n/a | api. |
23+
| database | Database engine to use (postgres) | n/a | null |
24+
| cacheStore | Cache store to use (default: no cache) | n/a | null |
25+
| accountId | AWS Account ID | n/a | null |
26+
| randomSeed | Random seed that will be shared between projects to come up with deterministic resource names | n/a | null |
27+
| databaseName | n/a | n/a | null |
28+
| fileUploads | Enable file uploads using S3 and Cloudfront signed URLs? (Will require manual creation of a Cloudfront keypair in AWS) | n/a | true |
29+
| userAuth | Enable user management using Kratos and authentication using the Oathkeeper access proxy? | n/a | true |
30+
| CIVendor | Using either circleCI or github Actions to build / test your repository | n/a | circleci |
31+
| circleciApiKey | Circle CI API Key to setup your CI/CD for repositories | CIRCLECI_API_KEY | null |
32+
| billingEnabled | Provides a subscription example using stripe in backend and frontend repository, this includes the checkout feature so you must have a verified(with bank account setup) Stripe account to use these features | n/a | null |
33+
| stagingStripePublicApiKey | Staging Stripe public api key, used for frontend repository (Recommended: using sandbox key while setting up) | n/a | null |
34+
| stagingStripeSecretApiKey | Staging Stripe secret api key, used for backend repository (Recommended: using sandbox key while setting up) | n/a | null |
35+
| productionStripePublicApiKey | Production Stripe public api key, used for frontend repository (Recommended: using sandbox key while setting up) | n/a | null |
36+
| productionStripeSecretApiKey | Production Stripe secret api key, used for backend repository (Recommended: using sandbox key while setting up) | n/a | null |
37+
38+
:::info
39+
Content generated by
40+
```shell
41+
## requires binary: `yq`
42+
which yqq >/dev/null || echo "Please install yq"
43+
cat <<EOF
44+
| Parameter | Label | Env-var(apply) | Default |
45+
|--|---|---|---|
46+
EOF
47+
cat zero-module.yml | yq -r '.parameters[] | "| " + .field + " | " + (.label//"n/a") + " | " + (.envVarName //"n/a") + " | " + ((.default)|tostring //"n/a") + " | "'
48+
```
49+
:::

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Overview
3+
sidebar_label: Overview
4+
sidebar_position: 1
5+
---
6+
7+
This is a [Zero][zero] module which sets up a
8+
service which can be deployed to the environment set up with [zero-aws-eks-stack][zero-infra].
9+
10+
The `/templates` folder is meant to be filled in via [Zero][zero] and results in Simple Go Service with a status endpoint. It also contains a simple CircleCI pipeline which defines how to build and deploy the service.
11+
12+
This repository is language/business-logic agnostic; mainly showcasing some universal best practices:
13+
- Built in containerization with docker
14+
- Deployment flow with kubernetes
15+
- Out of the box CI/CD flow CircleCi
16+
- testing
17+
- building docker image
18+
- uploading docker image to private registry (ECR)
19+
- deploy with kustomize
20+
- manual approval step for production environment
21+
22+
23+
### Frontend Repo
24+
25+
The corresponding frontend for this app is [zero-deployable-react-frontend][zero-frontend].
26+
27+
28+
<!-- Links -->
29+
[zero]: https://github.com/commitdev/zero
30+
[zero-infra]: https://github.com/commitdev/zero-aws-eks-stack
31+
[zero-frontend]: https://github.com/commitdev/zero-deployable-react-frontend

‎doc-site/docs/components/billing.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Billing using Stripe
3+
sidebar_label: Stripe
4+
sidebar_position: 3
5+
---
6+
7+
## Billing example
8+
If you have enabled Billing from Zero, a subscription and checkout example using [Stripe](https://stripe.com), coupled with the backend repository to provide an end-to-end checkout example for you to customize. We also setup a webhook and an endpoint in the backend to receive webhook when events occur.
9+
10+
### Requirements
11+
This billing example requires the following backend API endpoints:
12+
```
13+
GET /billing/products
14+
POST /billing/success
15+
POST /billing/cancel
16+
POST /billing/checkout
17+
```
18+
19+
### Initialization
20+
`zero apply` will run a script adding your Stripe API keys to external secret, allowing your kubernetes deployment to access it.
21+
22+
23+
### Setup
24+
The following example content has been set up in Stripe:
25+
- 1 product
26+
- 3 prices(subscriptions) [annual, monthly, daily]
27+
- 1 webhook [`charge.failed`, `charge.succeeded`, `customer.created`, `subscription_schedule.created`]
28+
See link for available webhooks: https://stripe.com/docs/api/webhook_endpoints/create?lang=curl#create_webhook_endpoint-enabled_events
29+
30+
this is setup using the script [scripts/stripe-example-setup.sh][backend-stripe-setup-script]
31+
32+
### Deployment
33+
The initialization step already added your Stripe API key to AWS secret manager hooked up with External Secrets, if you need to update the API Key you can simply edit the value in AWS Secret Manager (this will mean you have to update the frontend publishable key as well)
34+
35+
[backend-stripe-setup-script]: https://github.com/commitdev/zero-deployable-backend/blob/main/templates/scripts/stripe-example-setup.sh

‎doc-site/docs/components/user-auth.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: User Auth
3+
sidebar_label: User Auth
4+
sidebar_position: 1
5+
---
6+
7+
## Authentication
8+
If you enabled `user_auth` from Project definition. An authentication setup would be templated out along side your frontend application.
9+
With examples of:
10+
- Authenticated and Unauthenticated navigation bar
11+
- Auth-provider implemented with user status checking
12+
- Home page with 2 blocks of data from backend, one requiring authentication
13+
- Signup/Login/Password reset forms secured with CSRF token
14+
- Example of backend API calls authenticated via https only cookie using signed JWT tokens
15+
16+
## Concept
17+
This example is built with backend components [ORY Oathkeepr][oathkeeper] as an access identity proxy and [ORY Kratos][kratos] as user-management system.
18+
19+
### Ingress
20+
When user-auth is enabled, instead of routing your request straight to your service, it will go through the access proxy - Oathkeeper, then if it satisfies the rules it will then continue en-route to your application service. This comes with multiple rules (Based on regexp)
21+
-
22+
23+
### Forms
24+
Forms on the frontend are secured with [CSRF tokens][csrf], they are a nonce that ensure the request cannot be repeatedly executed. Each form request(signup/login/password reset) are initiated and identifiable.
25+
26+
### API calls to the backend
27+
API calls to the backend are authenticated via the Oathkeeper proxy, they are made to the backend with `credentials: include`
28+
```javascript
29+
fetch(uri,{ credentials : "include" });
30+
```
31+
This will pass along `same-origin`'s cookie along with the request, and through Oathkeeper Proxy will inspect the Cookie against Kratos for authenticity and expiry, and upon unauthenticated request it will return `401 Unauthorized` and request **will not** make it to the backend service.
32+
33+
34+
[kratos]: https://github.com/ory/kratos
35+
[oathkeeper]: https://github.com/ory/oathkeeper
36+
[csrf]:https://owasp.org/www-community/attacks/csrf

‎doc-site/docs/guides/ci-cd-pipeline.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Continuous Integration and Delivery
3+
sidebar_label: CI/CD
4+
sidebar_position: 2
5+
---
6+
7+
## Circle CI
8+
Your repository comes with a end-to-end CI/CD pipeline, which includes the following steps:
9+
1. Checkout
10+
2. Unit Tests
11+
3. Build and Push Image
12+
4. Deploy Staging
13+
5. Integration Tests
14+
6. Approval to Deploy to production
15+
7. Deploy Production
16+
17+
18+
[See details on CircleCi][circleci-details]
19+
20+
## Github actions
21+
Your repository comes with a end-to-end CI/CD pipeline, which includes the following steps:
22+
1. Checkout
23+
2. Unit Tests
24+
3. Build Image
25+
4. Upload Image to ECR
26+
4. Deploy image to Staging cluster
27+
5. Integration tests
28+
6. Deploy image to Production cluster
29+
30+
**Note**: you can add a approval step using Github Environments(Available for Public repos/Github pro), you can configure an environment in the Settings tab then simply add the follow to your ci manifest (`./.github/workflows/ci.yml`)
31+
```yml
32+
deploy-production: # or any step you would like to require Explicit approval
33+
enviroments:
34+
name: <env-name>
35+
```
36+
### Branch Protection
37+
Your repository comes with a protected branch `master` and you can edit Branch protection in **Branches** tab of Github settings. This ensures code passes tests before getting merged into your default branch.
38+
By default it requires `[lint, unit-test]` to be passing to allow Pull requests to merge.
39+
<% end %>
40+
41+
[circleci-details]: https://github.com/commitdev/zero-deployable-node-backend/tree/main/templates/.circleci/README.md
42+
[github-actions]: https://github.com/commitdev/zero-deployable-node-backend/tree/main/templates/.github/workflows/ci.yml

0 commit comments

Comments
 (0)