Why does structure prediction matter?

Structure prediction is a 2nd order thing to drug-discovery programs, where people really care about:

1.⁠ ⁠Finding therapeutic targets to go after, 2.⁠ ⁠⁠finding hit molecules for those targets, and 3.⁠ ⁠⁠optimizing those hit molecules.

In the discovery context, structure prediction is a foundation, a “means to an end”, not the goal itself – that’s markedly different from a tech crowd, where perhaps “making the number go higher” (benchmarks) is seen as sufficient.

How does structure prediction impact lead optimization? Well, for one thing, better co-folding models equals better starting structures for FEP simulations. As these models improve geometry and chemistry awareness, they’ll reduce the setup time and expert touch currently required for FEP workflows.

Comparisons are tricky

The public structure prediction benchmarks often focus on aspects of the predicted pose, like ligand RMSD to crystal structure. Geometric problems are often incompletely captured but that’s changing: people are looking at non-physical protein/ligand/water contacts and geometries.

While many SAAS products (Nvidia NIM, Tamarind.bio, Deepmirror, Rowan) will allow you to run these models, almost none of them really allow you to benchmark (Apheris is a notable exception). Simple inference is the level of “kicking the tires”, barely above Hugging Face examples, and hard to imagine how that fits into a discovery workflow.

Who’s who 2025

Favorites for 2026

Closed-source: Pearl

Probably the best closed-source model for small molecules at the moment, released earlier this week. Another giggle: the company renamed from “Genesis Therapeutics” to “Genesis Molecular AI”… I see what you did here! With the (dire) state of the biotech investment, everyone seems to be cuddling closer and closer to “AI”, where investment dollar flows happily.

