Gatsby: Add Documentation For Self Hosting Gatsby Websites

[bonedaddy]

While the documentation for gatsby is great if you're using third-party service providers, if you're self-hosting your gatsby site, the documentation is sparse, to completely doesn't exist. I've spent a solid 30 or so minutes digging through stack overflow posts, the gatsby deploying and hosting documentation, and the closest I came to was https://stackoverflow.com/questions/51828727/hosting-gatsby-on-a-subdirectory-using-nginx.

Initially I thought it would be as simple as building and updating a simple nginx config, but in practice it seems to be a bit more tricky than that once you introduce production environments to the mix that have things like load balancers in between the server, and the internet which appear to muck with the routing that gatsby uses? Either way I think the documentation surely needs to be updated for people and companies that self-host.

[wardpeet]

Thank you for bringing this up. Setting up a site yourself is always tricky. It's hard to create a "host a gatsby site yourself" doc as it depends on hosting providers. Creating a low-level guide, explaining how to organise it through barebone Nginx/apache2 config seems a bit too advanced to me.

However, creating a guide to include the most popular control panels (Cpanel, Plesk & DirectAdmin) seems a great idea. The benefit of these platforms is that we don't have to dive too deep into server internals. Most hosting providers use these as client UI.

What do you think? Would this also fix your issue?

[bonedaddy]

What do you think? Would this also fix your issue? Not entirely, that's making quite big assumptions about the deployments and assuming that the users are using cpanel, plesk, directadmin.

I do agree that Nginx, or Apache is a little low level, but we are talking about websites, which at the end of the day you're going to need a web server to run, so I think it's absolutely needed to have configuration documentation for nginx and apache.

~edit 1: However I would certainly settle for a control panel guide, since I can just pick one that uses nginx, and pull out the configs, and use that to generate a guide so I suppose it would be doable~

edit 2: In hindsight I don't think a guide for popular control panels is acceptable. This is again forcing users of Gatsby to have to choose a third-party, proprietary, non open-source, paid for solution. I literally just want to be able to use gatsby, an amazing project, without having to shell out money for a third-party service, and use the existing infrastructure I have. I do not want to have to install yet another dependency, or service into my infrastructure simply to run a website and have it work properly. I have a somewhat functional installation of gatsby and nginx, but certain aspects are broken because I've had to hack together pieces of solutions I've found on the internet.

Gatsby is website software (and its fantastic website software), so it needs to have guides on how you can set it up like traditional websites, without needing to resort to paying someone else. If anything I would think that using third-party services should have guides added after the usual suspects (nginx, apache, etc..)

[wardpeet]

Thank you for the well-written response. I assumed most hosting providers were using those control panels. How do you feel about writing a doc for this were we can start iterating on? Seems like you have some experience.

@gatsbyjs/docs any suggestions?

[bonedaddy]

Well I suppose I might be an outlier but my company isn't using a hosting provider and do everything on-premise.

Absolutely! I would be more than happy to help with this :D I can draft up a rough guide and indicate the parts that are "confusing". Is there a particular place you want me to submit it, I'm guessing the docs repo?

I'll have a draft done within the next 3-5 days.

[marcysutton]

I'd like to see an outline of what a doc like this would cover, so we can iterate on it before you've sunk a bunch of time into writing out details (in case it changes based on feedback). It's valuable information, and I want to make sure it fits with the rest of the Gatsby docs which are for a variety of skill levels. We aim to document what's unique or essential to Gatsby development, and to do this we tend to link out to other resources so we aren't having to cover the entire internet.

Here are some resources for writing docs reference guides, as well: https://www.gatsbyjs.org/contributing/docs-templates/#reference-guides

And the Gatsby Style Guide: https://www.gatsbyjs.org/contributing/gatsby-style-guide/

[bonedaddy]

@marcysutton that is understandable, and actually a much better way of going about doing this. I'm currently on a small vacation and heading back home within a day. I'll draft up an outline on my flight home.

For some initial feedback I'm thinking of breaking up the guide into two sections, which have very different implications for how to set them up:

1) Standard direct connection to nginx
2) Connection to nginx that goes through a loadbalancer, such as HAProxy.

The main issue that I'm having is when the nginx server is sitting behind a load-balancer. That appears to cause some issues when you're trying to go to a page like https://foo.bar/baz instead of going to https://foo.bar and then clicking a link or a menu item that takes you to https://foo.bar/baz.

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[gatsbot[bot]]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community!

[whyboris]

I wonder if it's worth reiterating on the Deploying and Hosting page for those not very familiar with web technologies that simply copying the public folder to your webhost may be enough to get everything working.

Users may try opening the index.html in their public folder on their browser on their computer only to find that nothing renders. That may make them erroneously conclude "I need some special webhost for this 😢 ",

This second point may also be worth mentioning on the _Deploying and Hosting_ page 😅

[edhil]

Agree with that. There is a section about configuring IIS, including proper caching / TTL config, so the same information for nginx and apache should also be present on the same Deploying and Hosting page.