Build static site once and deploy on multiple hosts

[hassanfarid]

❓ Questions and Help

I want to build my documentation for being hosted in multiple offline environments, hosted on docker containers. This requires following key features in static site generator,

• Use all resources (js / css), hosted locally with static html files.
• Configure url and baseUrl at deployment time (when docker container is started).

These two configurations can help achieve, build once deploy anywhere, and in an offline environment.

Two questions,

• How to set url at deploy time?
• How to set all resources to be hosted locally?

Please note that this issue tracker is not a help form and this issue will be closed.

Please contact us instead. We have a few channels:

• Stack Overflow
• Twitter
• Discord

[amimas]

I think this is related to #448

[endiliey]

I think this is more of a continuous integration question. You can always use environment variable for this.

Jest, for example configure their algolia api key through their CI
https://github.com/facebook/jest/blob/c5fd7aae93764c13c259ae9a73846c10e84ae2a3/website/siteConfig.js#L113

Please note that this issue tracker is not a help form and this issue will be closed.

[sarahhenkens]

I ran into this same problem today. I have a single docker image that I move through environment stages from dev -> staging -> prod. The docker image itself never changes, but the configuration needs to be able to be dynamically set at runtime.

@endiliey I don't think this is a responsibility for CI. Its a known best practice to not have divergent docket images between environments.

[slorber]

@sarahhenkens this issue is old, Docusaurus v1 and see also https://docusaurus.io/blog/2020/01/07/tribute-to-endi

We don't say to use a different Docker image for all envs, just to change environment variables of your container.

You can read them using process.env.MY_ENV_VARIABLE in the Docusaurus config file so that you build your site with different configs.

---

It is not recommended to build your site once, and then deploy it to multiple locations.

There are many SEO pages metadata in the static HTML that Docusaurus produces that must be absolute URLs including the domain and baseUrl.

For example, canonical URL, hreflang....

<link data-rh="true" rel="canonical" href="https://docusaurus.io/docs/installation">

I'd also recommend to build your staging deployments with a "noIndex" setting otherwise Google could index your staging site and penalize the SEO of your prod website for having duplicates.

https://docusaurus.io/docs/api/docusaurus-config#noIndex

Some better hosts like Vercel/Netlify do this for you on deploy previews automatically: I'd really recommend those to host Docusaurus instead of your custom Docker setup, it's a much better experience and free or not very expensive. (see: https://twitter.com/leeerob/status/1554211061284364290)

---

I don't know which config you talk about exactly, but anything that impacts the static output means you can't make it dynamic => most config changes will impact the static HTML files being built and you'd have to rebuild on config changes.

You can't build once for all envs, or at least we don't want to encourage such pattern. If the domain, baseUrl or whatever changes, you should rather rebuild.

[sarahhenkens]

We don't say to use a different Docker image for all envs, just to change environment variables of your container.
You can read them using process.env.MY_ENV_VARIABLE in the Docusaurus config file so that you build your site with different configs.

Since these env variables are used only during the docusaurus build step, we would need to build it at pod start. Which takes about 15 mins to compile on our documentation site.

Its also an internal docs site which will never be crawled by search engine, so the seo tags being wrong are not that concerning.

I also posted about this issue in the discord server: https://discord.com/channels/398180168688074762/601200852337688586/1006727071277535233