Excited to share Pearl from Genesis Molecular AI (yes, we've updated our name!): the first co-folding model to clearly surpass AlphaFold 3 on protein-ligand structure prediction.

Unlike LLMs that train on vast public data, drug discovery AI faces fundamental data scarcity. Our… pic.twitter.com/Jmc2FQ65mA

— Genesis Molecular AI (@genesistxai) October 28, 2025

As an ex-competitor of theirs, this is certainly interesting to me: Charm Therapeutics also focused on small molecules. CharmTx DragonFold model was able to match AF3 but not meaningfully exceeded it. The Genesis crew significantly outperforms AF3 on small-molecule structure prediction.

The code and model remains closed-source, even to academics/non-commercial users. The technical report which accompanied the release is sparse on the details but if you’ve worked in this field, the subtle nudges within are pretty clear: some mixture of architecture changes, and synthetic data generation.

The team is suitably cross discipline and appears well funded. Such teams will continue to outperform pure tech plays – in my view – because pure tech will often tap-out in the data curation angle, or success metric definition: the ability to curate data with help of crystallographers, affinity data with biology and chemistry teams, ability to generate synthetic data with computational chemists. “Make number go higher” only works if you have a clue how to define the number, and your science colleagues do.

Open-source: OF3

I personally share the enthusiasm of the post below :D

🔥 It's here: OpenFold3 is now live.

THE open-source foundation model for predicting 3D structures of proteins, nucleic acids & small molecules. This is where the future of drug discovery and biomolecular AI lives.

Built by @open_fold. Hosted on @huggingface.
👇 more pic.twitter.com/IukdhBL8rD

— Georgia Channing (@cgeorgiaw) October 28, 2025

OF3 certainly looks to be more “opener” than “open-weights” competitors. To be fully and meaningfully open, the models should disclose their training code and data. Weights and inference code just allows the model to be run “as is”.

What’s important for OF3, and more broadly the open-model community, is to move beyond AF3 and into the future. The OF3 crew has the (massive) benefit of multiple talents in the house (tech + science, academia + industry) – bringing those together will be the key to success.

Challenges and ideas

Generalization

The problem Performance drops sharply on targets not seen in training. Models interpolate well but struggle to extrapolate.

Why it matters Biologics – where the hypervariable Ab regions by definition don’t have many “similar” sequences in the training dataset. Small molecules – targets with limited structural data.

What could work

• better architectures to increase what the model can squeeze out of the same data,
• federated learning to provide proprietary data,
• better measuring sticks, Runs’N’Poses (RnP) is a great start.

Validation beyond benchmarks

The problem The public structure prediction benchmarks are a “minimum bar” to pass. Most of the AF3 clones have not been tested in discovery.

Why it matters The benchmarks don’t fully capture the expectations of a medicinal chemist, trust is lost when used prospectively and artifacts are observed.

What could work

• Better benchmarks, with more medicinal chemistry focus
• Back-testing on industry data (preferably data not seen in training).
• Blind prospective validation – but that takes time and money.

Protein dynamics (including disorder)

Protein dynamics and protein disorder comes in many different flavors: from fully disordered proteins, to those that fold upon contact with others “partially disordered”. On the more humble end, you could think as allostery as the minimal case of protein disorder albeit that’s a bit unorthodox.

The problem Current generation of models are great “structure predictors” and don’t appear to have a great understanding of protein physics/dynamics, folding mechanism or kinetics/thermodynamics is out of reach.

Why it matters Many drug targets are partially disordered or undergo conformational changes upon binding. Single static structures miss the ensemble.

What could work

• Training on experimental stability/flexibility data (HDX-MS, radical reactivity)
• Synthetic MD trajectories, e.g., AF CALVADOS

Data scarcity and quality

The problem Unlike LLMs trained on the entire internet, structure models are data-starved. Self-distillation risks “exhaust gas recirculation”—training on your own mediocre predictions degrades quality.

Why it matters: More data = better performance, but only if the data is high-quality. Garbage in, garbage out.

What could work

• Synthetic data generation, with careful curation
  • Molecular dynamics (Boltz-2)
  • From affinity datasets with closely-linked structural data (Genesis?)
• Experimental data generation for structure and affinity (OpenBind consortium)
• Fine-tuning on proprietary data (works better than RAG for these models)

Scaling laws

The problem We haven’t seen clear scaling laws emerge yet, where same architecture can be scaled up to a larger model and unlock new capabilities.

Why it matters Scaling laws drive investment, without them only data/architecture breakthrough are needed.

What we’re learning Genesis hints at scaling with synthetic data. More investigation needed.

Chemistry awareness

The problem Models still generate non-physical geometries – protein and ligand impacted – bad bond angles, steric clashes, impossible ring conformations.

Why it matters Medicinal chemists won’t trust poses that violate basic chemistry. “This nitrogen can’t be sp3 in this fragment” = loss of trust in the tech.

What could work

• Improve the handling of chemistry features: bond orders, protonation, chirality, ring puckering, non-physical intra-molecular contacts,
• Physics-based geometry constraints during training/inference,
• Water co-folding Many discovery programs hinge on explicit water interactions—currently missing from all models.

Affinity prediction

The problem Current affinity models appear to overfit training distributions. Performance drops on novel scaffolds or targets not in training data.

Why it matters In lead optimization, accurate ΔΔG (relative binding affinity) prediction can save money spent on synthesis and experimental validation.

What could work:

• Split the affinity problem into two: (1) binder/non-binder separation between different series, and (2) accurate affinity prediction within a series,
• Synthetic data: pair known affinity datasets with predicted/AlphaFilled structures

Training complexity

The problem Multi-stage training regimes make reproduction difficult. These models aren’t as big as LLMs (64 A100s suffices) but the “fiddly” training process creates replication barriers.

Why it matters Complex training = fewer groups can validate/extend the work, because they have to “guess” the training stage parameters.

Architecture frontiers

The problem Hard to predict what architecture changes will matter. Attention mechanisms have memory limitations for all-atom polymer representations.

Why it matters Current generation of models could be permanently limited because of the loss of all-atom representation, needed to save memory.

What could work

• Pearl hint at the return of SO(3)-equivariant architecture (present in AF2 but removed in AF3)
• Improved coarse-graining: 2-3 tokens per residue instead of 1 (captures more geometry without full all-atom overhead)
• Hybrid approaches: coarse for bulk structure, all-atom for binding site (already the case for PTM residues, which are all-atom)

Why do inverse folding methods hate bulky aromatics so much? From the BoltzGen paper pic.twitter.com/BhDcOHuk42

— Diego del Alamo (@DdelAlamo) October 27, 2025

Conclusion and predictions for 2026

This field is currently pretty buzzing or at the very least showing “healthy signs of activity”. These models are here to stay, and are quickly becoming the bread-and-butter of discovery. We understand much better where they work and why. However, there are quite of few of them and the differences are to express (commodification at least at the surface level).

Maybe we’ll cure all diseases in 10 years – that’d be really awesome – but we probably won’t. We need more AF3-like moments for different parts of the drug discovery process.

Prediction is hard, I was certainly wrong about two major things last year

• I was skeptical of federated learning, yet that strategy seems to be doing pretty well (eg Apheris, OpenFold)
• I was skeptical of synthetic data via but that too seems to have done well (Genesis and Boltz have reported on this, albeit have taken different strategies)

For 2026, I think we’ll see multiple models go beyond AF3, both in terms of capabilities and raw structure prediction performance. People are definitely trying to address the data limitations, both via synthetic data generation and experimentally via initiatives like OpenBind. Targets with little structural data will remain challenging, unless new break-through architectures emerge.

Scientists, talk to your tech buddies – tech people talk to your science mates. None of you can do it alone, only together can you complete the puzzle.

Acknowledgements

Many thanks to Peter Mernyei & Jenke Scheen for their feedback on this post.

Update (2025-10):
This post didn’t age that well!

Recently I was approached by an old co-worker and good colleague to consider re-joining a place we used to work together. I pretty much declined and probably offended him a bit (sorry!) but it really got me thinking about which opportunities I’d like to take vs pass on.

Maybe this view comes from a personal bias. Surviving cancer definitely sharpens the focus. There is more time for family and friends, and more time for meaningful work, but less time for money for the sake of money. Can’t take status to the grave with you!

Here are a few dimensions to consider, when joining, or re-joining a company:

• What’s the purpose of the company? is it about solving a burning problem, or an insurmountable challenge (good), or is it about the greatness/legacy of the owner, or a advancing a particular favored method/technique (bad), is there any clarity at all? is any of this backed by measurable actions (very important)

• What happens to the people who leave the place? Do they become more or less successful? Do super-stars ever return? Actions speak louder than words, people may simply be polite and avoiding speaking their mind… choosing to instead speak with their exit. Can you reach leavers an LinkedIn and get them on the phone to get the “real” exit interview?

• What’s the money like? This one is kind of U-shaped: on one end you have grift-startups with charismatic founders, on the other places with no soul that pay top-$$$. For the grifting startups, they’re unable to really raise enough money, so they descend into sweat-shop mode – paying the staff the bare minimum and going the cult path. On the other hand, you have ultra-high paying places that solve problems by just paying you more to shut up. Some people need the money, because circumstances and reasons. In the middle, you should get places that are the best: they pay a lot but not insane. Discount startup stock completely: you’re already 100% exposed and it’ll be years before you see stock option profit, if at all, and you can always get more of it later down the road.

• What’s the competition like? This one is U-shaped again. Too much competition is clearly bad, but no competition at all may mean that it’s too soon, or simply a hermit-like organization.

And the most important one of all

• What’s the progress for the money and time spent? What’s the bang for your buck? Given an estimate spend of an organization, and they years they’ve been around, what have they actually accomplished? Was it something truly relevant to their claimed mission, or an improvement (however ingenious) on the periphery? Under-performing on this dimension is an indicator of real problems, especially when backed by enormous resources: things are probably too screwed up internally to make any real progress. Could be leadership, could be team, could be everything. Typically this is not a failure mode available to startups, unless they go zombie mode.

This is probably not exhaustive but it feels good enough!

It’s as simple linear set of equations, and you’ve just been nerd-sniped so good luck solving it!

While simple, the problem inspired me to write a tiny Python solver – it’s brute force and assumes each of the variables is an int bound between 0..10

def solver():
    for c in range(11):
        for r in range(11):
            for t in range(11):
                for w in range(11):
                    check1 = c + r + t == 4*w
                    check2 = c + r == t
                    check3 = c + t == 8 + r
                    check4 = t == 3*r

                    if check1 and check2 and check3 and check4:
                        print(dict(c=c, r=r, t=t, w=w))
                        print(c + (r * t) - w)

if __name__ == "__main__":
    solver()

Every year we repeat the idiotic ritual of switching our clocks back by one hour. While sleeping one hour longer is a genuinely pleasant prospect, the change is disruptive to your circadian clock. Yeah, the mornings are brighter but you’ll end up leaving your office at 5pm in complete darkness. Not ideal. The switch to winter time is generally unpopular with the European crowd, a fact that continues to be ignored by policymakers.

Here is a hack that I’ve tried for 2-3 years now, a system called “European Winter Schedule”. It’s designed to essentially ignore the time change and maximize your daylight leisure time. It’s a tweak around the 9-to-5 working time.

Start the day EARLY, with your first slot of work between 8am–noon. You’ll find less disruption for the first hour, while people rock up. You’ll get ahead with work, especially tasks that require focus.

Then comes then comes the best part: a JUMBO lunch break 12pm–2pm, maybe longer. Get lunch, get out, meet friends, get some sun, go for a run, do groceries. Do whatever, as long as you’ll get some of that daylight it’ll be worth it.

After lunch, back in the trenches for another 4 hours: 2pm–6pm. It’s like a reset after taking a large break and will go so fast. Chances are you’ll be seen as more hard-working: people pay attention to silly things like when people leave, so despite chilling more, you’ll get your boss to love you more.

European Winter Schedule is my go-to move for the winter months. Admittedly it works best without kids, and with a job that allows you to go remote. It also works better outside the US where you’re expected to grid your life away.

Update (2024-06):
Internet has this funny property of making your beliefs/opinions expressed at one time immortal and seem like held forever. And this rather short post continues to haunt me: two separate candidates have mentioned it (concerned). Presumably candidates think that I will put the gun to their head and ask for 100% test coverage. I won’t, I promise… Not over coverage anyway… 100% coverage was definitely the answer at one point in Labstep’s history but the team that inspired that idea departed from it after I moved on. 100% coverage is definitely not appropriate for fast-exploration code-bases (ML Research, SAAS looking for product-market fit). However, I’d still argue that it’s a good idea for any maturing code – I’ve seen too many code-bases become unmaintainable because of “pragmatic” decisions to maybe not test some code because it’s “hard”. What that general vibe is driven by is another question… More introspectively this post remains a clear example of confirmation bias: I held a belief that high test coverage is a good thing, and found some random interview that supported the notion.

Original post

This weekend I stumbled upon a remarkable conversation:

Richard: […] It’s pretty easy to get up to 90 or 95% test coverage. Getting that last 5% is really, really hard and it took about a year for me to get there, but once we got to that point, we stopped getting bug reports from Android. Adam: Oh, wow. Richard: Yeah. IT just worked from there on out. It made a huge, huge difference. We just didn’t really have any bugs for the next eight or nine years.

This is from a conversation with Richard Hipp – the creator of SQLite.

You know what else happened this week? An insane heat wave in the North East of the US (typically an area with “nice” weather). “Jan, you lunatic, what does testing have in common with climate change?”. Bare with me!

Figuring out causality is hard. Really really hard. Even when we really know the mechanism, it’s just baffling. What’s the cause of this extreme heat wave? It’s caused by global warming. What’s the reason for endless bug reports on my project? It’s insufficient testing.

Once you see it, it won’t stop amusing you. People claiming that anything below 100% test coverage is “practical”, “good”, “pragmatic”. That unit testing to the extreme is dogmatic. Or just complete nonsense like this. Meanwhile the bug reports keep coming, and seemingly never stop. Why would that be?

If you understand the link between climate change and extreme weather events, please consider extending your thinking to other parts of life. Bugs don’t come from nowhere, tests prevent them from happening.

So you built your first Pulumi program? Maybe even got some workloads running in production? The team loves it, the thing just works. People are adopting it, adding components, importing more of the existing resources. The stacks are getting bigger… and bigger.

Overnight, what was a simple proof of concept before turns into a 200+ lines of infrastructure code. You look to the community for some best practices: how to structure this thing, how to break it up? How to add some unit tests maybe?

In this article, let’s refactor a Pulumi program and break it down into more re-usable components. The components will be more maintainable and bingo testable. Because there is a bunch of changes to make, we’ll make so incrementally.

This is a problem that many people bump into and most people just want/need guidance and simple rules of thumb to structure their code. What should be a really interesting and valuable proposition (“unit testing you infrastructure code”) becomes hard to achieve.

Other posts in this series

Part 1 – Part 2 – Part 3

Getting a “lay of the land”

Over the last three posts in this series, we worked on a simple static web app (React). We went from a simple S3 bucket architecture, to a solution with a CDN, a domain record and a proper SSL certificate. But as time went on the index.ts became bigger and bigger. This is what it looks like now.

Well this is an unholy messy! Let’s see if we can get from the mess above to neat and tidy the index.ts below.

This truly sparks Marie Kondo-levels of joy! But how do we make it happen?

Refactoring with Janski

Figuring out how to split things out

Let’s have a look at the monster index.ts and see which things we might split off. Color-coding to help the eye.

We can already see three potential improvements:

• stuff related to the Content Delivery Network (S3 bucket, the CDN itself, and the domain record)
• stuff related to the SSL certificate (could come useful, just as a generic “hey get me an SSL for blah”)
• a utility function getDomainAndSubdomain and a constant tenMinutes

Beyond this, the domain name is repeated over and over – just a copy pasted string. That string constant can be easily factored out as a Pulumi config. So let’s get started in reverse order!.

Avoiding domain name repetition

You probably noticed the domain name my-app.somedomain.com being endlessly copy&pasted in the code. This is obviously not good practice but it was simple enough to get started. It can be simply refactored by using the Pulumi config component.

In your terminal simply define a new config value

pulumi config set targetDomain my-app.somedomain.com

This should now update the Pulumi.dev.yaml to look something like this

encryptionsalt: <SOME RANDOM SALT>
config:
  aws:region: eu-west-1
  my-app:targetDomain: my-app.somedomain.com

Now the only thing that remains is to make our Pulumi program index.ts aware of this code.

function main() {
  const stackConfig = new pulumi.Config("my-app");
  const config = {
    // targetDomain is the domain/host to serve content at.
    targetDomain: stackConfig.require("targetDomain"),
  };
}

Now the config.targetDomain can be used to configure the various resources in your program.

Pulling out a simple utils function

The index.ts starts with a simple utility function, this is the simplest refactor of all – the function should just go into a separate util.ts file. While we’re at it, let’s also put the tenMinutes constant in there.

// src/utils.ts
import * as aws from "@pulumi/aws";

export const tenMinutes = 60 * 10;

// Split a domain name into its subdomain and parent domain names.
// e.g. "www.example.com" => "www", "example.com".
export function getDomainAndSubdomain(
  domain: string
): { subdomain: string; parentDomain: string } {
  const parts = domain.split(".");
  if (parts.length < 2) {
    throw new Error(`No TLD found on ${domain}`);
  }
  // No subdomain, e.g. awesome-website.com.
  if (parts.length === 2) {
    return { subdomain: "", parentDomain: domain };
  }

  const subdomain = parts[0];
  parts.shift(); // Drop first element.
  return {
    subdomain,
    // Trailing "." to canonicalize domain.
    parentDomain: parts.join(".") + ".",
  };
}

Refactoring the SSL certificate code

The interesting stuff starts now. In the index.ts, the code looks like this.

  // Per AWS, ACM certificate must be in the us-east-1 region.
  const eastRegion = new aws.Provider("east", {
    profile: aws.config.profile,
    region: "us-east-1",
  });

  const certificate = new aws.acm.Certificate(
    "certificate",
    {
      domainName: "my-app.somedomain.com",
      validationMethod: "DNS",
    },
    { provider: eastRegion }
  );

  /**
   *  Create a DNS record to prove that we _own_ the domain we're requesting a certificate for.
   *  See https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html for more info.
   */
  const certificateValidationDomain = new aws.route53.Record(
    "my-app.somedomain.com-validation",
    {
      name: certificate.domainValidationOptions[0].resourceRecordName,
      zoneId: hostedZoneId,
      type: certificate.domainValidationOptions[0].resourceRecordType,
      records: [certificate.domainValidationOptions[0].resourceRecordValue],
      ttl: tenMinutes,
    }
  );

  /**
   * This is a _special_ resource that waits for ACM to complete validation via the DNS record
   * checking for a status of "ISSUED" on the certificate itself. No actual resources are
   * created (or updated or deleted).
   *
   * See https://www.terraform.io/docs/providers/aws/r/acm_certificate_validation.html for slightly more detail
   * and https://github.com/terraform-providers/terraform-provider-aws/blob/master/aws/resource_aws_acm_certificate_validation.go
   * for the actual implementation.
   */
  const certificateValidation = new aws.acm.CertificateValidation(
    "certificateValidation",
    {
      certificateArn: certificate.arn,
      validationRecordFqdns: [certificateValidationDomain.fqdn],
    },
    { provider: eastRegion }
  );

What’s a good way to refactor this? Let’s refactor this into a “component resource”. Looking top-down, how could we use this component from index.ts?

import { MyCertificate } from "./src/my-certificate";

...

function main() {
  const stackConfig = new pulumi.Config("my-app");
  const config = {
    // targetDomain is the domain/host to serve content at.
    targetDomain: stackConfig.require("targetDomain"),
  };

  const certificate = new MyCertificate('my-certificate', {
    targetDomain: config.targetDomain,
  });
}

Wouldn’t that be neat, huh? A reusable way to generate an SSL certificate for any domain. Well, here is how you do that. All the same components appear again. The special sauce here is { parent: this } which attaches all the resources to the component resource.

Curiously, it can be used to nest multiple components inside another, more than one level deep, when that’s needed.

// Created a new file in src/my-certificate/index.ts

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

import { getDomainAndSubdomain, tenMinutes } from "../utils";

export class MyCertificate extends pulumi.ComponentResource {
  certificate: aws.acm.Certificate;
  certificateValidation: aws.acm.CertificateValidation;

  constructor(
    name: string,
    args: {
      targetDomain: string;
    },
    opts: any = {}
  ) {
    super("pkg:index:Certificate", name, {}, opts);
    const { targetDomain } = args;

    // Per AWS, ACM certificate must be in the us-east-1 region.
    const eastRegion = new aws.Provider(
      "east",
      {
        profile: aws.config.profile,
        region: "us-east-1",
      },
      { parent: this }
    );

    this.certificate = new aws.acm.Certificate(
      "certificate",
      {
        domainName: targetDomain,
        validationMethod: "DNS",
      },
      { provider: eastRegion, parent: this }
    );

    const domainParts = getDomainAndSubdomain(targetDomain);
    const hostedZoneId = aws.route53
      .getZone({ name: domainParts.parentDomain }, { async: true })
      .then((zone) => zone.zoneId);

    /**
     *  Create a DNS record to prove that we _own_ the domain we're requesting a certificate for.
     *  See https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html for more info.
     */
    const certificateValidationDomain = new aws.route53.Record(
      `${targetDomain}-validation`,
      {
        name: this.certificate.domainValidationOptions[0].resourceRecordName,
        zoneId: hostedZoneId,
        type: this.certificate.domainValidationOptions[0].resourceRecordType,
        records: [this.certificate.domainValidationOptions[0].resourceRecordValue],
        ttl: tenMinutes,
      },
      {
        parent: this,
      }
    );

    /**
     * This is a _special_ resource that waits for ACM to complete validation via the DNS record
     * checking for a status of "ISSUED" on the certificate itself. No actual resources are
     * created (or updated or deleted).
     *
     * See https://www.terraform.io/docs/providers/aws/r/acm_certificate_validation.html for slightly more detail
     * and https://github.com/terraform-providers/terraform-provider-aws/blob/master/aws/resource_aws_acm_certificate_validation.go
     * for the actual implementation.
     */
    this.certificateValidation = new aws.acm.CertificateValidation(
      "certificateValidation",
      {
        certificateArn: this.certificate.arn,
        validationRecordFqdns: [certificateValidationDomain.fqdn],
      },
      { provider: eastRegion, parent: this }
    );
  }
}

Refactoring the CDN component

Much like the certificate, the CDN definition is rather verbose. Especially the DistributionArgs takes like 70 lines of code :yikes:!

  const distributionArgs: aws.cloudfront.DistributionArgs = {
    ... // a massive JS object
  }

Let’s start by putting defining a function that creates DistributionArgs inside a new file.

// Created a new file in src/my-app/index.ts

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

import { tenMinutes, getDomainAndSubdomain } from "../utils";

function createDistributionArgs(
  targetDomain: string,
  bucket: aws.s3.Bucket,
  certificateValidation: aws.acm.CertificateValidation,
  tenMinutes: number
): aws.cloudfront.DistributionArgs {
  // distributionArgs configures the CloudFront distribution. Relevant documentation:
  // https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html
  // https://www.terraform.io/docs/providers/aws/r/cloudfront_distribution.html
  return {
    enabled: true,
    // Alternate aliases the CloudFront distribution can be reached at, in addition to https://xxxx.cloudfront.net.
    // Required if you want to access the distribution via config.targetDomain as well.
    aliases: [targetDomain],

    // We only specify one origin for this distribution, the S3 content bucket.
    origins: [
      {
        originId: bucket.arn,
        domainName: bucket.websiteEndpoint,
        customOriginConfig: {
          // Amazon S3 doesn't support HTTPS connections when using an S3 bucket configured as a website endpoint.
          // https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesOriginProtocolPolicy
          originProtocolPolicy: "http-only",
          httpPort: 80,
          httpsPort: 443,
          originSslProtocols: ["TLSv1.2"],
        },
      },
    ],

    defaultRootObject: "index.html",

    // A CloudFront distribution can configure different cache behaviors based on the request path.
    // Here we just specify a single, default cache behavior which is just read-only requests to S3.
    defaultCacheBehavior: {
      targetOriginId: bucket.arn,

      viewerProtocolPolicy: "redirect-to-https",
      allowedMethods: ["GET", "HEAD", "OPTIONS"],
      cachedMethods: ["GET", "HEAD", "OPTIONS"],

      forwardedValues: {
        cookies: { forward: "none" },
        queryString: false,
      },

      minTtl: 0,
      defaultTtl: tenMinutes,
      maxTtl: tenMinutes,
    },

    // "All" is the most broad distribution, and also the most expensive.
    // "100" is the least broad, and also the least expensive.
    priceClass: "PriceClass_100",

    // You can customize error responses. When CloudFront receives an error from the origin (e.g. S3 or some other
    // web service) it can return a different error code, and return the response for a different resource.
    customErrorResponses: [
      { errorCode: 404, responseCode: 404, responsePagePath: "/404.html" },
    ],

    restrictions: {
      geoRestriction: {
        restrictionType: "none",
      },
    },

    viewerCertificate: {
      acmCertificateArn: certificateValidation.certificateArn, // Per AWS, ACM certificate must be in the us-east-1 region.
      sslSupportMethod: "sni-only",
    },
  };
}

Pulling out this verbose chunk, we can define a new component resource in the same file. Let’s go ahead and update src/my-app/index.ts.

// Editing in src/my-app/index.ts
export class MyApp extends pulumi.ComponentResource {
  bucket: aws.s3.Bucket;
  cdn: aws.cloudfront.Distribution;
  record: aws.route53.Record;

  constructor(
    name: string,
    args: {
      targetDomain: string;
      certificateValidation: aws.acm.CertificateValidation;
    },
    opts: any = {}
  ) {
    super("pkg:index:MyApp", name, {}, opts);
    const { targetDomain, certificateValidation } = args;
    // Create an AWS resource (S3 Bucket)
    this.bucket = new aws.s3.Bucket(
      targetDomain,
      {
        bucket: targetDomain,
        acl: "public-read",
        website: {
          indexDocument: "index.html",
        },
      },
      { parent: this }
    );

    const distributionArgs = createDistributionArgs(
      targetDomain,
      this.bucket,
      certificateValidation,
      tenMinutes
    );

    this.cdn = new aws.cloudfront.Distribution("cdn", distributionArgs, {
      parent: this,
    });

    const domainParts = getDomainAndSubdomain(targetDomain);
    const hostedZoneId = aws.route53
      .getZone({ name: domainParts.parentDomain }, { async: true })
      .then((zone) => zone.zoneId);

    // Create a Route53 A-record
    this.record = new aws.route53.Record(
      "targetDomain",
      {
        name: targetDomain,
        zoneId: hostedZoneId,
        type: "A",
        aliases: [
          {
            name: this.cdn.domainName,
            zoneId: this.cdn.hostedZoneId,
            evaluateTargetHealth: true,
          },
        ],
      },
      { parent: this }
    );
  }
}

And voila, another nice component resource to include in index.ts. Looking top-down here is how it can used?

import { MyApp } from "./src/my-app";

...

function main() {
  const stackConfig = new pulumi.Config("my-app");
  const config = {
    // targetDomain is the domain/host to serve content at.
    targetDomain: stackConfig.require("targetDomain"),
  };

  const certificate = new MyCertificate('my-certificate', {
    targetDomain: config.targetDomain,
  });

  const myApp = new MyApp("my-app", {
    targetDomain: config.targetDomain,
    certificateValidation: certificate.certificateValidation,
  });
}

Wrapping up here are some follow-up resources. I found nothing about best way to structure pulumi projects, so I just improvised here – this is what worked for me.

• The topic of component resources is covered briefly in the Programming Model of Pulumi docs,
• There also appears to be a nice official tutorial with an S3 bucket example.

Visual improvement in project structure

And you know what’s great? The structure of the stack resources is visibly improved. Initially the output of pulumi refresh looked something like this

$ pulumi refresh -y
Previewing refresh (dev):
     Type                              Name                               Plan     
     pulumi:pulumi:Stack               my-app-dev                                  
     ├─ pulumi:providers:aws           east                                        
     ├─ aws:acm:CertificateValidation  certificateValidation                       
     ├─ aws:acm:Certificate            certificate                                 
     ├─ aws:route53:Record             my-app.somedomain.com-validation           
     ├─ aws:s3:Bucket                  my-app.somedomain.com                      
     ├─ aws:route53:Record             targetDomain                                
     └─ aws:cloudfront:Distribution    cdn                                         
 
Resources:
    8 unchanged

All the resources are a flat list, without any visual linkage or grouping between them. However, after our little refactoring this now looks much cleaner, with resources being grouped logically.

$ pulumi refresh 
Previewing refresh (dev):
     Type                                 Name                               Plan           
     pulumi:pulumi:Stack                  my-app-dev                         running...     
     ├─ pkg:index:Certificate             my-certificate                                    
     │  ├─ pulumi:providers:aws           east                                              
     │  ├─ aws:acm:CertificateValidation  certificateValidation                             
     │  ├─ aws:route53:Record             my-app.somedomain.com-validation                 
     │  └─ aws:acm:Certificate            certificate                                       
     └─ pkg:index:MyApp                   my-app                                            
        ├─ aws:route53:Record             targetDomain                                      
        ├─ aws:s3:Bucket                  my-app.somedomain.com             refreshing...  
        └─ aws:cloudfront:Distribution    cdn                                               

Unit testing resource components

Some of you might be thinking “wait, what? unit testing infrastructure? I thought you could only big integration tests where infrastructure is spun up?”. Well, prepare your mind to be blown. Pulumi mocks cloud provider responses allowing you to mock that a fake piece of infrastructure is created. Relative to tests with jest that you might be familiar with, things are a bit more awkward here but still okay.

Let’s start by building a unit test for the MyCertificate component. What does this test need to include? Well, my certificate internall creates at least two resources:

• Certificate – aws:acm/certificate:Certificate
• CertificateValidation – aws:acm/certificateValidation:CertificateValidation

So for both of these a mock is needed. Pulumi exposes an API for unit testing via pulumi.runtime.setMocks that allows for API responses to be mocked. Here is how you can start

// Create a new file in src/my-certificate/index.test.ts

import * as pulumi from "@pulumi/pulumi";
import * as assert from "assert";
import "mocha";

pulumi.runtime.setMocks({
  newResource: function (
    type: string,
    name: string,
    inputs: any
  ): { id: string; state: any } {
    switch (type) {
      case "aws:acm/certificate:Certificate":
        return {
          id: inputs.name + "_id",
          state: {
            ...inputs,
            arn: "arn:aws:some-cert-arn",
          },
        };
      case "aws:acm/certificateValidation:CertificateValidation":
        return {
          id: inputs.name + "_id",
          state: {
            ...inputs,
          },
        };
      default:
        return {
          id: inputs.name + "_id",
          state: {
            ...inputs,
          },
        };
    }
  },
  call: function (token: string, args: any, provider?: string) {
    return args;
  },
});

That’s a little verbose but gives us control on the state of the returned object. For example, see you the ARN is set on the Certificate via arn: "arn:aws:some-cert-arn".

Next, we import the module under test, and write down the tests as usual using describe() definitions.

// Continuing in src/my-certificate/index.test.ts

// It's important to import the program _after_ the mocks are defined.
import * as infra from "./index";

describe("MyCertificate", function () {
  const targetDomain = "some.domain.com";
  const resource = new infra.MyCertificate("my-certificate", {
    targetDomain,
  });
  it("must have a targetDomain", function (done) {
    pulumi.all([resource.certificate.domainName]).apply(([domainName]) => {
      assert.equal(domainName, targetDomain);
      done();
    });
  });
  it("must have a certificateValidation", function (done) {
    pulumi
      .all([resource.certificateValidation.certificateArn])
      .apply(([certificateArn]) => {
        assert.equal(certificateArn, "arn:aws:some-cert-arn");
        done();
      });
  });
});

Two asserts are declared here:

• the certificate takes on the targetDomain passed from the config,
• the certificateValidation gets the arn from the certificate.

Simple enough and effective for this very simple component.

How do you actually run the test itself? Again it’s a bit more verbose than ideal…

node_modules/.bin/mocha -r ts-node/register src/my-certificate/index.test.ts 

  MyCertificate
    ✓ must have a targetDomain
    ✓ must have a certificateValidation


  2 passing (7ms)

Further reading could include the official documentation for unit testing.

Conclusions

Refactoring

Take action before your Pulumi project becomes a long index.ts file with hundreds of resources. You can take advantage of compound resources to break code up into smaller, re-usable chunks. Beyond just making the code maintainable, it’ll allow you to unit-test the components in isolation.

Testing

I can’t say that I loved writing Pulumi unit tests in Typescript. It feels awkward and clunky, relative to my experience with other tools (Jest?). Despite all my love for Pulumi, you won’t hear me sing accolades here. Still, it’s infinitely better than having no unit tests at all. Together with a robust integration tests, it should be entirely possible to bring the best of testing into your infrastructure code.

Introduction

Welcome back to the series! We’re nearly done here with your SPA application happily sitting behind a domain an an S3 bucket. Why push forward, you might ask? After all things are looking pretty dandy. Well, it turns out that serving files from your S3 bucket may not be the ideal option. Depending on how often your website changes on S3, and its probably not that often, you’re essentially serving the same files over and over again. Would that make for an excellent case for caching? It would.

Putting a content distribution network in front of the S3 bucket would allow you to cache the responses to incoming requests. For example, once a CSS file is shipped once, the CDN will keep track of it.

Well, this seems complicated, is it really worth it? This setup is as close to “industry best practice as it gets”. As a matter of fact, I’ll be ripping off from Pulumi’s own tutorial pretty heavily and shamelessly. But to be completely honest, for a small page like it probably doesn’t make sense. Using GitHub Pages would be just as suitable of an alternative.

Other posts in this series

Part 1 – Part 2 – Part 4

The plan

This is it people – it’s the 3rd part and so we’re entering “level HARD”. No more joking around – and if you completed parts I and II, you’re practically a cloud engineer now ;-)

