Example: Deplying a Static Site to AWS S3

This example shows how to deploy a static site to Amazon Web Services (AWS) Simple Storage Service (S3) with CloudFront CDN distribution around the world, costing mere pennies a month. Guise Mummy transparently sets up SSL/TLS support on a custom domain, with automatic upgrade from non-secure connections. Both subdomains such as www.example.com and bare domains such as example.com are supported, and Guise Mummy can configure redirects to the canonical one.

This example requires that you own a domain name and can set its DNS servers through the registrar's control panel.

Install

You will use the Guise Mummy Command Line Interface (CLI) to generate static sites. To use the CLI, you must first install Java and then the CLI itself.

Download install Java from the AdoptOpenJDK project. You must use Java 11 or later.
Download and install the Guise CLI.

For more details read the in-depth installation instructions for Guise CLI.

Home Page

Although it is possible to use any directory structure, it's easiest to use the Guise standard directory layout, which requires no custom configuration.

Create a project directory my-site.
Create the home page at my-site/src/site/index.md using Markdown.
Inside my-site run the command guise mummify.
Your new home page will appear in my-site/target/site/index.html. You can now upload the entire my-site/target/site/ directory to your server, but there are even better ways to deploy your site, explained below.

my-site/src/site/index.md

---
title: My Site Home Page
---
# My Site

Welcome to my site.

$ cd my-site
$ guise mummify
   _____       _
  / ____|     (_)
 | |  __ _   _ _ ___  ___
 | | |_ | | | | / __|/ _ \
 | |__| | |_| | \__ \  __/
  \_____|\__,_|_|___/\___|


Guise CLI x.x.x

Mummify...
[INFO] Project directory: …/my-site
[INFO] Site source directory: …/my-site/src/site
[INFO] Site target directory: …/my-site/target/site
[INFO] Site description target directory: …/my-site/target/site-description

my-site/target/site/index.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>My Site Home Page</title>
  <meta name="generator" content="Guise Mummy x.x.x" />
  <meta name="generated-at" content="2020-01-03T16:23:12.640413200Z" />
</head>
<body>
  <h1>My Site</h1>
  <p>Welcome to my site.</p>
</body>
</html>

Test Using Local Server

Guise comes with a built-in server for testing your site locally. Use the guise serve command to start a server at localhost on port 4040 by default. Add the --browse flag and Guise will automatically open the page in your browser.

$ guise serve
   _____       _
  / ____|     (_)
 | |  __ _   _ _ ___  ___
 | | |_ | | | | / __|/ _ \
 | |__| | |_| | \__ \  __/
  \_____|\__,_|_|___/\___|


Guise CLI x.x.x

Serve...
[INFO] Project directory: …/my-site
[INFO] Site source directory: …/my-site/src/site
[INFO] Site target directory: …/my-site/target/site
[INFO] Site description target directory: …/my-site/target/site-description
[INFO] Server base directory: C:\Users\user\AppData\Local\Temp\guise\mummy\server
[INFO] Server port: 4040
[INFO] Initializing ProtocolHandler ["http-nio-4040"]
[INFO] Starting service [Tomcat]
[INFO] Starting Servlet engine: [Apache Tomcat/9.0.30]
[WARN] Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [510] milliseconds.
[INFO] Starting ProtocolHandler ["http-nio-4040"]
[INFO] Serving site at <http://localhost:4040/>. (Press Ctrl+C to stop.)

Add a Project Description File

Adding a project description file allows you to customize and add new capabilities to the build and process. The project description file is named guise-project.turf and lives in the root directory of your site. It uses a new file format, TURF, which is similar to JSON but more powerful.

my-site/guise-project.turf

*GuiseProject:
  domain = "example.com."
  site:
    domain = "www"
    altDomains = ("")
  ;
;

"example.com." specifies the base domain that you own or manage. Don't forget the dot at the end!
"www" indicates the relative subdomain where your site will be deployed, that is www.example.com.
"" indicates the relative subdomain that is an alternate access to your site, in this case example.com itself. Depending on where the site is deployed, browsing to http://example.com would redirect to http://www.example.com.

Deploy to AWS with Custom Domain and SSL/TLS

Guise Mummy initially supports automated deployment to an AWS S3 bucket, and replicated around the world using the CloudFront (CDN) using a secure SSL/TLS (HTTPS) connection and the Route 53 DNS. Future versions of Guise will support additional deployment targets.

Create an AWS account if you don't already have one.
- Create an IAM user and store its credentials in the ~/.aws/credentials file (that is, .aws/credentials inside your user directory).
Update your guise-project.turf file:
```
*GuiseProject:
  domain = "example.com."
  site:
    domain = "www"
    altDomains = ("")
  ;
  deploy:
    dns = *Route53
    targets = [
      *S3Website:
        region = "us-east-1"
      ;
      *CloudFront
    ]
  ;
;
```
- *Route53 indicates you'll be using Route 53 for your DNS.
- *S3Website tells Guise Mummy to deploy your site to an S3 bucket but allow it to be accessed as a web site. You may change "us-east-1" to the AWS Region of your choice for your S3 bucket. Guise Mummy will actually create two buckets with the above configuration, one of which, example.com, will serve only as an alternative, redirecting to the canonical domain.
- *CloudFront instructs Guise Mummy to set up a CloudFront distribution for your site, with SSL/TLS support using the AWS Certificate Manager.

Deploy your site using the guise deploy command.

