Deploy fast your documentation with authentication with AWS Amplify. Docusaurus is a great documentation tool. The best, even to collaborate with non-technical people. Deploying and securing through an authentication is always a question I see developers facing. Most of the user cases for documentation besides open source require some level of auth. Working remote, this is a simple way to deploy your documentation.
After reading this
- You will now how to deploy Docusaurus using AWS Amplify, lacking in Docusaurus docs itself, which I will submit a PR
- Use Continuous Integration provided by AWS Amplify to always keep your docs up to date
- Implement the minimum auth necessary to protect your docs from the world
What I will NOT cover
- How to set up Docusaurus. Please follow the instructions in the official docs. Which is basically run
npx @docusaurus/init@latest init my-website classicto create a scaffold project
- How to set up the repository for your code being deployed at each new commit to a specific branch.
First, install and configure Amplify in your machine. After this create a
amplify.yml file to the root of your project, commit and push.
version: 1 backend: phases: build: commands: - '# Execute Amplify CLI with the helper script' - amplifyPush --simple frontend: phases: preBuild: commands: - yarn install build: commands: - yarn build artifacts: baseDirectory: build files: - '*/*' cache: paths: - node_modules/**/*
Sidenote: Some time ago I opened a ticket because I never could make my build process follow the steps on the CLI, so just in case, this will enhance your experience. I always have to place this custom file in my projects to work on the first deploy or else it always fails then I have to edit the application deploy settings in the administration of the Amplify project. I assume is a problem with my environment but besides this, works smoothly.
Initialize your Amplify project:
You will be prompted with some questions, choose the ones matches your environment.
Docusaurus is a React application, and the distribution path is inside the build folder, created through the command
yarn build. This will generate static files in a S3 bucket and the distribute through the CDN of CloudFront created by Amplify. Since we’ll be using just static files, we don’t really use a start command.
Amplify then will start initialize both locally and in the cloud your project. Your next step will be the command
amplify add hosting to configure the hosting for your documentation.
It will prompt you by some questions:
? Select the plugin module to execute Hosting with Amplify Console (Managed hosting with custom domains, Continuous deployment) ? Choose a type Continuous deployment (Git-based deployments) ? Continuous deployment is configured in the Amplify Console. Please hit enter once you connect your repository
I always use the continuous deployment option because you can connect your repository (GitHub, Bitbucket and other).
Once your merge to a specific branch defined will automatically build a new version of your project. If you choose manual, you must run
amplify publish everything you need a new deployment.
With this option, Amplify will open a tab in your browser for you connect your provider and you just need to follow the instructions. Once is done, Amplify will start the whole process and then hitting enter in your terminal, you will get the url provided by Amplify that will look something like this:
It is a simple HTTP authentication. If your use case needs roles, I recommend either you create different branches to deploy with the sensitive code and then create different urls for roles or then customize with Cognito making customizations that are not covered here. In my experience, this simple method is enough to protect the documentation.
In the application page, you just need to select “Access control” in the App settings option on the left side menu. To edit you hit manage access, change the access setting to restrict and then define a username and a password with at least 7 characters. Hit save to make effect.
You can customize even further adding a domain if you have one configured in the Route 53. You can create a sub-domain like
docs.acme.com and generate a SSL certificate.
2021-08-03: Updated post with formating issues on code snippets, thanks to Slawa.