The principal aim will be to create an AWS CloudFront resource and place it between the S3 bucket and the Route53 domain. Additionally, we will create a new bucket for storing AWS CloudFront logs – but that’s just a nice to have.

As we’re about to jump in, the time is ripe for a friendly warning:

In this post we’ll be working with the AWS CloudFront service, which is notoriously slow to work with – in the sense of configuration changes taking 15-20 minutes to perform.

So don’t get your coffee just yet – there will be plenty of opportunity to do that later.

Results

Logging back into Pulumi

Before jumping in, and especially if you’re returning to this series after a break, make sure that your Pulumi environment is configured correctly.

Here is a handy checklist

• Did you login to the right Pulumi project with pulumi login?
• Did you configure PULUMI_CONFIG_PASSPHRASE as your environment variable?

If yes, you can check if it’s all working with pulumi stack to display the resources in the stack.

$ pulumi stack
Current stack is dev:
    Managed by jans-mbp.mynet
    Last updated: 1 minute ago (2020-10-31 07:10:29.907622 +0000 UTC)
    Pulumi version: v2.12.1
Current stack resources (4):
    TYPE                              NAME
    pulumi:pulumi:Stack               my-app-dev
    ├─ aws:s3/bucket:Bucket           my-app.jandomanski.com
    ├─ aws:route53/record:Record      targetDomain
    └─ pulumi:providers:aws           default_3_11_0

