Deploy Docusaurus on Koyeb

Introduction

Docusaurus is a framework for easily building, deploying, and maintaining documentation websites. Docusaurus provides out-of-the-box documentation features including blog support, internationalization, search, and versioning.

In this guide, we will explain how to deploy your Docusaurus sites to production with continuous deployment on Koyeb.

By deploying your Docusaurus sites on Koyeb using the git-driven deployment method, each time you push new changes to your GitHub repository, a new deployment will occur and be promoted once the build and health checks are completed. Once deployed, your Docusaurus sites will benefit from automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network with zero configuration.

Requirements

To successfully follow and complete this guide, you need:

• A local development environment with Node.js installed
• A Koyeb account to deploy and run the Docusaurus site
• A GitHub account

Steps

To deploy a Docusaurus site to Production on Koyeb, you need to follow these steps:

1. Create a new Docusaurus project
2. Initialize a git repository and push your application
3. Deploy the Docusaurus project on Koyeb

Create a new Docusaurus project

Get started by creating a new Docusaurus project by running the following in your terminal:

$ npx create-docusaurus@latest
❯ npx create-docusaurus@latest
✔ What should we name this site? … docusaurus-on-koyeb
✔ Select a template below... › classic (recommended)
✔ This template is available in TypeScript. Do you want to use the TS variant? … yes

You are asked to provide some information about your project:

• The name of the Docusaurus project site. This information will also be used to create a directory to store your project
• The template to use
• And depending on if the template supports it, whether you want to use the TypeScript template version or not

Once the project initialization completed, a skeleton Docusaurus site is created in the folder you specified containing the following files:

docusaurus-on-koyeb
├── README.md
├── babel.config.js
├── blog
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2021-08-01-mdx-blog-post.mdx
│   ├── 2021-08-26-welcome
│   │   ├── docusaurus-plushie-banner.jpeg
│   │   └── index.md
│   └── authors.yml
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   │   ├── _category_.json
│   │   ├── congratulations.md
│   │   ├── create-a-blog-post.md
│   │   ├── create-a-document.md
│   │   ├── create-a-page.md
│   │   ├── deploy-your-site.md
│   │   └── markdown-features.mdx
│   └── tutorial-extras
│       ├── _category_.json
│       ├── manage-docs-versions.md
│       └── translate-your-site.md
├── docusaurus.config.js
├── package.json
├── sidebars.js
├── src
│   ├── components
│   │   ├── HomepageFeatures.module.css
│   │   └── HomepageFeatures.tsx
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── index.module.css
│       ├── index.tsx
│       └── markdown-page.md
├── static
│   └── img
│       ├── docusaurus.png
│       ├── favicon.ico
│       ├── logo.svg
│       ├── tutorial
│       │   ├── docsVersionDropdown.png
│       │   └── localeDropdown.png
│       ├── undraw_docusaurus_mountain.svg
│       ├── undraw_docusaurus_react.svg
│       └── undraw_docusaurus_tree.svg
├── tsconfig.json
└── yarn.lock

12 directories, 38 files

You can ensure that the Docusaurus project is working as expected by launching the site using the following command in your project folder:

cd docusaurus-on-koyeb
yarn start

Your browser should automatically open a new tab pointing to your Docusaurus site located at http://localhost:3000.

Initialize a git repository and push to GitHub

Create a new GitHub repository from the GitHub web interface or using the GitHub CLI by running:

gh repo create <YOUR_GITHUB_REPOSITORY> --private

Initialize a new git repository on your machine running:

git init

Add a new remote pointing to your GitHub repository:

git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY>.git

Add your Docusaurus files to your repository and commit & push the changes:

git add .
git commit -m "Initial commit"
git push -u origin main

Deploy the Docusaurus project on Koyeb

We are now ready to deploy the Docusaurus site on Koyeb.

Go to the Koyeb Control Panel and click the Create App button to go to the App creation page:

1. Select GitHub as the deployment method to use
2. In the repositories list, select the repository containing your Docusaurus site
3. Specify the branch to deploy, in this case, main
4. Set the run command to let Koyeb know how to launch Docusaurus: npm run serve -- -h 0.0.0.0 -p 8080
5. Give your App a name, here docusaurus-on-koyeb, and click Create App

Then, click the Create App button to create and deploy the application. You land on the deployment page where you can follow the progress of your Docusaurus site's deployment. Once the build and deployment are completed, you can access your application by clicking the App URL ending with koyeb.app in the Koyeb control panel.

If you want to learn about how Koyeb automatically builds your Docusaurus site from git, make sure to read our how we build from git documentation.

Conclusion

In this guide, we explained how to deploy a Docusaurus site on Koyeb using git-driven deployment. Now each change you push to your repository will automatically trigger a new build and deployment on the Koyeb Serverless Platform. Your changes then go live as soon as the deployment passes all necessary health checks. In case of a failure during one of your deployments, we ensure to keep the latest working deployment active so your application is always up and running.

Questions or suggestions to improve this guide? Join us on the community platform to chat!