fe80e136da
* Add specification about AWS IAM Unique Identifiers We experienced an issue where IAM roles resources were re-provisioned with the same ARNs and no change had been made to our vault role configuration but users lost access with `-method=aws`. It wasn't immediately clear to us how IAM Unique Identifiers where being used to avoid the same situations outlined in the AWS documentation. We eventually concluded that re-provisioning the roles in our auth/aws/auth would fetch the new IAM Unique Identifiers. I hope that this small amendment helps people avoid this problem in the future. |
||
---|---|---|
.. | ||
components | ||
data | ||
layouts | ||
lib | ||
pages | ||
public | ||
.editorconfig | ||
.eslintrc.js | ||
.gitignore | ||
.npm-upgrade.json | ||
Dockerfile | ||
Makefile | ||
README.md | ||
_redirects | ||
babel.config.js | ||
netlify.toml | ||
next.config.js | ||
package-lock.json | ||
package.json | ||
prettier.config.js |
README.md
Vault Website
This subdirectory contains the entire source for the Vault Website. This is a NextJS project, which builds a static site from these source files.
Contributions Welcome!
If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀
Running the Site Locally
The website can be run locally through node.js or Docker. If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node. Also if you are a vim user, it's also worth noting that vim's swapfile usage can cause issues for the live reload functionality. In order to avoid these issues, make sure you have run :set backupcopy=yes
within vim.
With Docker
Running the site locally is simple. Provided you have Docker installed, clone this repo, run make
, and then visit http://localhost:3000
.
The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run make build-image
to generate a local Docker image with updated dependencies, then make website-local
to use that image and preview.
With Node
If your local development environment has a supported version (v10.0.0+) of node installed you can run:
npm install
npm start
and then visit http://localhost:3000
.
If you pull down new code from github, you should run npm install
again. Otherwise, there's no need to re-run npm install
each time the site is run, you can just run npm start
to get it going.
Editing Content
Documentation content is written in Markdown and you'll find all files listed under the /pages
directory.
To create a new page with Markdown, create a file ending in .mdx
in the pages/
directory. The path in the pages directory will be the URL route. For example, pages/hello/world.mdx
will be served from the /hello/world
URL.
This file can be standard Markdown and also supports YAML frontmatter. YAML frontmatter is optional, there are defaults for all keys.
---
title: 'My Title'
description: "A thorough, yet succinct description of the page's contents"
---
The significant keys in the YAML frontmatter are:
title
(string)
- This is the title of the page that will be set in the HTML title.description
(string)
- This is a description of the page that will be set in the HTML description.
⚠️Since
api
is a reserved directory within NextJS, all/api/**
pages are listed under the/pages/api-docs
path.
Editing Sidebars
The structure of the sidebars are controlled by files in the /data
directory.
To nest sidebar items, you'll want to add a new category
key/value accompanied by the appropriate embedded content
values.
category
values will be directory names within thepages
directorycontent
values will be file names within their appropriately nested directory.
Creating New Pages
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
Deployment
This website is hosted on Netlify and configured to automatically deploy anytime you push code to the stable-website
branch. Any time a pull request is submitted that changes files within the website
folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from stable-website
will look and behave the same way as deployment previews.