Current stack outputs (2):
    OUTPUT      VALUE
    bucketName  my-app.jandomanski.com
    recordName  my-app.jandomanski.com

Defining a helper function

Let’s kick off with a very simple helper function. The helper function takes a domain (“www.example.com”) and returns an object with 2 properties (subdomain and parentDomain). What this is needed for will become apparent soon!

// Split a domain name into its subdomain and parent domain names.
// e.g. "www.example.com" => "www", "example.com".
function getDomainAndSubdomain(
  domain: string
): { subdomain: string; parentDomain: string } {
  const parts = domain.split(".");
  if (parts.length < 2) {
    throw new Error(`No TLD found on ${domain}`);
  }
  // No subdomain, e.g. awesome-website.com.
  if (parts.length === 2) {
    return { subdomain: "", parentDomain: domain };
  }

  const subdomain = parts[0];
  parts.shift(); // Drop first element.
  return {
    subdomain,
    // Trailing "." to canonicalize domain.
    parentDomain: parts.join(".") + ".",
  };
}

Building the foundations

What do we have now? We have an S3 bucket and a Route53 record. We agreed to slot in a CDN in between those two. How exactly do we do that?

The CDN can serve responses via HTTPS so let’s provide it with a SSL certificate, as a nice bonus quest. So let’s start by setting this up: insert the following snippet after the bucket definition.

  const domainParts = getDomainAndSubdomain("my-app.jandomanski.com");
  const hostedZoneId = aws.route53
    .getZone({ name: domainParts.parentDomain }, { async: true })
    .then((zone) => zone.zoneId);

  const tenMinutes = 60 * 10;

  // Per AWS, ACM certificate must be in the us-east-1 region.
  const eastRegion = new aws.Provider("east", {
    profile: aws.config.profile,
    region: "us-east-1",
  });

• The tenMinutes is just a simple constant that we’ll use later,
• The eastRegion is more interesting.

The eastRegion is just a resource, like everything else in Pulumi, but it’s important for the SSL. The SSL certificates can only be created in the “us-east-1” region. My default region is “eu-west-1” and thus I need an additional provider to create other resources in that region. This may not be necessary for you if you’re already using the “us-east-1” region.

This looks like a simple enough change, so let’s be “greedy” and get this update done. Quick win to start the post. Here is what you should seen when you run pulumi up.

$ pulumi up
Previewing update (dev):
     Type                     Name        Plan       
     pulumi:pulumi:Stack      my-app-dev             
 +   └─ pulumi:providers:aws  east        create     
 
Resources:
    + 1 to create
    3 unchanged

Do you want to perform this update? yes
Updating (dev):
     Type                     Name        Status      
     pulumi:pulumi:Stack      my-app-dev              
 +   └─ pulumi:providers:aws  east        created     
 
Outputs:
    bucketName: "my-app.jandomanski.com"
    recordName: "my-app.jandomanski.com"

Resources:
    + 1 created
    3 unchanged

Duration: 16s

Creating and validating an SSL certificate

With the eastProvider we can now create an SSL certificate on AWS. If you’ve ever done it manually, this will be pure magic. Using a special resource, you can *automatically validate the SSL certificate. No more email validation, or manual DNS validation! In this case, a Route53 record is created automatically to validate the certificate.

  const certificate = new aws.acm.Certificate(
    "certificate",
    {
      domainName: "my-app.jandomanski.com",
      validationMethod: "DNS",
    },
    { provider: eastRegion }
  );

  const certificateValidationDomain = new aws.route53.Record(
    "my-app.jandomanski.com-validation",
    {
      name: certificate.domainValidationOptions[0].resourceRecordName,
      zoneId: hostedZoneId,
      type: certificate.domainValidationOptions[0].resourceRecordType,
      records: [certificate.domainValidationOptions[0].resourceRecordValue],
      ttl: tenMinutes,
    }
  );

  const certificateValidation = new aws.acm.CertificateValidation(
    "certificateValidation",
    {
      certificateArn: certificate.arn,
      validationRecordFqdns: [certificateValidationDomain.fqdn],
    },
    { provider: eastRegion }
  );

Let’s run the update and get our SSL certificate. Here is what the pulumi output should look like:

$ pulumi up 
Previewing update (dev):
     Type                              Name                               Plan       
     pulumi:pulumi:Stack               my-app-dev                                    
 +   ├─ aws:acm:Certificate            certificate                        create     
 +   ├─ aws:route53:Record             my-app.jandomanski.com-validation  create     
 +   └─ aws:acm:CertificateValidation  certificateValidation              create     
 
Resources:
    + 3 to create
    4 unchanged

Do you want to perform this update? yes
Updating (dev):
     Type                              Name                               Status      
     pulumi:pulumi:Stack               my-app-dev                                     
 +   ├─ aws:acm:Certificate            certificate                        created     
 +   ├─ aws:route53:Record             my-app.jandomanski.com-validation  created     
 +   └─ aws:acm:CertificateValidation  certificateValidation              created     
 
Outputs:
    bucketName: "my-app.jandomanski.com"
    recordName: "my-app.jandomanski.com"

Resources:
    + 3 created
    4 unchanged

Duration: 57s

Configuring and creating the CDN

AWS CloudFront is a complicated service with a lot of belts and whistles. Examples include

• HTTPS -> HTTPS redirects,
• ability to use AWS Lambdas to process requests and responses,
• injecting custom headers.

Many of these features can be defined by DistributionArgs. It’s rather verbose and almost completely copy&pasted from the Pulumi Tutorial . If you want a better sense of what’s available in CDN configuration, have a look below:

  // distributionArgs configures the CloudFront distribution. Relevant documentation:
  // https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html
  // https://www.terraform.io/docs/providers/aws/r/cloudfront_distribution.html
  const distributionArgs: aws.cloudfront.DistributionArgs = {
    enabled: true,
    // Alternate aliases the CloudFront distribution can be reached at, in addition to https://xxxx.cloudfront.net.
    // Required if you want to access the distribution via config.targetDomain as well.
    aliases: ["my-app.jandomanski.com"],

    // We only specify one origin for this distribution, the S3 content bucket.
    origins: [
      {
        originId: bucket.arn,
        domainName: bucket.websiteEndpoint,
        customOriginConfig: {
          // Amazon S3 doesn't support HTTPS connections when using an S3 bucket configured as a website endpoint.
          // https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesOriginProtocolPolicy
          originProtocolPolicy: "http-only",
          httpPort: 80,
          httpsPort: 443,
          originSslProtocols: ["TLSv1.2"],
        },
      },
    ],

    defaultRootObject: "index.html",

    // A CloudFront distribution can configure different cache behaviors based on the request path.
    // Here we just specify a single, default cache behavior which is just read-only requests to S3.
    defaultCacheBehavior: {
      targetOriginId: bucket.arn,

      viewerProtocolPolicy: "redirect-to-https",
      allowedMethods: ["GET", "HEAD", "OPTIONS"],
      cachedMethods: ["GET", "HEAD", "OPTIONS"],

      forwardedValues: {
        cookies: { forward: "none" },
        queryString: false,
      },

      minTtl: 0,
      defaultTtl: tenMinutes,
      maxTtl: tenMinutes,
    },

    // "All" is the most broad distribution, and also the most expensive.
    // "100" is the least broad, and also the least expensive.
    priceClass: "PriceClass_100",

    // You can customize error responses. When CloudFront receives an error from the origin (e.g. S3 or some other
    // web service) it can return a different error code, and return the response for a different resource.
    customErrorResponses: [
      { errorCode: 404, responseCode: 404, responsePagePath: "/404.html" },
    ],

    restrictions: {
      geoRestriction: {
        restrictionType: "none",
      },
    },

    viewerCertificate: {
      acmCertificateArn: certificateValidation.certificateArn, // Per AWS, ACM certificate must be in the us-east-1 region.
      sslSupportMethod: "sni-only",
    },
  };

Finally, let’s add a line to create the CDN and run pulumi up.

  const cdn = new aws.cloudfront.Distribution("cdn", distributionArgs);

Before proceeding, you should know one thing.

WARNING AWS CloudFormation is a very big service and it can take a WHILE (5-25 minutes) to create or update resources

Here is what your pulumi up should look like

$ pulumi up 
Previewing update (dev):
     Type                            Name        Plan       
     pulumi:pulumi:Stack             my-app-dev             
 +   └─ aws:cloudfront:Distribution  cdn         create     
 
Resources:
    + 1 to create
    7 unchanged

Do you want to perform this update? yes
Updating (dev):
     Type                            Name        Status      
     pulumi:pulumi:Stack             my-app-dev              
 +   └─ aws:cloudfront:Distribution  cdn         created     
 
Outputs:
    bucketName: "my-app.jandomanski.com"
    recordName: "my-app.jandomanski.com"

Resources:
    + 1 created
    7 unchanged

Duration: 2m53s

Updating the Route53

This is the final step and should take no time at all! At the moment, we have a Route53 record that points to the S3 bucket holding the React app. The Route53 record is defined like this:

  // Create a Route53 A-record
  const record = new aws.route53.Record("targetDomain", {
    name: "my-app.jandomanski.com",
    zoneId: hostedZoneId,
    type: "A",
    aliases: [
      {
        zoneId: bucket.hostedZoneId,
        name: bucket.websiteDomain,
        evaluateTargetHealth: true,
      },
    ],
  });

Now that we have a CDN, we can update the Route53 record to point to a new endpoint. Same domain name, same zoneId, just pointing to the new CDN – which acts as a proxy for the S3 bucket.

  // Create a Route53 A-record
  const record = new aws.route53.Record("targetDomain", {
    name: "my-app.jandomanski.com",
    zoneId: hostedZoneId,
    type: "A",
    aliases: [
      {
        name: cdn.domainName,
        zoneId: cdn.hostedZoneId,
        evaluateTargetHealth: true,
      },
    ],
  });

Here is how the pulumi log output looks like

$ pulumi up 
Previewing update (dev):
     Type                   Name          Plan       Info
     pulumi:pulumi:Stack    my-app-dev               
 ~   └─ aws:route53:Record  targetDomain  update     [diff: ~aliases]
 
Resources:
    ~ 1 to update
    7 unchanged

Do you want to perform this update? yes
Updating (dev):
     Type                   Name          Status      Info
     pulumi:pulumi:Stack    my-app-dev                
 ~   └─ aws:route53:Record  targetDomain  updated     [diff: ~aliases]
 
Outputs:
    bucketName: "my-app.jandomanski.com"
    recordName: "my-app.jandomanski.com"

Resources:
    ~ 1 updated
    7 unchanged

Duration: 51s

Testing if it all works

There are some quick ways to diagnose if we got what we want the two simple tests should be

• open http://my-app.jandomanski.com -> should redirect to https://
• open https://my-app.jandomanski.com -> should open index.html
• open https://my-app.jandomanski.com/index.html -> same as above

Beyond, there are some further advanced experiments we can do using curl.

First of all, remember index.html and how we set the Cache-Control headers? Well, those are respected by the CDN. You can clearly see this by hitting the endpoint with cURL.

$ curl https://my-app.jandomanski.com/index.html -I
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 2219
Connection: keep-alive
Date: Sun, 01 Nov 2020 19:20:52 GMT
Cache-Control: no-cache,no-store
Last-Modified: Sun, 01 Nov 2020 19:20:43 GMT
ETag: "67e4d5da5073a0ba60ce72a01c3feee4"
Server: AmazonS3
X-Cache: Miss from cloudfront
Via: 1.1 a5c420a169b19bd150b00f34513e997d.cloudfront.net (CloudFront)
X-Amz-Cf-Pop: LHR62-C3
X-Amz-Cf-Id: P3048HiqZZ66rJ2PujNg44G51v2wzkwumXp1aO2LOumDmbsT03nVFg==

You can hit this over and over again, in all cases you’ll get X-Cache: Miss from cloudfront and Cache-Control: no-cache,no-store. Because of the Cache-Control header, the content is always served from S3 directly. What about other files? Does caching work for them as expected?

$ curl https://my-app.jandomanski.com/favicon.ico -I
HTTP/1.1 200 OK
Content-Type: image/x-icon
Content-Length: 3150
Connection: keep-alive
Date: Sun, 01 Nov 2020 19:24:45 GMT
Cache-Control: max-age=31536000
Last-Modified: Sat, 31 Oct 2020 08:31:51 GMT
ETag: "6e1267d9d946b0236cdf6ffd02890894"
Server: AmazonS3
X-Cache: Hit from cloudfront
Via: 1.1 6fc6ff9b881f0fff41ff95cfddcc92eb.cloudfront.net (CloudFront)
X-Amz-Cf-Pop: LHR52-C1
X-Amz-Cf-Id: 6MIpI2IkMlT1UiGnmP4hsO8qM_TIbxEG5ZbhRh3fhoGREYz_O08Snw==
Age: 3

Can you see the Cache-Control and X-Cache headers above? Both indicate a few things about the CDN:

• it respected the Cache-Control property we set on the S3 objects,
• it cached the appropriate files, and is serving them from cache – no trips to the S3 bucket are done.

Conclusions

So that’s it, right? Over the course of the series, we travelled from a very simple S3 hosting of a simple site. Things were simple then but not very cost efficient. Then we added a Route53 domain for some nice access. Finally, we put a CDN in front of the S3 bucket as a caching layer.

But did we sacrifice something? The initial index.ts seemed very simple but the one we have now is quite large. Is there a way to refactor? How to make this more modular? What about testing? Is there an easy way to test this code, without creating the infrastructure? Well, those are very wise questions indeed – and we’ll answer them in the BONUS fourth part to this series.

Introduction

Welcome back to part II in the series! If you remember, we’re going to figure out how to deploy a small Create React App to AWS infrastructure. How are we going to do that exactly? Using a neat tool called Pulumi. While using Create React App as an example, we’ll cover reusable architectures for creating any web apps on AWS infrastructure.

The series is mainly targeted at frontend developers who want to get their hands dirty with AWS infrastructure. The series can also be useful if you’re looking for a gateway drug into the majestic world of Pulumi.

By way of a re-cap, what did we do last time?

• Outlined 3 possible architectures (easy, medium and hard),
• Transpiled a ‘stock’ Create React App and got a build,
• Setup boilerplate for managing stacks of infrastructure resources is Pulumi,
• Deployed the “easy” architecture (a single S3 bucket).

With all this out of the way, we have some new interesting waters to sail.

Other posts in this series

Part 1 - Part 3 – Part 4

The plan

So what’s new this time around? We’ll be putting together the “medium architecture”, it’s time to make things interesting. What exactly are looking for? Well, instead of accessing the app via the S3 bucket URL, it’d be nice to park it behind a proper domain (www.your-create-react-app.com). AWS manages DNS records via a service called Route53, so we’re going to use that.

What domain do we want use? It doesn’t really matter, maybe use some domain that you already bought? In this guide, I’ll use a subdomain at myapp.jandomanski.com.

Results

Before jumping in, and especially if you’re returning to this series after a break, make sure that your Pulumi environment is configured correctly.

Here is a handy checklist

• Did you login to the right Pulumi project with pulumi login?
• Did you configure PULUMI_CONFIG_PASSPHRASE as your environment variable?

If yes, you can check if it’s all working with pulumi stack to display the resources in the stack.

$ pulumi stack
Current stack is dev:
    Managed by jans-mbp.mynet
    Last updated: 2 weeks ago (2020-08-31 21:21:49.628757 +0100 BST)
    Pulumi version: v2.9.1
Current stack resources (4):
    TYPE                              NAME
    pulumi:pulumi:Stack               my-app-dev
    ├─ aws:s3/bucket:Bucket           my-app.jandomanski.com
    ├─ aws:route53/record:Record      targetDomain
    └─ pulumi:providers:aws           default_2_13_0

Current stack outputs (2):
    OUTPUT      VALUE
    bucketName  my-app.jandomanski.com
    recordName  my-app.jandomanski.com

Updating the definition of an S3 bucket

At the end of the last article, we were left with the following Pulumi program. The program create an S3 bucket that we could access at a public URL my-bucket-f01e841.s3-eu-west-1.amazonaws.com.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket("my-bucket", {
    acl: "public-read",
    website: {
        indexDocument: "index.html",
    },
});

// Export the name of the bucket
export const bucketName = bucket.id;

That’s a good start but hardly adequate. How can we publish your app to my-bucket-f01e841.s3-eu-west-1.amazonaws.com? Clearly nobody will care, it looks weird. What’s needed here is a nice domain such as my-app.jandomanski.com.

To get there, we first need rewrite that program slightly: to serve contents as a website, the S3 service needs bucket names to contain the domain name.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket("my-app.jandomanski.com", {
    bucket: "my-app.jandomanski.com",
    acl: "public-read",
    website: {
        indexDocument: "index.html",
    },
});

// Export the name of the bucket
export const bucketName = bucket.id;

Then we run the familiar pulumi up and here is a recording of how things should play out: my-bucket gets deleted and my-app.jandomanski.com gets created.

Refactoring to wrap in a main function

Things are looking great – we’re iteratively moving towards the designed solution. It’s time for a little twist: a refactor to wrap our program into a main function. For now it’s just eye-candy and doesn’t really change too much.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";

function main() {
  // Create an AWS resource (S3 Bucket)
  const bucket = new aws.s3.Bucket("my-app.jandomanski.com", {
    bucket: "my-app.jandomanski.com",
    acl: "public-read",
    website: {
      indexDocument: "index.html",
    },
  });

  return {
    // Export the name of the bucket
    bucketName: bucket.id,
  };
}

module.exports = main();

We can now run pulumi up again but since no resources are changed, it doesn’t really matter.

Adding a Route 53 A-record

What’s our aim here? We need to put our S3 bucket behind a domain. To do that, we need to create a Route53 record in the DNS. How do we create Route53 record in the DNS? Well, we take an existing hosted zone (I’m assuming that you have that setup already) and use that to create the Record.

Getting the hosted zone uses this magical invocation

aws.route53.getZone({ name: "jandomanski.com" }, { async: true }).then(...)

Here is the entire pulumi program. It retrieves the hosted zone information (a promise, under the hood) and creates a DNS record linking the domain to the S3 bucket.

function main() {
  // Create an AWS resource (S3 Bucket)
  const bucket = new aws.s3.Bucket("my-app.jandomanski.com", {
    bucket: "my-app.jandomanski.com",
    acl: "public-read",
    website: {
      indexDocument: "index.html",
    },
  });

  // Get the hosted zone by domain name
  const hostedZoneId = aws.route53
    .getZone({ name: "jandomanski.com" }, { async: true })
    .then((zone) => zone.id);

  // Create a Route53 A-record
  const record = new aws.route53.Record("targetDomain", {
    name: "my-app.jandomanski.com",
    zoneId: hostedZone.zoneId,
    type: "A",
    aliases: [{
        zoneId: bucket.hostedZoneId,
        name: bucket.websiteDomain,
        evaluateTargetHealth: true,
    }],
  });

  return {
    // Export the name of the bucket
    bucketName: bucket.id,
    // Export the name of the record
    recordName: record.name,
  };
}

With our new program, we need to run pulumi up again to create new resources with our cloud provider. Here is a recording that shows more-or-less what should happen.

Using dig to confirm domain configuration change

Joy fills the air - you did it! Using a small Pulumi program, you ran to AWS and made it update the DNS for your website. But you know what’s the funny thing about DNS changes? Changes to the DNS can tak a while to propagate.

Hang on… but what if something is not working? Let’s say you go to my-app.jandomanski.com in your browser and the page doesn’t open. What then? How do you know if you still need for the DNS to propagate VS if there was a bug in your config that got propatade? What tools are available to diagnose DNS issues? Well, look no further keen reader and open your mind to the power of dig.

dig is the master tool that you need to know, just like cURL.

Importantly, while cURL is the tool to master with HTTP requests, dig is the universal device for dealing with DNS issues.

$ dig my-app.jandomanski.com A 
[...]

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;my-app.jandomanski.com.		IN	A

;; AUTHORITY SECTION:
jandomanski.com.	113	IN	SOA	ns-906.awsdns-49.net. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400

After the change

$ dig my-app.jandomanski.com A
[...]

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;my-app.jandomanski.com.		IN	A

;; ANSWER SECTION:
my-app.jandomanski.com.	5	IN	A	52.218.97.212

The relevant change to look for is the change from “AUTHORITY SECTION” to “ANSWER SECTION” that contains a valid IP4 address.

Another tool that you can use to diagnose DNS issue is nslookup, try nslookup my-app.jandomanski.com.

Using cURL to confirm page contents can be loaded

We’re almost there! We’ve created a DNS record and confirmed that it has been propagated correctly using dig. What’s left to do is to confirm that your app can still be accessed. Accessing it via the bucket URL should continue to work, let’s confirm that quickly.

$ curl http://my-app.jandomanski.com.s3-website-eu-west-1.amazonaws.com -I
HTTP/1.1 200 OK
x-amz-id-2: GmBsU0g/xUwEbglwJtNF9kccPdPooUengo+M4JJUF74sS9qVK81mByp7mAL4LMyTcq8vOBSEYWw=
x-amz-request-id: 54B4D8A94D9BF9F8
Date: Mon, 31 Aug 2020 20:17:44 GMT
Cache-Control: no-cache,no-store
Last-Modified: Mon, 31 Aug 2020 20:15:25 GMT
ETag: "67e4d5da5073a0ba60ce72a01c3feee4"
Content-Type: text/html
Content-Length: 2219
Server: AmazonS3

Okay, all good here. What about accessing it via the domain? Let’s try a simple test via curl just like above.

$ curl http://my-app.jandomanski.com -I
HTTP/1.1 200 OK
x-amz-id-2: Gf/CYg8wVqE9DH1qj6/YCkCJU7NfgukwsENIEKGRuXRs0B33557+euz5mKtiTvskWSyYaHvwFrE=
x-amz-request-id: 4F134C079414F428
Date: Mon, 31 Aug 2020 20:25:52 GMT
Cache-Control: no-cache,no-store
Last-Modified: Mon, 31 Aug 2020 20:15:25 GMT
ETag: "67e4d5da5073a0ba60ce72a01c3feee4"
Content-Type: text/html
Content-Length: 2219
Server: AmazonS3

Whoa, that’s really cool! It worked!

Conclusions

Well done for bearing with this one! We took a pretty windy road through the space of infrastructure and Pulumi. There was a lot of group covered in this post:

• New Pulumi concepts in managing DNS records via the AWS Route53 service,
• Diagnosing and debugging DNS setting using dig.

This was much harder than the previous “easy” architecture, and a lot more complex! Now you have a domain with an S3 bucket but is that all we need?

• What about access via HTTPS?
• What happens if many people access the domain?
• How does AWS price access to S3 bucket contents? Can we cache them somehow?

All this and more in the 3rd and final episode.

Credits

Still waiting for some eager reviewers

Introduction

So you have just created your first app with Create React App. You built it, changed some source files. It works! Well, it works on your machine. What’s next? How do you actually get it out there, running?

You can build it but you want to ship it.

The aim of this series of posts is to provide a step-by-step, incremental improvement journey. The posts will show how to build your infrastructure, starting from the simplest configuration. What’s the point in showing you how to build the castle, if it’s not clear why one needs anything more than a shack?

This series may be particularly interesting to frontend developers who want to increase their understanding of infrastructure.

Going beyond just a cookbook recipe will be a must (troubleshooting should be an essential part of any series). When possible, debug and diagnostic commands are run to make sure things are in the state that they need to be.

This will be a big journey but if we can break it up into smaller iterative sub-steps, we’ll go from a shack to a castle.

Other posts in this series

Part 2 – Part 3 – Part 4

The plan

What will we need from AWS? It is going to be a million services or just a few? For now just one: the app will need an S3 bucket to place the transpiled JS files for Create React App.

