GatsbyJS is a javascript framework based on React that makes it easy to create static websites and dynamic apps.

Since it uses React as a base content can be structured and worked on independently as componants.

I.e you can work on just the header for a page and link it throughout your site.

GatsbyJS also includes a lot of tooling and plugins to pull data from other sources and use other features. Things like implementing SEO, adding Google analytics, adding support for typescript and many many more useful things are available as plugins.

One very handy plugin is the gatsby-plugin-s3 which allows you to deploy a gatsby site to an S3 bucket.

Gatsby Page

https://www.gatsbyjs.org/packages/gatsby-plugin-s3/?=S3#features

Github

GitHub - gatsby-uc/gatsby-plugin-s3: Deploy your gatsby site to a S3 bucket.

Enables you to deploy your gatsby site to a S3 bucket.
Requires very little configuration, while optimizing your site as much as possible.

Features:

📦 Fully handles the deployment process for you, all you need to configure is your bucket name.
- Automatically creates/updates bucket with optimal configuration applied.
- Syncs gatsby files to the bucket & updates metadata.
⏭ Redirects.
💾 Optimizes caching for you.
☁️ Optional serverless framework support if you want to take things a step further.
✏️ Add your own params to uploaded S3 objects (if you wish).

What this boils down to is that it is a plugin that uses aws-cli to deploy your website to an S3 bucket adding defaults that are basically good ideas.

This can also be used with Swarms S3 interface.

Instructions

Figure out how to make a gatsby site

So step 1 is going to be “Learn enough Gatsby to install and make something you want to share”. Thankfully this step isn’t as daunting as it might seem as the Gatsby documentation is excellent.

https://www.gatsbyjs.org/tutorial/

Going through parts 0 and 1 of the linked tutorial will give you a development environment and an example site that is ready to deploy.

There's a lot more to Gatsby but all we need is a working example here.

Add the Gatsby S3 plugin

With gatsby installed and our starter site deployed we can now add a plugin.

first cd into the directory of your site

tony@tony-NUC8i7HVK:~/gatsby$ cd multipass/
tony@tony-NUC8i7HVK:~/gatsby/multipass$ pwd
/home/tony/gatsby/multipass
tony@tony-NUC8i7HVK:~/gatsby/multipass$

Then we want to install the plugin

tony@tony-NUC8i7HVK:~/gatsby/multipass$ npm i gatsby-plugin-s3

With that installed our next step is to configure the plugin

Configure the plugin

The documentation for the plugin tells you to configure the plug in the gatsby-config.js file.

you will find this in the root directory for your site.

tony@tony-NUC8i7HVK:~/gatsby/multipass$ ll
total 892
drwxrwxr-x    7 tony tony   4096 Jul 27 09:23 ./
drwxrwxr-x    4 tony tony   4096 Jul 26 19:22 ../
drwxrwxr-x    9 tony tony   4096 Jul 27 09:23 .cache/
-rw-rw-r--    1 tony tony    164 Jul 26 19:22 gatsby-browser.js
-rw-rw-r--    1 tony tony   1635 Jul 27 09:23 gatsby-config.js
-rw-rw-r--    1 tony tony    158 Jul 26 19:22 gatsby-node.js
-rw-rw-r--    1 tony tony    180 Jul 26 19:22 gatsby-ssr.js
drwxrwxr-x    8 tony tony   4096 Jul 26 19:23 .git/
-rw-rw-r--    1 tony tony    974 Jul 26 19:22 .gitignore
-rw-rw-r--    1 tony tony    675 Jul 26 19:22 LICENSE
drwxrwxr-x 1351 tony tony  40960 Jul 26 19:36 node_modules/
-rw-rw-r--    1 tony tony   1336 Jul 26 20:13 package.json
-rw-rw-r--    1 tony tony 800489 Jul 26 19:36 package-lock.json
-rw-rw-r--    1 tony tony     45 Jul 26 19:22 .prettierignore
-rw-rw-r--    1 tony tony     46 Jul 26 19:22 .prettierrc
drwxrwxr-x    8 tony tony   4096 Jul 27 09:23 public/
-rw-rw-r--    1 tony tony   5564 Jul 26 19:22 README.md
drwxrwxr-x    5 tony tony   4096 Jul 26 19:22 src/

