diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index eedbc6258e..649151e36e 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -54,6 +54,50 @@ Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-gui ::: +## Choosing a hosting provider + +There are a few common hosting options: + +- [Self hosting](#self-hosting) with an HTTP server like Apache2 or Nginx; +- Jamstack providers, e.g. [Netlify](#deploying-to-netlify) and [Vercel](#deploying-to-vercel). We will use them as references, but the same reasoning can apply to other providers. +- [GitHub Pages](#deploying-to-github-pages). (By definition, it is also Jamstack, but we compare it separately.) + +If you are unsure of which one to choose, ask the following questions: + +
+ + + How much resource (person-hours, money) am I willing to invest in this? + + +- πŸ”΄ Self-hosting is the hardest to set upβ€”you would usually need an experienced person to manage this. Cloud services is almost never free, and setting up an on-site server and connecting it to the WAN can be more costly. +- 🟒 Jamstack providers can help you set up a working website in almost no time and offers features like server-side redirects that are easily configurable. Many providers offer generous build time quota even for free plans that you would almost never exceed. However, it's still ultimately limitedβ€”you would need to pay once you hit the limit. Check the pricing page of your provider for details. +- 🟑 The GitHub Pages deployment workflow can be tedious to set up. (Evidence: see the length of [Deploying to GitHub Pages](#deploying-to-github-pages)!) However, this service (including build and deployment) is always free for public repositories, and we have detailed instructions to help you make it work. + +
+ +
+ +How much server-side configuration would I need? + +- 🟒 With self-hosting, you have access to the entire server's configuration. You can configure the virtual host to serve different content based on the request URL; you can do complicated server-side redirects; you can put part of the site behind authentication... If you need a lot of server-side features, self-host your website. +- 🟑 Jamstack usually offers some server-side configurations, e.g. URLs formatting (trailing slashes), server-side redirects... +- πŸ”΄ GitHub Pages doesn't expose server-side configurations besides enforcing HTTPS and setting CNAME. + +
+ +
+ +Do I have needs to cooperate? + +- 🟑 Self-hosted services can achieve the same effect as Netlify, but with much more heavy-lifting. Usually, you would have a specific person who looks after the deployment, and the workflow won't be very git-based as opposed to the other two options. +- 🟒 Netlify and Vercel have deploy previews for every pull request, which is useful for a team to review work before merging to production. You can also manage a team with different member access to the deployment. +- 🟑 GitHub Pages cannot do deploy previews in a non-convoluted way. One repo can only be associated with one site deployment. On the other hand, you can control who has write access to the site's deployment. + +
+ +There isn't a silver bullet. You need to weigh your needs and resources before making a choice. + ## Self-Hosting {#self-hosting} Docusaurus can be self-hosted using [`docusaurus serve`](cli.md#docusaurus-serve-sitedir). Change port using `--port` and `--host` to change host. @@ -70,12 +114,78 @@ It is not the best option, compared to a static hosting provider / CDN. :::warning -In the following sections, we will introduce a few common hosting providers and how they should be configured to deploy Docusaurus sites most efficiently. The documentation may not be up-to-date: recent changes in their API may not be reflected on our side. If you see outdated content, PRs are welcome. +In the following sections, we will introduce a few common hosting providers and how they should be configured to deploy Docusaurus sites most efficiently. Some of the writeups are provided by external contributors. Docusaurus is not interest-related with any of the services. The documentation may not be up-to-date: recent changes in their API may not be reflected on our side. If you see outdated content, PRs are welcome. For the same concern of up-to-datedness, we have stopped accepting PRs adding new hosting options. You can, however, publish your writeup on a separate site (e.g. your blog, or the provider's official website), and ask us to include a link to your writeup. ::: +## Deploying to Netlify {#deploying-to-netlify} + +To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: + +```js {2-3} title="docusaurus.config.js" +module.exports = { + url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash + baseUrl: '/', // Base directory of your site relative to your repo + // ... +}; +``` + +Then, [create your site with Netlify](https://app.netlify.com/start). + +While you set up the site, specify the build commands and directories as follows: + +- build command: `npm run build` +- build directory: `build` + +If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created. + +Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`. + +:::caution + +Some Docusaurus sites put the `docs` folder outside of `website` (most likely former Docusaurus v1 sites): + +```bash +repo # git root +β”œβ”€β”€ docs # md files +└── website # docusaurus root +``` + +If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/): + +```toml title="website/netlify.toml" +[build] + ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/" +``` + +::: + +:::warning + +By default, Netlify adds trailing slashes to Docusaurus URLs. + +It is recommended to disable the Netlify setting `Post Processing > Asset Optimization > Pretty Urls` to prevent lowercased URLs, unnecessary redirects, and 404 errors. + +**Be very careful**: the `Disable asset optimization` global checkbox is broken and does not really disable the `Pretty URLs` setting in practice. Please make sure to **uncheck it independently**. + +If you want to keep the `Pretty Urls` Netlify setting on, adjust the `trailingSlash` Docusaurus config appropriately. + +Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) for more information. + +::: + +## Deploying to Vercel {#deploying-to-vercel} + +Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use. + +To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository. + +Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings). + +After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (usually "main" or "master") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). + ## Deploying to GitHub Pages {#deploying-to-github-pages} Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/), which comes for free with every GitHub repository. @@ -488,73 +598,7 @@ trigger: from_secret: git_deploy_private_key ``` -Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website. - -## Deploying to Netlify {#deploying-to-netlify} - -To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: - -```js {2-3} title="docusaurus.config.js" -module.exports = { - url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash - baseUrl: '/', // Base directory of your site relative to your repo - // ... -}; -``` - -Then, [create your site with Netlify](https://app.netlify.com/start). - -While you set up the site, specify the build commands and directories as follows: - -- build command: `npm run build` -- build directory: `build` - -If you did not configure these build options, you may still go to "Site settings" -> "Build and deploy" after your site is created. - -Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`. - -:::caution - -Some Docusaurus sites put the `docs` folder outside of `website` (most likely former Docusaurus v1 sites): - -```bash -repo # git root -β”œβ”€β”€ docs # md files -└── website # docusaurus root -``` - -If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/): - -```toml title="website/netlify.toml" -[build] - ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/" -``` - -::: - -:::warning - -By default, Netlify adds trailing slashes to Docusaurus URLs. - -It is recommended to disable the Netlify setting `Post Processing > Asset Optimization > Pretty Urls` to prevent lowercased URLs, unnecessary redirects and 404 errors. - -**Be very careful**: the `Disable asset optimization` global checkbox is broken and does not really disable the `Pretty URLs` setting in practice. Please make sure to **uncheck it independently**. - -If you want to keep the `Pretty Urls` Netlify setting on, adjust the `trailingSlash` Docusaurus config appropriately. - -Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-guide) for more information. - -::: - -## Deploying to Vercel {#deploying-to-vercel} - -Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use. - -To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository. - -Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings). - -After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). +Now, whenever you push a new tag to GitHub, this trigger will start the drone CI job to publish your website. ## Deploying to Render {#deploying-to-render}