There are further wrinkles:

• How to ensure an encrypted SSL connection?
• Which caching settings to use for the resources?
• How to scale the service in the future and how to monitor it?

All these we’ll be covered in the series – we’ll be building up from the simplest shack to a more robust configuration.

To click or not to click?

What’s the gateway drug of AWS? It’s obviously the AWS console. Things are very easy to setup but once the complexity becomes larger, things get trickier. How trickier? Suppose you want to do a production environments but then also a staging and a testing environments. How would you apply a configuration change across all three environments? Well, unfortunately, it’s point and click with the AWS console. We don’t want to do that, so we’ll use something else, a tool called Pulumi. True infrastructure as code.

Why Pulumi?

Let’s start by explaining the choice of Pulumi since it’s a relatively new tool. A catchy (and provocative) summary would be:

Pulumi is React for infrastructure

Instead of managing the infrastructure via the AWS console (easy to start, hard to manage), we will codify the infrastructure. The standard solution to this is using products such as CloudFormation or Terraform. These products are based on custom markup languages, you may have heard them referred to as “infrastructure as code”. However, that’s not accurate. There is no real “code”, instead there is “markup” either as JSON or YAML. What does that mean? It means that it’s very difficult to use programming concepts you’re familiar with. For example, refactoring a Terraform files becomes a copy’n’paste bonanza.

So how does Pulumi help? The promise is that you can write a Pulumi program in a familiar language (JS, TypeScript, Python). The Pulumi program can then be broken up, refactored, and unit tested – much like any other coding tool you’re familiar with. Declaring the infrastructure state you desire, much like you would declare React component structure you want rendered.

But how does a pulumi program look exactly? Foreshadowing is all the jazz, so why not try some of that here. Here is pulumi snippet that creates an S3 bucket called my-bucket on AWS.

Let’s get our hands dirty

Without further delay, let’s hit the road to a tech nirvana and get the answers you’ve all been looking for!

Starting with a ‘stock’ Create React App

So what’s the starting point of this journey? If you follow the create react app docs, you’ll see something like this

npx create-react-app my-app
cd my-app
npm build

This transpiles the sources and gives you a build/ directory – let’s have a look inside

$ ls build/
asset-manifest.json					logo512.png						service-worker.js
favicon.ico						manifest.json						static
index.html						precache-manifest.a6c522ff242ab9465073ffb9aae702c8.js
logo192.png						robots.txt

But what do you do with that? These are some interesting questions:

• How do you get your precious creation into the cloud?
• How to ensure that as you push updates to your app clients get the latest version?

There are some big questions there, in particular which cache directives to set for the files in build/. These settings will be super important for the browser. We’ll cover all of that later once we have the nuts and bolts ready.

Can these topics feel confusing and annoying? Hell yeah. Have you ever seen them covered in create react app documentation? Hell no.

Getting setup with Pulumi

To avoid setting up resources in AWS console by hand, we’ll use Pulumi to write little programs that setup resources on the AWS cloud. These programs are declarative and can be written in any language of your choice, so it’s very easy to do.

What’s a Pulumi program? Program: a collection of files written in your chosen programming language

Here we’ll be sticking with Typescript (consistent with create react app).

https://www.pulumi.com/docs/get-started/aws/begin/

What’s the first decision we need to make? It’s deciding where to put the Pulumi code managing our infrastructure. Let’s create a new directory ‘pulumi’, alongside the ‘build’ directory.

$ mkdir pulumi
$ ls
README.md	build		node_modules	package.json	public		pulumi		src		yarn.lock
$ cd pulumi

Then let’s login into Pulumi, here we’ll us a local file to store the state of the project. This is okay for individual work and tinkering but gets insufficient once multiple people contribute to the project.

$ pulumi login file://...

So why not get started and create a new Pulumi project? Here is the command you need to run and the expected output.

What’s a Pulumi project? Project is a directory containing a program, with metadata, so Pulumi knows how to run it

$ pulumi new aws-typescript
This command will walk you through creating a new Pulumi project.

Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.

project name: (pulumi) my-app
project description: (A minimal AWS TypeScript Pulumi program) 
Created project 'my-app'

stack name: (dev) 
Enter your passphrase to protect config/secrets: 
Re-enter your passphrase to confirm: 
Created stack 'dev'

Here is a little asciicast to show you how this step will look like.

Now we need to configure our region of choice, here we’ll opt for eu-west-1 but it doesn’t matter what you choose here (us-west-1 or any other will do just fine).

pulumi config set aws:region eu-west-1

This command also creates our first stack – called “dev” – it will hold the state of the infrastructure we maintain.

What’s a Pulumi stack? Stack is an instance of your project, each often corresponding to a different cloud environment

Well done, that’s how we setup a Pulumi and project boiler plate. Let’s create our first stack – it will hold the state of the infrastructure we maintain.

Defining an S3 bucket

Before we jump in, let’s have a look around what we got at this step. There should now be a first Pulumi program in index.ts, let’s have a look inside:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket("my-bucket", {
    acl: "public-read",
    website: {
        indexDocument: "index.html",
    },
});

// Export the name of the bucket
export const bucketName = bucket.id;

This is too simple for what we want to do eventually but good enough for now.

Let’s get this miniature to work – if there are any problems in your Pulumi config you’ll catch them now. What’s better than incremental progression, when you’re breaking new ground and trying not to get lost?

To get Pulumi to show you the available stacks (dev, production, testing), just run

$ pulumi stack ls
NAME  LAST UPDATE  RESOURCE COUNT
dev*  n/a          n/a

If you want to jump more into the Pulumi nomenclature, here is a great introduction

Creating an S3 bucket

Now we should be ready to get our first piece of infrastructure setup in Pulumi! To get Pulumi to create the stack on AWS, just run pulumi up:

$ pulumi up
Previewing update (dev):
     Type                 Name        Plan       
 +   pulumi:pulumi:Stack  my-app-dev  create     
 +   └─ aws:s3:Bucket     my-bucket   create     
 
Resources:
    + 2 to create

Do you want to perform this update? yes
Updating (dev):
     Type                 Name        Status      
 +   pulumi:pulumi:Stack  my-app-dev  created     
 +   └─ aws:s3:Bucket     my-bucket   created     
 
Outputs:
    bucketName: "my-bucket-6daefdf"

Resources:
    + 2 created

Duration: 11s

Permalink: file:///Users/jandom/.pulumi/stacks/dev.json

Pulumi says it’s all done – but can you trust it? Heading over to AWS console, you should see the bucket created and confirm it has been created.

Publishing contents to the S3 bucket

We have an S3 bucket but now let’s get the Create React App into it. How can we accomplish that? Well, we’ve got the build/ directory and we’ve got a bucket on S3. Let’s sync the contents of build with the S3 bucket using the aws s3 cp command

What’s in the newly bucket? Well, unsurprisingly, nothing.

$ aws s3 ls s3://my-bucket-f01e841

Yup, nada. So let’s get some stuff in there! What could be easier?

$ aws s3 cp build/ s3://my-bucket-f01e841 --recursive --exclude *.map
upload: build/favicon.ico to s3://my-bucket-f01e841/favicon.ico
upload: build/index.html to s3://my-bucket-f01e841/index.html  
upload: build/service-worker.js to s3://my-bucket-f01e841/service-worker.js
upload: build/robots.txt to s3://my-bucket-f01e841/robots.txt  
upload: build/manifest.json to s3://my-bucket-f01e841/manifest.json
upload: build/precache-manifest.a6c522ff242ab9465073ffb9aae702c8.js to s3://my-bucket-f01e841/precache-manifest.a6c522ff242ab9465073ffb9aae702c8.js
upload: build/asset-manifest.json to s3://my-bucket-f01e841/asset-manifest.json
upload: build/static/css/main.5f361e03.chunk.css to s3://my-bucket-f01e841/static/css/main.5f361e03.chunk.css
upload: build/logo192.png to s3://my-bucket-f01e841/logo192.png 
upload: build/logo512.png to s3://my-bucket-f01e841/logo512.png
upload: build/static/js/2.a430f49c.chunk.js.LICENSE.txt to s3://my-bucket-f01e841/static/js/2.a430f49c.chunk.js.LICENSE.txt
upload: build/static/js/main.4f4a69a4.chunk.js to s3://my-bucket-f01e841/static/js/main.4f4a69a4.chunk.js
upload: build/static/js/runtime-main.f8c5b4be.js to s3://my-bucket-f01e841/static/js/runtime-main.f8c5b4be.js
upload: build/static/media/logo.5d5d9eef.svg to s3://my-bucket-f01e841/static/media/logo.5d5d9eef.svg
upload: build/static/js/2.a430f49c.chunk.js to s3://my-bucket-f01e841/static/js/2.a430f49c.chunk.js

Now that was easy… but is that what we want? Well… Everything in build got published so that’s good news. We excluded *.map files which you may want to keep private. Also what about the caching settings used by browsers? There is only one way to find out: with the swiss-army knife of all things web, cURL

$ curl https://my-bucket-f01e841.s3-eu-west-1.amazonaws.com/index.html
<?xml version="1.0" encoding="UTF-8"?>
<Error><Code>AccessDenied</Code><Message>Access Denied</Message><RequestId>079C0D51FEE2F8E1</RequestId><HostId>FPIAUu0YGJ1XEyCTuJPdSWiAQGBLkC7ftzbraMq4FchBUo7kEv8MTjoemmXumaiyIffhTv/ikMk=</HostId></Error>

Now that’s a funny thing: the S3 bucket contents are not available to us by default. They are private. We can certainly change that!

aws s3 rm s3://my-bucket-f01e841/ --recursive

aws s3 cp build/ s3://my-bucket-f01e841 \
  --recursive \
  --exclude *.map \
  --exclude index.html \
  --cache-control max-age=31536000 \
  --acl public-read 

aws s3 cp build/index.html s3://my-bucket-f01e841/index.html \
  --metadata-directive REPLACE \
  --cache-control no-cache,no-store \
  --content-type text/html \
  --acl public-read

And with any luck, all of these files should upload to S3 with new cache-control headers. Let’s verify how things are working by requesting index.html

$ curl http://my-bucket-f01e841.s3-eu-west-1.amazonaws.com/index.html -v
...
< Cache-Control: max-age=0,no-cache,no-store,must-revalidate
...
<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="/favicon.ico"/>...