edit the gatsby-config file and add the details for your bucket, domain and the below options. This can be a little messy be sure not to forget comma’s also its case sensitive.

bucketName = the name of the bucket you want to service content from

customAwsEndpointHostname = your swarm domain that you are serving the bucket from.

{
      resolve: `gatsby-plugin-s3`,
      options: {
        bucketName: "gatsbytest",
        customAwsEndpointHostname: 'tlokko.cloud.caringo.com',
        mergeCachingParams: false,
        generateRoutingRules: false,
        generateRedirectObjectsForPermanentRedirects: false,
        generateIndexPageForRedirect: true,
        generateMatchPathRewrites: true,
        removeNonexistentObjects: true,
        enableS3StaticWebsiteHosting: false,
        parallelLimit: 20,

      },
    },

Swarm doesn’t support some of the options available on S3 so its important for this toolchain to turn them off.

enableS3StaticWebsiteHosting: false,
mergeCachingParams: false,

Another important config item is at the top of the file

module.exports = {
  assetPrefix: `https://tlokko.cloud.caringo.com/gatsbytest/`,
  siteMetadata: {
    title: `Tonys Multipass`,
    description: `Kick off your next, great Gatsby project with this default starter. This barebones starter ships with the main Gatsby configuration files you might need.`,
    author: `@gatsbyjs`,
  },

The assetPrefix tells gatsby to use static links rather than relative links when building the static html+javascript files for your site.

that turns a <a href=/page-1.jsp> to <a href=https://tlokko.cloud.caringo.com/gatsbytest/page-1.jsp>

very important if you have more than a single site page more info on it here.

https://www.gatsbyjs.org/docs/path-prefix/

https://www.gatsbyjs.org/docs/asset-prefix/

Thats all we need to add in this file.

Add the plugin to our deployment step

next we modify the package.json

in the scripts section we’ll add

"deploy": "gatsby-plugin-s3 deploy",

So our full stanza will look like this

"scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop",
    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\"",
    "start": "npm run develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "deploy": "gatsby-plugin-s3 deploy",
    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"
  },

From here we’re just about ready to deploy our site. Next we need to deal with aws-cli and run the upload.

Install and configure Aws-cli

The gatsby plugin uses aws-cli to upload the static files on the profile that you are currently logged in as.

To install aws-cli check the installation steps for your platform from here.

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html

Once its installed you will need to add a token and keypair for the platform that you are running on.

tony@tony-NUC8i7HVK:~/gatsby/multipass$ cd /home/tony/.aws/
tony@tony-NUC8i7HVK:~/.aws$ ll
total 16
drwxrwxr-x  2 tony tony 4096 May  7 09:59 ./
drwxr-xr-x 64 tony tony 4096 Jul 28 16:30 ../
-rw-------  1 tony tony   10 May  7 09:59 config
-rw-------  1 tony tony   97 May  7 09:59 credentials
tony@tony-NUC8i7HVK:~/.aws$

The credentials file will simply contain

[default]
aws_access_key_id = whatever-my-token-is
aws_secret_access_key = whatever-my-access-key-is

Now that aws-cli is setup we can run our build for the site and upload it.

Deployment

In my scenario the domain is

tlokko.cloud.caringo.com

the bucket is

gatsbytest

It is worth bearing in mind that you need to have the domain dns resolvable and by default it will attempt to use https as its assuming an s3 service + production quality setup.

Luckily the dns resolution is managed for me in this case but if it wasn’t a hostfile entry or local would do.

Https on the otherhand is handled via a wildcard cert which npm will not accept. In a production setup you would expect an ssl cert for tlokko.cloud.caringo.com and another for *.tlokko.cloud.caringo.com and perhaps even the bucket. This is just a test though so we can tell npm to ignore ssl.