$ guise deploy
   _____       _
  / ____|     (_)
 | |  __ _   _ _ ___  ___
 | | |_ | | | | / __|/ _ \
 | |__| | |_| | \__ \  __/
  \_____|\__,_|_|___/\___|


Guise CLI x.x.x

Deploy...
[INFO] Project directory: …/my-site
[INFO] Site source directory: …/my-site/src/site
[INFO] Site target directory: …/my-site/target/site
[INFO] Site description target directory: …/my-site/target/site-description
[INFO] Creating Route 53 public hosted zone for name `example.com.`.
[INFO] Name server: ns-xxx.awsdns-xx.com.
[INFO] Name server: ns-xxxx.awsdns-xx.org.
[INFO] Name server: ns-xxx.awsdns-xx.net.
[INFO] Name server: ns-xxxx.awsdns-xx.co.uk.
[INFO] Preparing AWS S3 bucket `www.example.com` in region `us-east-1` for deployment.
[INFO] Setting policy of S3 bucket `www.example.com` to public.
[INFO] Preparing AWS S3 bucket `example.com` in region `us-east-1` to serve as an alternative.
[INFO] Requesting certificate for domain name `example.com` and alternative names `[www.example.com]`.
[INFO] Waiting for requested certificate `…` to be recognized...
[INFO] Setting DNS entry [CNAME] `….www.example.com.` = `…` for certificate `…` validation for domain name `www.example.com`.
[INFO] Setting DNS entry [CNAME] `….example.com.` = `…` for certificate `…` validation for domain name `example.com`.
[ERROR] Certificate `…` is still pending validation for domain names [www.example.com, example.com]. …

The first time you deploy your site, the deployment will fail because AWS cannot validate the SSL/TLS certificate until you have switched your domain to use the new Route 53 DNS addresses.

In your registrar's configuration for example.com, change the name servers to those Guise Mummy indicated during initial setup: ns-xxx.awsdns-xx.com, ns-xxxx.awsdns-xx.org, ns-xxx.awsdns-xx.net, ns-xxxx.awsdns-xx.co.uk (yours will differ from those highlighted above). Your registrar will likely require you not to enter the ending dot for each DNS address.
Wait for the AWS Certificate Manager to recognize the DNS changes and issue the certificate(s). Normally this takes just a few minutes, depending on how soon your registrar actually makes the changes visible. You can check to see if the certificate(s) have an Issued status by using the AWS Certificate Manager console. Regardless of the region you specified for your S3 bucket(s), Guise Mummy creates your certificates in the US East (N. Virginia) region as AWS requires for CloudFront, so make sure you select that region in the CloudFront console or your certificate(s) will not appear.

Deploy your site again using the guise deploy command.

$ guise deploy
   _____       _
  / ____|     (_)
 | |  __ _   _ _ ___  ___
 | | |_ | | | | / __|/ _ \
 | |__| | |_| | \__ \  __/
  \_____|\__,_|_|___/\___|


Guise CLI x.x.x

Deploy...
[INFO] Project directory: …/my-site
[INFO] Site source directory: …/my-site/src/site
[INFO] Site target directory: …/my-site/target/site
[INFO] Site description target directory: …/my-site/target/site-description
[INFO] Creating Route 53 public hosted zone for name `example.com.`.
[INFO] Name server: ns-xxx.awsdns-xx.com.
[INFO] Name server: ns-xxxx.awsdns-xx.org.
[INFO] Name server: ns-xxx.awsdns-xx.net.
[INFO] Name server: ns-xxxx.awsdns-xx.co.uk.
[INFO] Preparing AWS S3 bucket `www.example.com` in region `us-east-1` for deployment.
[INFO] Setting policy of S3 bucket `www.example.com` to public.
[INFO] Preparing AWS S3 bucket `example.com` in region `us-east-1` to serve as an alternative.
[INFO] Deploying to AWS region `us-east-1` S3 bucket `www.example.com`.
[INFO] Deploying artifact to S3 key `index.html`.
[INFO] Configuring S3 bucket `www.example.com` for web site access.
[INFO] Configuring S3 alternative bucket `example.com` for web site redirection.
[INFO] (S3Website) Successfully deployed site to <http://www.example.com.s3-website-us-east-1.amazonaws.com/>.
[INFO] Creating distribution for S3 bucket `www.example.com`.
[INFO] Setting DNS alias [A] record for domain name `www.example.com.` to CloudFront distribution ….
[INFO] Creating distribution for S3 bucket `example.com`.
[INFO] Setting DNS alias [A] record for domain name `example.com` to CloudFront distribution ….
[INFO] (CloudFront) Successfully deployed site to <https://www.example.com/>.

Wait for the CloudFront distribution(s) to be deployed. Normally this will take place within an hour. You can check to see if the distribution(s) have a Deployed status by using the AWS CloudFront console.
Your site is now deployed and accessible at https://www.example.com/, with an alternate location of https://example.com/ that redirects to the canonical address. Moreover your SSL/TLS certificate(s) will be renewed automatically. Even after initial deployment, it may take a while for the DNS changes to propagate to your area.

You can redeploy the site at any time using guise deploy, and Guise Mummy will update the AWS S3 bucket with the new content without needing to request new S3 buckets, SSL/TLS certificates, or CloudFront distributions. Even after redeploying your site, keep in mind that CloudFront caches the old content for up to a day, so the changes may not be immediately visible to the world.