Importantly, the root page is also working (redirecting to index.html). We can verify that with cURL again

$ curl -v http://my-bucket-f01e841.s3-website-eu-west-1.amazonaws.com
* Rebuilt URL to: http://my-bucket-f01e841.s3-website-eu-west-1.amazonaws.com/
*   Trying 52.218.60.172...
* TCP_NODELAY set
* Connected to my-bucket-f01e841.s3-website-eu-west-1.amazonaws.com (52.218.60.172) port 80 (#0)
> GET / HTTP/1.1
> Host: my-bucket-f01e841.s3-website-eu-west-1.amazonaws.com
> User-Agent: curl/7.54.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< x-amz-id-2: VKg+mTQ8wGUge3GzLx9J1BN+cBUNmbQuixY95AZ4wgV4U7H9fKF3v8is1ms6tUTalGIEUMwEW+Y=
< x-amz-request-id: 1ZAT1PAWEP0MFXAR
< Date: Wed, 29 Jul 2020 19:11:31 GMT
< Cache-Control: max-age=0,no-cache,no-store,must-revalidate
< Last-Modified: Tue, 28 Jul 2020 19:57:17 GMT
< ETag: "67e4d5da5073a0ba60ce72a01c3feee4"
< Content-Type: text/html
< Content-Length: 2219
< Server: AmazonS3
< 
* Connection #0 to host my-bucket-f01e841.s3-website-eu-west-1.amazonaws.com left intact
<!doctype html><html lang="en"><head><meta charset="utf-8"/>

Caching settings

Following this StackOverflow thread, we’ll follow similar defaults https://stackoverflow.com/questions/49604821/cache-busting-with-cra-react

Using Cache-Control: max-age=31536000 for your build/static assets, and Cache-Control: no-cache for everything else is a safe and effective starting point that ensures your user’s browser will always check for an updated index.html file, and will cache all of the build/static files for one year. Note that you can use the one year expiration on build/static safely because the file contents hash is embedded into the filename.

This is a much wider topic and we’ll only stick to the simplest solution. Searching around for best practices might give you some ideas for what to do depending on your situation.

Conclusions

That brings us to a conclusion, we have a rudimentary setup for hosting a Create React App. With a single bucket we can serve contents using HTTP requests. This is a far cry from what we want, it’s hard to expect users to access your website by the bucket URL! What’s next in this series? Well, we need to connect the S3 bucket to a Route53 record. Then, some considerations about load and caching will follow, showing how CloudFront can be used to cache the contents of your S3 bucket. But that’ll all come later!

What’s next?

This was a simple intro to publishing a Create React App to AWS S3 via Pulumi. It’s rudimentary and not suitable for a production-level workload. Which components to add next? Checkout the second blog post in the series on how to connect Route 53 with our Create React App.

Credits

Big big thanks to my colleagues

• Charlie “Cloud Wizard” Shepherd
• Giulio Cirnigliaro

For helping me review and improve this post.

How do you know you’re old in tech? The tell-tale sign is that your new projects and up being about saving your old projects. How old? Like DECADES old. But I’m getting ahead of myself here… let’s introduce our characters.

How did we get here?

When I was a wee little lad, my first encounter with programming was as a biochemistry student, staying over the summer at Oxford. Funded by Wellcome Trust, that summer thrust me into the tech trajectory that I stayed on for over 10 years now. What was the mission? Researchers typically stored the parameter files on random FTP servers or shared them via email. Our task was to build a database of lipid parameters for molecular dynamics simulation.

Having no prior coding experience, what could you expect from a student? The product was a database called Lipidbook, a simple CMS-like app for researchers to upload these parameters and link them to their papers (for proper citation by their peer) . The summer ended, a paper got written up and that’s it. End of story, right? That’s the reality it in terms of science sustainability for software development: there often is funding to develop new tools but once it’s out there… the funding situations becomes more “dire”.

The troubles begin

With the Lipidbook published the researcher started to publish stuff to it. Not like millions of files but enough to make the tool valuable to the community. People not only started depositing but also citing the paper. So far it’s my 2nd most cited paper of all time: a software tool paper that overshadowed other “actual” science papers.

Remarkably, the system held with little human intervention. For nearly a decade the website run of a mac mini in a cupboard in Oxford. Yeah, sometimes it needed a reboot but beyond that, smooth sailing! Everything was kind of “MVP” (minimal viable product) with bash scripts and cron jobs running support functions. The real crisis began when the people running the hardware moved out of the lab. Without anybody to occasionally press the reset button, or without any SSH access, we were stranded. The website was down for days, then weeks then months. People kept messaging us but we simply didn’t have the time.

How can we fix this?

The impetus came from Phil Stansfeld and Oliver Beckstein, both mentors of mine, who equally facilitated “good decisions” and suppressed “questionable choices”. What should we do to get this service up and running without a tremendous amount of work? Where should we host it? Typically, academia prefers to host things in-house, rather than on AWS. Why is that strange choice, you might ask? Comes down to the funding model: once you get your grant money in science, you can buy a lot of hardware, but running that hardware will largely be done by the university. Even with your grant money running low, you don’t have to cut down on usage. It’s really unfortunate that funding bodies haven’t changed their model to include year-long support costs. That wouldn’t be the case with AWS, billed per hour, as you can imagine. Despite that, Oliver wanted to push ahead with AWS. This project is an interesting example of using AWS in a cost-efficient way for science infrastructure. But how do we yank Lipidbook from a single MacMini to the cloud? Enter Pulumi and AWS.

AWS needs no introduction, it’s the mother-of-clouds, the Amazon Web Services. Pulumi is tool that allows you to manipulate and manage AWS resources via declarative programs that specify the desired end-state of your infrastructure.

Assembling a web app

Will this be a primer on Pulumi or AWS? Probably not but what I’ll attempt to do here is to outline how these pieces fit together. What’s the first thing that comes to mind? We’ll probably need an EC2 instance on AWS to host the webserver and all. But let’s take a step back and start by putting together our networking layer, and the boilerplate on which the app will stand.

BEWARE

All examples given here will be in Typescript, the programming language that is the love child of the web in 2020. Pulumi comes with a variety of other SDKs, including Python, so you’re free to choose between them.

Networking layer

import * as awsx from "@pulumi/awsx";

const vpc = new awsx.ec2.Vpc("custom", {
    numberOfAvailabilityZones: 1,
});

This will create our VPC with public and private subnets. VPC will ensure the isolation of all the services inside. Single availabilility zone to keep the costs super-duper low.

Backup bucket

What’s the next useful thing to add? The Lipidbook database needs to be backed up regularly, so let’s create an S3 bucket to hold the backups

import * as aws from "@pulumi/aws";

const backupBucket = new aws.s3.Bucket("backup-bucket", {
    bucket: config.backupBucket,
    serverSideEncryptionConfiguration: {
        rule: {
            applyServerSideEncryptionByDefault: {
                sseAlgorithm: 'AES256',
            },
        },
    },
});

Notice that the bucket contents get encrypted, because why not!

SecurityGroups

The EC2 instance needs to know on which ports to accept the connections, we probably want to keep 443 and 80 ports open. To define that behavior, we create a SecurityGroup

const securityGroup = new aws.ec2.SecurityGroup(
    "security-group",
    createSecurityGroupArgs(config)
);

The createSecurityGroupArgs is a helper function to create the SecurityGroup configuration that you need. The details are left to the eager reader!

KeyPair access

Next, we’ll need a KeyPair to access our EC2 instance via SSH and do servicing/maintenance on it.

$ ssh-keygen -t rsa -f rsa

We then import the publicKey part

const keyPair = new aws.ec2.KeyPair(
    "key-pair", {
        keyName: `lipidbook-${config.environmentName}`,
        publicKey: config.publicKey,
});

Amazon Machine Image

Lastly, we need to get an amazon machine image for our Ubuntu version up and running

const size = "t1.micro";
const ami = aws.getAmi({
    filters: [{
        name: "name",
        values: ["ubuntu/images/hvm-ssd/ubuntu-trusty-****"],
    }],
    owners: ["099720109477"], # canonical
});

Getting the webserver

All the pieces are assembled now: we have the VPC for networking, we have a security group and the machine image. Let’s get the final piece assembled!

const server = new aws.ec2.Instance("webserver-www",
    createEC2Args(config, vpc, size, securityGroup, ami),
);

Now obviously this is just a blank EC2 box. It still needs to be provisioned to run our app. This is beyond the scope of this post but we’ve used Hashicorps Vagrant for that.

Elastic IP

The EC2 instance we’ve created does have a public IP but it keeps changing between each machine spin-up. To get our DNS setting working we’ll need an elastic IP.

const elasticIp = new aws.ec2.Eip(
    "elastic-ip",
    {
        instance: server.id,
    }
);

No matter what the instance public IP is, this ElasticIP will not change and can be used to configure the DNS.

DNS Configuration

This is the last piece. Again, I’m omitting the details of createARecordArgs and createCNAMERecordArgs. There are obviously important details… But let’s allow the big picture to take priority.

const record = new aws.route53.Record(
    "record",
    createARecordArgs(config.targetDomain, elasticIp),
);

const aliasRecord = new aws.route53.Record(
    "alias-record",
    createCNAMERecordArgs(config.targetDomain, config.aliasDomain),
);

Future work

There is a number of things here that I’m not happy about and could be improved:

1. With the app we’re running, given it’s age, I see no incremental migration path. It’s a re-write and these don’t get funded.

2. The EC2 instance should ideally be in a private subnet, all HTTP requests should go via a LoadBalancer, and direct access should be possible only via SSH hopping over a bastion box.

3. The database is hosted directly on the EC2 instance, ideally, it should run on its own RDS instance. So that when the EC2 goes down the database is not lost.

Closing

Amazon Web Services model has not been super popular in academia. The reasons are probably related to funding structure and grants. However, for running scientific infrastructure that often needs to be maintained for years, it is a suitable choice. The entire cost for us to run this operation is 35$ / month, aka peanuts. Using tools such a pulumi, the infrastructure can be quickly spun-up and modified. The pulumi program presented here was written in typescript but SDKs for most popular languages exist (including Python). The scientific community could run many more pieces of infrastructure for less, in a more maintainable fashion using cloud providers and declarative infrastructure.