diff --git a/docs/docs/deploying-to-digitalocean-droplet.md b/docs/docs/deploying-to-digitalocean-droplet.md new file mode 100644 index 0000000000000..ac599c79f6f10 --- /dev/null +++ b/docs/docs/deploying-to-digitalocean-droplet.md @@ -0,0 +1,255 @@ +--- +title: Deploying to a DigitalOcean Droplet +--- + +This guide walks through how to deploy and host your Gatsby site on a [DigitalOcean Droplet](https://www.digitalocean.com/products/droplets/) with Ubuntu and Nginx. + +DigitalOcean provides a cloud platform to deploy, manage, and scale applications of any size, removing infrastructure friction and providing predictability so developers and their teams can spend more time building better software. + +DigitalOcean's product droplets are scalable compute IaaS (Infrastructure as a Service) or a VPS (Virtual Private Server) on the cloud which has great reliability and scalability. They come with varied price ranges ideal for small apps to giant enterprise-level apps. + +They provide service to select from various Unix-based distributions and select your technology-based platform with preinstalled pre-requisites from the marketplace. This guide will walk through the specific options that work best for deploying a Gatsby site with DigitalOcean. + +A Droplet can be spun up in less than a minute for as little as \$5/month. + +## Prerequisites + +- A Gatsby site living in a Git repository (GitHub, GitLab, or any Git cloud) +- A [DigitalOcean Droplet](https://www.digitalocean.com/products/droplets/) with a non-root user configured with sudo group ([example: Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-18-04-quickstart)) +- A custom domain name for your Gatsby site to help with configuring HTTPS + +## How to deploy your Gatsby site to DigitalOcean + +### Install NodeJS, NPM and Gatsby-CLI onto your droplet + +Follow these instructions for installs on an Ubuntu droplet. + +1. Log in to your droplet as a non-root user. + +2. Install NodeJS + + ```bash + sudo apt-get update + sudo apt-get install nodejs + ``` + +3. Install npm + + ```bash + sudo apt-get install npm + ``` + + To view the version of Node and npm installed, run, + + ```bash + node -v + npm -v + ``` + +4. To install the latest stable Node.js release using the `n` package (Required), + + ```bash + sudo npm install -g n + sudo n stable + ``` + + `Note`: If you check the version now, you would see the older versions of node and npm from the cache. + You can either exit and restart your terminal or refresh the cache by following commands, + + ```bash + hash node + hash npm + ``` + +5. Install the gatsby-cli now globally. This will be useful ahead in building the Gatsby site for production. + + ```bash + sudo npm install -g gatsby-cli + ``` + +### Clone your repository to the droplet + +The next step is to clone the repository containing your Gatsby app (Replace `` with your Github repository link) + +```bash +git clone +``` + +> Note: Copy the path where your `` is cloned, for future reference. + +```bash +pwd +``` + +In case of a warning related to "Permission denied", check if `` has `sudo` privileges. Or before cloning your repository, [change permissions](https://help.ubuntu.com/community/FilePermissions) for `` to access the `.config` directory of under `/home//`: + +```bash +cd ~/ +sudo chown -R $(whoami) .config +``` + +> Note: This guide will refer to the cloned directory as `` for simplicity; you should replace it with your repo directory name. + +### Generate your Gatsby site for production + +The static files will be hosted publicly on the droplet. The `gatsby build` command provides utility to build the site and generate the static files in the `/public`. + +> Note: Go to the path where is. You can used the copied path for reference in a [previous step](#clone-your-repository-to-the-droplet). + +1. Install dependencies. + +```bash +cd +sudo npm install +``` + +2. Run build to generate static files. + +```bash +sudo gatsby build +``` + +### Install Nginx Web Server to host the site and open firewall to accept HTTP and HTTPS requests + +To host a website or static files onto a Linux-based server/VPS, a web-server like Apache or Nginx is required. + +Nginx is web-server. It provides the infrastructure code for handling client requests from the World Wide Web, along with features like a load balancer, mail proxy, and HTTP Cache. + +1. Install Nginx. + + ```bash + sudo apt-get install nginx + ``` + +2. Configure firewall settings of the droplet to listen to HTTP and HTTPS requests on port 80 and 443 respectively. + + ```bash + sudo ufw allow 'Nginx HTTP' + sudo ufw allow 'Nginx HTTPS' + ``` + +3. To check the access, + + ```bash + sudo ufw app list + ``` + +4. If `ufw` status is disabled/inactive, you can enable it with the following command: + + ```bash + sudo ufw enable + ``` + + Allow the OpenSSH if not already done, to not disconnect from your droplet. + + ```bash + sudo ufw allow 'OpenSSH' + ``` + +### Configure Nginx to point to your Gatsby site's `/public` directory and add your domain + +Change the root directory configuration of Nginx in the default server block file + +1. Go to `/etc/nginx/sites-available/` + + ```bash + cd /etc/nginx/sites-available/ + ``` + +2. Open the file default in Vim ([shortcut cheat sheet](https://devhints.io/vim)) + + ```bash + sudo vim default + ``` + +3. Edit the file and make the following changes for below-mentioned fields, leave the rest of the fields as is. Your exact path may vary, but it may resemble `/home///public`. + + ```bash + server { + root /public; + + index index.html index.htm index.nginx-debian.html; + + server_name ; + + location / { + try_files $uri $uri/ =404; + } + } + ``` + +4. Restart the Nginx service + + ```bash + sudo systemctl restart nginx + ``` + + You should now be able to view your built Gatsby site at your DigitalOcean IP address, before configuring a domain. + +5. Configure your domain to point to the IP address of your droplet. Go to the Advanced DNS settings in your domain provider's console and put an A record that points to the IP address of the droplet. + +6. By this time, you can view your site live at ``. + +### Configuring HTTPS for your Gatsby Site + +Follow the below steps to configure your site with a free SSL/TLS certificate from Lets Encrypt using their Certbot CLI tool. + +1. Install Certbot onto your droplet. + + You'll need to add the Certbot PPA (Personal Package Archives) to your list of repositories. To do so, run the following commands: + + ```bash + sudo apt-get update + sudo add-apt-repository ppa:certbot/certbot + sudo apt-get update + ``` + + Run the following commands to install Certbot. + + ```bash + sudo apt-get install certbot python3-certbot-nginx + ``` + +2. Generate the certificate. Certbot will automatically edit and configure the Nginx config file and point to the certificate file. + + Run the following command: + + ```bash + sudo certbot --nginx + ``` + +3. If you are using Certbot for the first time on this droplet then you will be prompted to enter your e-mail for recovery purposes. + +4. Agree to the license agreement on prompt. + + `Note`: You will be prompted to select the domain for which you want to generate the certificate. Select the domain configured in a [previous step](#configuring-nginx-to-point-to-your-gatsby-site's-`public`-directory-and-add-your-domain). + + `Note`: You will be prompted to choose the option to redirect HTTP requests to HTTPS, which you may choose on your needs. + (It is recommended to choose to redirect HTTP to HTTPS) + +5. Restart the nginx service. + + ```bash + sudo systemctl restart nginx + ``` + +6. Now, you can access your site at `` with a secure connection. + +### View your Gatsby site live + +Once you've followed along with all the steps and configuration properly, you can visit your site live at ``. + +Whenever there's an update to your site, run a `sudo gatsby build` in the root of your `` and your changes will be live. + +Congratulations! You've deployed your Gatsby App on a DigitalOcean droplet along with configuring HTTPS for it. + +## Additional resources + +There's a lot more to learn about DigitalOcean's Droplets, Ubuntu configurations, and Nginx. Below are some links which could be useful in achieving the prerequisites of this post: + +- [Microblog - Create a new non-root user with sudo privileges on Ubuntu-based DigitalOcean Droplet configured with SSH](https://dev.to/mistryvatsal/microblog-create-a-new-non-root-user-with-sudo-privileges-on-ubuntu-based-digitalocean-droplet-configured-with-ssh-1l3) +- [Official DigitalOcean Docs](https://www.digitalocean.com/docs/) +- [Official Nginx Docs](http://nginx.org/en/docs/) +- [Configuring HTTPS Servers with Nginx](http://nginx.org/en/docs/http/configuring_https_servers.html) +- [How To Install Nginx on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04) +- [How To Secure Nginx with Let's Encrypt on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04) diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 6c2b1ffb7c281..77234f97d9772 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -74,6 +74,9 @@ - title: Deploying to AWS Amplify link: /docs/deploying-to-aws-amplify/ breadcrumbTitle: AWS Amplify + - title: Deploying to a DigitalOcean Droplet + link: /docs/deploying-to-digitalocean-droplet/ + breadcrumbTitle: DigitalOcean - title: Deploying to S3 & CloudFront link: /docs/deploying-to-s3-cloudfront/ breadcrumbTitle: S3 & CloudFront