npm config set strict-ssl false

Once thats done we run the build command to create our site locally. Do this from the toplevel of your site directory.

gatsby build --prefix-paths

This command builds all of the static files that you will need to host on a service via gatsby. It does things like image optimization , link resolution etc. leaving you with a huge set of files

ony@tony-NUC8i7HVK:~/gatsby/multipass/public$ ll
total 2824
drwxrwxr-x 8 tony tony   4096 Jul 27 09:23 ./
drwxrwxr-x 7 tony tony   4096 Jul 27 09:23 ../
drwxrwxr-x 2 tony tony   4096 Jul 27 09:23 404/
-rw-rw-r-- 1 tony tony  11427 Jul 27 09:23 404.html
-rw-rw-r-- 1 tony tony  95225 Jul 27 09:20 app-010e799643cf6b759eee.js
-rw-rw-r-- 1 tony tony 369943 Jul 27 09:20 app-010e799643cf6b759eee.js.map
-rw-rw-r-- 1 tony tony  94757 Jul 27 09:19 app-311a2b8bf3b22030afe3.js
-rw-rw-r-- 1 tony tony 369916 Jul 27 09:19 app-311a2b8bf3b22030afe3.js.map
-rw-rw-r-- 1 tony tony  95440 Jul 27 09:16 app-5faf61d4881fb1eef9ae.js
-rw-rw-r-- 1 tony tony 369943 Jul 27 09:16 app-5faf61d4881fb1eef9ae.js.map
-rw-rw-r-- 1 tony tony  94972 Jul 27 09:23 app-6faea61b9e18a80bb5bb.js
-rw-rw-r-- 1 tony tony 369929 Jul 27 09:23 app-6faea61b9e18a80bb5bb.js.map
-rw-rw-r-- 1 tony tony    434 Jul 27 09:23 chunk-map.json
-rw-rw-r-- 1 tony tony  18918 Jul 27 09:23 commons-919ff68c55a2acfb1dd6.js
-rw-rw-r-- 1 tony tony  76972 Jul 27 09:23 commons-919ff68c55a2acfb1dd6.js.map
-rw-rw-r-- 1 tony tony    461 Jul 27 09:23 component---src-pages-404-js-852bd3a5faea7629c57d.js
-rw-rw-r-- 1 tony tony    618 Jul 27 09:23 component---src-pages-404-js-852bd3a5faea7629c57d.js.map
-rw-rw-r-- 1 tony tony  15558 Jul 27 09:20 component---src-pages-index-js-04ab1ab9f24ec3add588.js
-rw-rw-r-- 1 tony tony  54128 Jul 27 09:20 component---src-pages-index-js-04ab1ab9f24ec3add588.js.map
-rw-rw-r-- 1 tony tony  15306 Jul 27 09:16 component---src-pages-index-js-8d072aae352862c26359.js
-rw-rw-r-- 1 tony tony  54128 Jul 27 09:16 component---src-pages-index-js-8d072aae352862c26359.js.map
-rw-rw-r-- 1 tony tony  15607 Jul 27 09:23 component---src-pages-index-js-9de8de8ddb4b340f3438.js
-rw-rw-r-- 1 tony tony  54128 Jul 27 09:23 component---src-pages-index-js-9de8de8ddb4b340f3438.js.map
-rw-rw-r-- 1 tony tony    507 Jul 27 09:23 component---src-pages-page-2-js-ef8c063115e3c48e159a.js
-rw-rw-r-- 1 tony tony    705 Jul 27 09:23 component---src-pages-page-2-js-ef8c063115e3c48e159a.js.map
-rw-rw-r-- 1 tony tony   1389 Jul 27 09:23 component---src-pages-using-typescript-tsx-ccc63956d1d6da3ec2a1.js
-rw-rw-r-- 1 tony tony   1919 Jul 27 09:23 component---src-pages-using-typescript-tsx-ccc63956d1d6da3ec2a1.js.map
-rw-r--r-- 1 tony tony   1504 Jul 27 09:23 favicon-32x32.png
-rw-rw-r-- 1 tony tony 128787 Jul 27 09:23 framework-5fc6169171e885c3b522.js
-rw-rw-r-- 1 tony tony 313207 Jul 27 09:23 framework-5fc6169171e885c3b522.js.map
drwxrwxr-x 2 tony tony   4096 Jul 26 19:23 icons/
-rw-rw-r-- 1 tony tony  14722 Jul 27 09:23 index.html
-rw-rw-r-- 1 tony tony   1035 Jul 27 09:23 manifest.webmanifest
drwxrwxr-x 2 tony tony   4096 Jul 27 09:23 page-2/
drwxrwxr-x 8 tony tony   4096 Jul 26 19:33 page-data/
drwxrwxr-x 4 tony tony   4096 Jul 26 19:23 static/
-rw-rw-r-- 1 tony tony    117 Jul 27 09:23 styles-c2fe8482057191dca484.js
-rw-rw-r-- 1 tony tony    107 Jul 27 09:23 styles-c2fe8482057191dca484.js.map
-rw-rw-r-- 1 tony tony   5402 Jul 27 09:23 styles.d5ef0abb16ee382cea7f.css
drwxrwxr-x 2 tony tony   4096 Jul 27 09:23 using-typescript/
-rw-rw-r-- 1 tony tony   3844 Jul 27 09:20 webpack-runtime-03be5921d4ed50976860.js
-rw-rw-r-- 1 tony tony  16893 Jul 27 09:20 webpack-runtime-03be5921d4ed50976860.js.map
-rw-rw-r-- 1 tony tony   3887 Jul 27 09:16 webpack-runtime-3b7076d2e8f366cd8c1c.js
-rw-rw-r-- 1 tony tony  16936 Jul 27 09:16 webpack-runtime-3b7076d2e8f366cd8c1c.js.map
-rw-rw-r-- 1 tony tony   3808 Jul 27 09:12 webpack-runtime-41e24e9b74e50f4eff27.js
-rw-rw-r-- 1 tony tony  16856 Jul 27 09:12 webpack-runtime-41e24e9b74e50f4eff27.js.map
-rw-rw-r-- 1 tony tony   3808 Jul 27 09:19 webpack-runtime-759c738e212e72a7212b.js
-rw-rw-r-- 1 tony tony  16856 Jul 27 09:19 webpack-runtime-759c738e212e72a7212b.js.map
-rw-rw-r-- 1 tony tony   3851 Jul 27 09:23 webpack-runtime-bd8e13a605a5974d00bc.js
-rw-rw-r-- 1 tony tony  16900 Jul 27 09:23 webpack-runtime-bd8e13a605a5974d00bc.js.map
-rw-rw-r-- 1 tony tony   2860 Jul 27 09:23 webpack.stats.json
tony@tony-NUC8i7HVK:~/gatsby/multipass/public$

note the above is a two page starter site.

once thats done re can run the deploy step

tony@tony-NUC8i7HVK:~/gatsby/multipass$ npm -y run deploy

> gatsby-starter-default@0.1.0 deploy /home/tony/gatsby/multipass
> gatsby-plugin-s3 deploy


    Please review the following: (pass -y next time to skip this)

    Deploying to bucket: gatsbytest
    In region: <LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">gem.tx.caringo.com
    Gatsby will: UPDATE (any existing website configuration will be overwritten!)

? OK? (Y/n) 
? OK? Yes
✔ Synced.

            Your website has now been published to:
            gatsbytest

If it all worked you’ll see a message like the above which tells you your files have been uploaded and all is good.

From there you should be able to access the file via its index.html page.

In my case thats https://tlokko.cloud.caringo.com/gatsbytest/index.html

index.html

If you want to have the content public change your access policy on the bucket to allow anonymous GET

Knowledge Base

Getting started with GatsbyJS and Swarm