mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
docs(deployment): add cost-benefit analysis with different options (#6026)
This commit is contained in:
Joshua Chen
GitHub
parent
40e4ce0e68
commit
373eda272e
1 changed files with 112 additions and 68 deletions
|
|
@ -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:
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
How much resource (person-hours, money) am I willing to invest in this?
|
||||
</summary>
|
||||
|
||||
- 🔴 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.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>How much server-side configuration would I need?</summary>
|
||||
|
||||
- 🟢 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.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Do I have needs to cooperate?</summary>
|
||||
|
||||
- 🟡 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.
|
||||
|
||||
</details>
|
||||
|
||||
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}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue