Pulumi Blog: Fullstack

Test-Driven Infrastructure Development with Pulumi and Jest

Christian Nunciato — Mon, 13 Jun 2022 00:00:00 +0000

When I was a kid growing up in Southern California, there was a phone number you could call to find out what time it was. It was a local number, 853-1212 (easy to remember as the arrangement of the numbers on the keypad made a capital T), and I used it all the time, to set my watch, adjust the alarm clock, fix the display on the VCR. I don’t recall the last time I used it, probably sometime in the mid ’90s, but I do remember clearly the sound of the voice at the other end of the line.

Services like these were called speaking clocks (although I never called them that; to me, it was just “calling Time”), and they date back to the early 1930s or so. In the U.S., most were powered by a machine called an Audichron that used mechanical drums to play back the time of day, often with a little advertisement or the current temperature to go along with it.

By the mid-2000s, though, most of these locally run services had been shut down — by then, we had clocks baked into our phones — and today, only a handful of Audichrons survive. Thanks to the National Institute of Standards and Technology, however, you can still call a phone number to get the time, and while the voice might not be the same, and long distance rates will apply, it’s definitely there, and you can use it. So on the off chance you happen to find yourself with no idea what time it is and only an analog phone line in reach, fear not — old-school telephone tech has your back. For now. Assuming you remember the number.

Recalling all this stuff did make me wonder, though, what a more modern version of a speaking clock might look like. So in this post, we’re going to build one ourselves. We won’t use an actual phone number, but we will use Pulumi and AWS — and because we want to do it right, we’ll take a test-driven approach to developing the infrastructure with Jest, the JavaScript testing framework. We’ll use TypeScript and Node.js for everything, focus on unit tests, and when we’re done, we’ll have a single, serverless, browser-friendly HTTPS endpoint that returns an MP3 audio stream that speaks the current time.

Let’s get started.

Sketching it out

The first thing we’ll need is a runtime environment — someplace to run some server-side JavaScript that can render and deliver an audio file. Until recently, the easiest way to get an HTTP endpoint up and running on AWS has generally been with AWS Lambda and API Gateway, using Lambda to run the requisite code and API Gateway to expose the Lambda to the internet. Pulumi Crosswalk actually makes this really easy, too — but with the release of AWS Lambda Function URLs this April, we now have another option, one that doesn’t need API Gateway at all.

A Lambda Function URL is just what it sounds like: a URL that exposes a Lambda function. Specifically, it’s an AWS cloud resource that consists of a few properties that tell AWS whether to allow anonymous access to the function or to protect it with AWS IAM, and optionally, you can also provide a few cross-origin resource-sharing (CORS) rules to provide (or restrict) access by websites running on other domains.

For an app like this one, a Function URL is a good fit, as it’s simple, quick to deploy (and update), and it gives us all the control we need to get the job done. Architecturally, then, our little app will look something like this:

That about covers the infrastructure — but what about the sound?

As it happens, Google Translate offers a publicly accessible text-to-speech API that can, as long as you don’t overuse it, render a string to MP3 audio. We can use that API to generate the time-of-day message, tack the sound of a beep onto the end of it (for maximum nostalgic effect), and voilà: instant, infinitely scalable, cloud-native speaking clock.

Plan in place, we can kick things off by creating a new Pulumi project.

Create a new TypeScript project

Start by creating a new AWS TypeScript project in the usual way:

$ mkdir audichron-2022 && cd audichron-2022
$ pulumi new aws-typescript

Step through the prompts to create a new stack (you’ll only need one stack for this project), and when the new-project wizard completes, clear out the contents of index.ts entirely, as we’ll be building this program entirely from the ground up.

Install and configure Jest

Since we’re working with TypeScript, we can use ts-jest, which conveniently brings Jest along for the ride:

$ npm install ts-jest @types/jest --save-dev

Jest requires a bit of configuration, so add a new file at the root of the project, called jest.config.ts, with the following code:

import type { Config } from "@jest/types";

const config: Config.InitialOptions = {
 preset: "ts-jest",
};

export default config;

With Jest now installed and configured, and its helpers (like describe and expect) declared globally, you can create a new spec file to hold your tests. Add another file at the root of the project called index.spec.ts, and give it the following temporary content:

import "jest";

describe("My speaking clock", () => {
 it ("works", () => {
 expect(true).toBeTruthy;
 });
});

Lastly, in package.json, add a scripts block with a helper to make running the tests a little easier:

{
 "name": "audichron-2022",
 "devDependencies": {
 "@types/node": "^14",
 "ts-jest": "^28.0.3"
 },
 ...
 "scripts": {
 "test": "jest"
 }
}

Now run the tests, just to make sure you’ve got everything wired up correctly. If all goes well, you should see that the temporary spec we just added happily passes:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 ✓ works

With that, it’s time to get to start writing some real tests.

Start with some failing tests

As devoted practitioners of test-driven development, we’re going to start by writing some unit tests — specifically, some failing unit tests that we can fix by writing the Pulumi code to make them pass.

Recall that our design requires just two cloud resources: a Lambda function and a Lambda function URL. For the function itself, we’ll use the high-level aws.lambda.CallbackFunction resource, one of my favorites for managing for Lambdas because it requires only one property: an inline JavaScript function to handle the event that triggers the Lambda.

For the URL resource — the eventual triggerer of that event — you’ll use an aws.lambda.FunctionURL configured to make the Lambda publicly accessible (i.e., available to anyone on the internet) and embeddable on any domain, making it easy, for example, to embed the URL as the src attribute of an HTML5 audio element.

So to get things going, we’ll need to:

Configure Pulumi to mock AWS resources. We’re writing unit tests, after all, and we want them to be fast, so we’ll need to prevent those tests from provisioning any real cloud infrastructure.
Import your Pulumi resource declarations — the function and the function URL — into index.spec.ts so you can reference them in tests.

In that light, replace the contents of index.spec.ts with the following code, which, after some setup to switch Pulumi into unit-testing mode, contains just one test: a check to make sure that the function URL is configured with the right authorizationType. I’ve included some comments to help explain what each line is doing:

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

describe("My speaking clock", () => {

 // Define the infra variable as a type whose shape matches that of the
 // to-be-defined resources module.
 // https://www.typescriptlang.org/docs/handbook/2/typeof-types.html
 let infra: typeof import("./resources");

 beforeAll(() => {

 // Put Pulumi in unit-test mode, mocking all calls to cloud-provider APIs.
 pulumi.runtime.setMocks({

 // Mock requests to provision cloud resources and return a canned response.
 newResource: (args: pulumi.runtime.MockResourceArgs): {id: string, state: any} => {

 // Here, we're returning a same-shaped object for all resource types.
 // We could, however, use the arguments passed into this function to
 // customize the mocked-out properties of a particular resource based
 // on its type. See the unit-testing docs for details:
 // https://www.pulumi.com/docs/iac/concepts/testing/unit
 return {
 id: `${args.name}-id`,
 state: args.inputs,
 };
 },

 // Mock function calls and return whatever input properties were provided.
 call: (args: pulumi.runtime.MockCallArgs) => {
 return args.inputs;
 },
 });
 });

 beforeEach(async () => {

 // Dynamically import the resources module.
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports
 infra = await import("./resources");
 });

 describe("function URL", () => {

 it("is publicly accessible", (done) => {
 infra.timeURL.authorizationType.apply(authType => {
 try {
 expect(authType).toBe("NONE");
 done();
 } catch (err) {
 done(err);
 }
 });
 });
 });
});

We can’t quite run these tests just yet, though, as they rely on a module called resources that we haven’t yet defined. Let’s do that now by creating a new file, resources.ts, containing some stubs for the cloud resources we’ve elected to use:

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

export const timeFunction = new aws.lambda.CallbackFunction("time-function", {
 callback: () => {
 // Leave the callback implementation empty for now.
 },
});

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "", // Leave this empty, too. (We want our first test to fail.)
});

Now run the tests, and you should see that the public-accessibility test fails — which shouldn’t be surprising, as we haven’t yet supplied an acceptable value:

$ npm test

FAIL ./index.spec.ts
 My speaking clock
 function URL
 ✕ is publicly accessible

 ● My speaking clock › function URL › is publicly accessible

 expect(received).toBe(expected) // Object.is equality

 Expected: "NONE"
 Received: ""

Now let’s turn that sad-looking ❌ into a ✅.

Make the tests pass

Update the FunctionUrl resource to change its authorizationType input to NONE (meaning for anonymous access, no authorization required):

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
- authorizationType: "",
+ authorizationType: "NONE",
});

Once you do that, you should be able to run the test suite again, and this time, see it pass:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible

Excellent: you’re now well on your way to writing more tests with Jest — and we’ll do that in a moment. But first, let’s digress momentarily to explore a few other ways of writing Jest specs with Pulumi.

Tidy up the specs

If you’ve written JavaScript tests before, particularly with tools like Jest, Jasmine, and Mocha, there’s a good chance you’ve gotten used to writing those tests in a particular way. And if you’re like me, you might’ve raised a bit of an eyebrow when you saw how that first test was written. Here it is again, this time with comments that capture the questions I might’ve had myself if I were seeing this code for the first time:

it("is publicly accessible", (done) => {
 infra.timeURL.authorizationType.apply(auth => { // Why do I have to use .apply() here?
 try { // What happens if I don't try/catch?
 expect(auth).toBe("NONE"); // Is it possible to use expect() by itself?
 done(); // Do I have to call done()? What if I don't?
 } catch (err) { // How can I make these tests more readable?
 done(err); // Is all of this code necessary?
 }
 });
});

This is a perfectly valid test, of course; we know because we just ran it. Still, you might wonder, especially since we’re only checking one property, whether this test might be written a bit more concisely — something more like this, maybe:

it("is publicly accessible", () => {
 expect(infra.timeURL.authorizationType).toBe("NONE"); // Alas, nope.
});

The main reason is the asynchronous nature of the objects we’re testing. An aws.lambda.FunctionUrl, after all, isn’t just a plain ol’ JavaScript object — it’s a Pulumi CustomResource, a representation of an eventual resource running in the cloud, with properties that may not be known until sometime after the resource has been deployed. While it’s true we provided authorizationType as a regular JavaScript string, by the time we attempt to read it in the test, it’s been transformed into a pulumi.Output<string> — an asynchronous value, like a promise, that has to be unwrapped with a call to apply() before it can be read.

However, just adding apply and calling expect from within its callback doesn’t quite work, either:

it("is publicly accessible", () => {
 infra.timeURL.authorizationType.apply(authType => {
 expect(authType).toBe("NONE"); // Also nope.
 });
});

Although that might not be obvious at first, since on the surface, the test appears to pass:

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible

It isn’t until you force the test to fail that it becomes clearer something’s gone sideways. Try changing the expected authorizationType to something other than NONE and you’ll see what I mean:

$ npm test

PASS ./index.spec.ts
 My time app
 function URL
 ✓ is publicly accessible

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function
without a catch block, or by rejecting a promise which was not handled with .catch(). The promise
rejected with the reason "Error: expect(received).toBe(expected) // Object.is equality

Expected: "AWS_IAM"
Received: "NONE"".] {
 code: 'ERR_UNHANDLED_REJECTION'
}

All is not lost, though. We do have other options, and that UnhandledPromiseRejection offers a bit of a clue.

Turn outputs into promises

Jest actually has built-in support for writing asynchronous tests with promises, and there are a couple of ways you can write specs that use them:

Have the function passed to it (or its alias, test) return a promise containing your expectation
Pass an async function to it and await the promise in the usual way

There’s only one problem: pulumi.Outputs may indeed be promise-like, but they aren’t actual promises.

They can, however, be wrapped in promises pretty easily. I like the way Pulumi community member @aviflax handled this with a little utility function that wraps the Output and preserves the type of its underlying value. Here’s that function, followed by a couple of examples that use it:

// Convert a pulumi.Output to a promise of the same type.
function promiseOf<T>(output: pulumi.Output<T>): Promise<T> {
 return new Promise(resolve => output.apply(resolve));
}

// Our test, rewritten to have it() return a Promise<string>.
it("is publicly accessible", () => {
 return promiseOf(infra.timeURL.authorizationType).then(authType => {
 expect(authType).toBe("NONE");
 });
});

// The same test, rewritten to use async/await.
it("is publicly accessible", async () => { // <-- Don't miss that async!
 const authType = await promiseOf(infra.timeURL.authorizationType);
 expect(authType).toBe("NONE");
});

Either approach works equally well, but I’m slightly more partial to the latter for its conciseness. So for now, update index.spec.ts to add the promiseOf helper and adjust the test accordingly, then run the suite one more time to make sure all’s well:

// ...

// Convert a pulumi.Output to a promise of the same type.
function promiseOf<T>(output: pulumi.Output<T>): Promise<T> {
 return new Promise(resolve => output.apply(resolve));
}

describe("My speaking clock", () => {
 // ...

 describe("function URL", () => {

 it("is publicly accessible", async () => {
 const authType = await promiseOf(infra.timeURL.authorizationType);
 expect(authType).toBe("NONE");
 });
 });
});

Assuming you’re back in ✅ territory, let’s move on so we can finish things off.

Finish the app

We’re in good shape: we’ve got scaffolding for our Jest-powered unit tests and we’re generally happy with how they look, so it’s time to round out the rest of the app and its tests so we can deploy. We’ll go through this last part briskly, as we’ve covered most of the important stuff at this point, and pause only briefly to point out what’s important as we go.

Here’s the plan:

We’ll add one more test to make sure the function URL is CORS-friendly
We’ll add another test to make sure the URL resource is bound to the right Lambda function
We’ll add the Lambda code to generate and return the audio file
We’ll deploy, and bask in the warm glow of nostalgia

Let’s get to it.

Add the remaining tests

To index.spec.ts, add two more tests, one to ensure the function is accessible to browsers running on any domain, the other to verify the function URL resource is exposing the right function (if we didn’t, it’d be easy to change that reference by mistake and accidentally expose the wrong function):

describe("My speaking clock", () => {
 // ...

 describe("function URL", () => {
 // ...

 it("is CORS-friendly", async () => {
 const authType = await promiseOf(infra.timeURL.cors);
 expect(authType).toEqual({
 allowOrigins: ["*"],
 allowMethods: ["GET"],
 });
 });

 it("is bound to the right Lambda function", async () => {
 const timeFuncName = await promiseOf(infra.timeFunction.name);
 const timeURLFunc = await promiseOf(infra.timeURL.functionName);
 expect(timeFuncName).toEqual(timeURLFunc);
 });
 });
});

Run the tests, and you should see one failure:

$ npm test

FAIL ./index.spec.ts (14.256 s)
 My speaking clock
 function URL
 ✓ is publicly accessible (3022 ms)
 ✕ is CORS-friendly (3 ms)
 ✓ is bound to the right Lambda function (1 ms)

 Expected: {"allowMethods": ["GET"], "allowOrigins": ["*"]}
 Received: undefined

Tests: 1 failed, 2 passed, 3 total

A quick addition to the FunctionUrl in resources.ts should get you to green:

// ...
export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "NONE",
+ cors: {
+ allowOrigins: ["*"],
+ allowMethods: ["GET"],
+ },
});

$ npm test

PASS ./index.spec.ts
 My speaking clock
 function URL
 ✓ is publicly accessible
 ✓ is CORS-friendly
 ✓ is bound to the right Lambda function

Tests: 3 passed, 3 total

That’s it for the tests! Now for the final additions.

Produce the audio message

The last thing we’ll need to do is render some audio. For this, we’ll need to communicate with Google Translate, our text-to-speech provider of choice, and that means we’ll need an HTTP client. I generally like node-fetch, so let’s go with that:

npm install --save node-fetch@2

Now, finish the program by importing node-fetch into resources.ts, adding a function to produce a speech-friendly string indicating the current time and updating the CallbackFunction’s callback property to send the string to Google Translate to produce the desired result. Here’s the complete file, with comments, for reference:

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

const fetch = require("node-fetch");

// Convert the current time into a speech-friendly string.
export function getSpeechText() {
 const now = new Date();
 now.setSeconds(now.getSeconds() + 6);

 const local = new Date(now.toLocaleString("en-US", { timeZone: "America/Los_Angeles" }));
 const localHour = local.getHours();
 const localMinute = local.getMinutes();
 const h = localHour > 12 ? localHour - 12 : localHour;
 const m = localMinute < 10 ? `oh ${localMinute}` : localMinute; // So 2:03 -> "two-oh-three"
 const s = local.getSeconds();

 return `At the tone, the time will be ${h} ${m}. And ${s} seconds.`;
}

export const timeFunction = new aws.lambda.CallbackFunction("time-function", {

 // Update the Lambda callback body to convert the current time into an MP3 file.
 callback: async () => {
 const text = getSpeechText();
 const speechURL = `https://translate.google.com/translate_tts?ie=UTF-8&q=${encodeURIComponent(text)}&textLen=${text.length}&tl=en&client=tw-ob`;
 const beepURL = "https://www.pulumi.com/uploads/beep.mp3";
 const ttsResponse = await fetch(speechURL);
 const beepResponse = await fetch(beepURL);
 const speech = await ttsResponse.arrayBuffer();
 const beep = await beepResponse.arrayBuffer();

 // Tack a beep onto the end of the audio returned from Google Translate, then
 // render the whole thing as a base-64 encoded string.
 const body = Buffer.concat([Buffer.from(speech), Buffer.from(beep)]).toString("base64");

 // Return an appropriately shaped HTTP response.
 return {
 body,
 headers: { "Content-Type": "audio/mpeg" },
 isBase64Encoded: true,
 statusCode: 200,
 };
 },
});

export const timeURL = new aws.lambda.FunctionUrl("time-url", {
 functionName: timeFunction.name,
 authorizationType: "NONE",
 cors: {
 allowOrigins: ["*"],
 allowMethods: ["GET"],
 },
});

// Export the public URL of our shiny new service.
export const audioURL = timeURL.functionUrl;

Finally, open index.ts (which should still be empty) and add a couple of lines to import the resources module and export the function URL as a Pulumi stack output:

import "./resources";

export { audioURL } from "./resources";

And that’s it. We’re ready to deploy.

Deploy the service

Doublecheck your AWS credentials are configured, then deploy the new service with a single pulumi up:

$ pulumi up

...
Updating (dev)

View Live: https://app.pulumi.com/cnunciato/audichron-2022/dev/updates/1

 Type Name Status
 + pulumi:pulumi:Stack audichron-2022-dev created
 + ├─ aws:iam:Role time-function created
 + ├─ aws:lambda:Function time-function created
 + ├─ aws:iam:RolePolicyAttachment time-function-7cd09230 created
 + ├─ aws:iam:RolePolicyAttachment time-function-a1de8170 created
 + ├─ aws:iam:RolePolicyAttachment time-function-1b4caae3 created
 + ├─ aws:iam:RolePolicyAttachment time-function-019020e7 created
 + ├─ aws:iam:RolePolicyAttachment time-function-4aaabb8e created
 + ├─ aws:iam:RolePolicyAttachment time-function-74d12784 created
 + ├─ aws:iam:RolePolicyAttachment time-function-e1a3786d created
 + ├─ aws:iam:RolePolicyAttachment time-function-6c156834 created
 + ├─ aws:iam:RolePolicyAttachment time-function-b5aeb6b6 created
 + └─ aws:lambda:FunctionUrl time-url created

Outputs:
 audioURL: "https://52rjmmybwfwcud3nxxhosznpum0cycbw.lambda-url.us-west-2.on.aws/"

Resources:
 + 13 created

Duration: 20s

When the update completes, open the URL in your browser of choice, and you should hear the message you’ve been waiting for — one that might even make Pat Fleet proud:

$ open $(pulumi stack output audioURL)

When you’re ready, you can tear everything down with a pulumi destroy.

Wrapping up

Beyond just having a nifty (and admittedly rather silly) new way to tell time, you should have a much better sense at this point of how you can use Pulumi with Jest to write better, safer infrastructure code.

From here, there’s a bunch more you might think about next: writing more tests to cover the code we just added, exploring some additional flavors of testing in the docs, or having a look at a few examples. You’ll find the full source for this walkthrough up on GitHub as well.

Happy testing!

Deploy MERN Stack on DigitalOcean with Pulumi [Guide]

Christian Nunciato — Fri, 11 Mar 2022 00:00:00 +0000

As a developer, I get lots of ideas for web apps—little things, mostly: nifty ways to keep track of my kids’ allowances, habit trackers, shopping lists. Most of them, however, never see the light of day, and not just because I’m lazy; I also tend to get hung up trying to decide what to use for the technology stack.

And as a JavaScript developer, I certainly have options—too many, in fact, and that’s part of the problem. Having roughly a hundred and fifty million libraries and frameworks to choose from is definitely better than having none, but at the same time, all that choice can make the actual choosing rather difficult. Which is why, when I just want to get something done, I’ll often reach for a combination of tools known as the MERN stack.

MERN-stack apps are three-tier web apps built with MongoDB, Express, React, and Node.js. You can read all about them in the MongoDB docs, but the gist is that they allow you use one language—JavaScript (or TypeScript, if you like)—to manage all three layers of the application stack: the front end as a single-page app built statically with React, the back end as a REST API managed with Express, and the database as a collection of JSON-like documents with MongoDB. MERN might not always the right tool for the job, but for the kinds of apps I tend to find myself building, it generally works out pretty well.

Still, once I’m finished building my app, I’m often faced with a whole other problem: figuring out how to get the app off of my laptop and onto the web.

The cloud hasn’t made this an easy task for developers. Choosing a cloud provider, deciding which resources to use (and how to use them), setting up networking, debugging permissions, navigating billing, and all the rest, can be overwhelming—and that’s before you’ve given a single thought to anything having to do with automation or infrastructure as code. What we want, I think, is to be able to focus on our apps, and when we’re ready to ship, push our code to a repository and wait patiently for a URL to emerge that we can paste into a browser and have everything just work.

Which is why I was so delighted when I discovered DigitalOcean’s App Platform.

If you’ve used DigitalOcean before, you know it’s all about making infrastructure more accessible to developers. What you may not know, though, or at least I didn’t myself until recently, is that you can do a lot more with DigitalOcean than just virtual machines. A fairly new, fully-managed platform service (think Heroku), App Platform gives you a set of high-level abstractions built to align with the tiers of a typical web application, which means you can focus on what you care about most—your app—and leave the infrastructure and its management to someone else. It’s a compelling option for anyone looking to deploy and manage any web application (MERN or otherwise), and as you’ll see, with Pulumi and a little bit of code, you can easily do so without ever having to leave the comfort of your IDE.

So let’s build ourselves a MERN app and deploy it on DigitalOcean with Pulumi. Given the goal is to focus primarily on the infrastructure and how to code it, we’ll start with a pre-baked web application (a simple grocery list), and we’ll map its tiers to App Platform constructs and wire everything up with Pulumi.

First steps: setting up

The code for this walkthrough is available as a template repository on GitHub, so if you want to follow along (and you should!), you should grab a copy of your own to work with by forking the repository or creating a new one from the template. Once you’ve done that, you should also:

Clone the repository to your local machine.
Install Pulumi and Node.js.
Sign into DigitalOcean and obtain a personal access token with read-write permissions.
Grant DigitalOcean access to your GitHub repository by visiting the Apps page, choosing Create App, and following the steps to install DigitalOcean’s GitHub app.
Optionally, if you’d like to develop the application locally as well, install and configure MongoDB Community Edition.

One thing to note: Since we’ll be provisioning real DigitalOcean resources, there’s a chance you could incur a slight cost for what you use. However, as we’ll be using the least expensive plan settings available, and tearing everything down when we’re through, that cost shouldn’t amount to more than a few pennies or so.

Let’s get started.

Cloning and inspecting the repository

Once you’ve cloned your copy of the template repository and navigated to the root, you’ll see a couple of files and folders that look something like this:

├── frontend
├── backend
└── package.json

The frontend folder contains the React application, and its job is to render the list of groceries and give you something to interact with (to add items, check them off, delete them, and so on). The scaffolding for the app was generated with a tool called Vite, and all of its logic—form fields, click handlers, API calls, etc.—is contained in src/App.tsx.

The backend folder contains the Express application that defines the REST API. It sets up four API routes to handle the CRUD operations you’d expect in an app like this one:

GET /api/items fetches all items from the database and returns them as a JSON array.
POST /api/items accepts a new item and writes it to the database.
PUT /api/items/:id updates an existing item (to toggle its checked/unchecked status).
DELETE /api/items/:id deletes an item from the database.

The back end supports three configurable properties as well, all of which are exposed as optional environment variables:

BACKEND_SERVICE_PORT, which defaults to 8000
BACKEND_ROUTE_PREFIX, which defaults to /api
DATABASE_URL, which defaults to mongodb://127.0.0.1 for local development

Running the application locally (optional)

You don’t have to do this, but if you’d like to, here’s how. After installing MongoDB and starting the service (which should be listening by default on port 27107), you can install all front-end and back-end dependencies and start the development server:

$ npm install
$ npm start

With the development server running, you can browse to http://localhost:3000 and see the app:

The front-end and back-end dev servers are set up to compile your TypeScript to JavaScript automatically, and the front-end server is configured to proxy the back-end service (which runs at http://localhost:8000) at a root-relative path of /api. Proxying the API in this way lets you avoid having to wrestle with CORS-related issues, and as you’ll see when we deploy to DigitalOcean later, App Platform conveniently supports the same configuration out of the box.

Try adding a few items and marking them off, just to make sure everything’s working as expected. If you’ve got a MongoDB client installed as well—I generally use MongoDB Compass—you should be able to find the grocery-list database and see the items collection filling up with delicious foods:

Now let’s have a look at how to go about deploying this stuff.

Charting a course

Earlier I mentioned that every cloud provider handles application deployment a little differently, sometimes in multiple ways, and that’s true for DigitalOcean as well. You could deploy the front end as a DigitalOcean Space, or both the front end and back end (and even the database) as a DigitalOcean Droplet. But given the shape of this application, the best fit is really is App Platform, for several reasons.

One is that because App Platform apps are comprised of these high-level components—abstractions like static site, service, and database—it’s pretty much purpose-built for an application like this one, and DigitalOcean customizes the deployment of each component based on its type. Static websites are distributed and cached on DigitalOcean’s CDN, services are packaged and delivered as containers (with its Kubernetes platform), and databases are deployed as configurable managed services. All of this means you’re not only able to stay focused on the application itself, but you’re able to scale each one of these components up or down however you like, and even delegate your front-end and back-end build processes to DigitalOcean to be handled in response to commits on one or more external Git repositories.

App Platform apps can be configured in one of two ways: manually, by configuring their components individually in the DigitalOcean web console, or programmatically, in the form of an App Platform spec, a JSON document submitted over DigitalOcean’s REST API. In our case, we’ll indirectly go the latter route, using Pulumi with the DigitalOcean provider package to define an app spec comprised of three components:

A staticSite component mapped to the frontend folder
A service component mapped to the backend folder
A database component mapped to a managed MongoDB cluster (which we’ll also configure to be accessible only by the service component)

And once deployed, it’ll all be available at a single DigitalOcean-provided URL.

Let’s begin by creating new Pulumi project.

Creating the project

In the root of the repository, make a new folder called infra, change to it, then run pulumi new using the digitalocean project template:

$ mkdir infra && cd infra
$ pulumi new digitalocean-typescript

$ mkdir infra && cd infra
$ pulumi new digitalocean-python

At the prompts, use the following values:

For project name, use grocery-list
For description, use Deploying a MERN-stack app on DigitalOcean
For stack name, use dev, the default

When the command completes, you’ll have a new Pulumi stack, but you’ll still have a few things to configure. For one, the Pulumi DigitalOcean provider needs to be configured to communicate with DigitalOcean on your behalf (to provision your app and its various resources). For this, you can use the access token you obtained earlier from the DigitalOcean console, and you can apply it by setting a single environment variable:

$ export DIGITALOCEAN_TOKEN="your-access-token"

Also, since one of our goals is to have App Platform deploy automatically on every GitHub commit, you’ll need to tell DigitalOcean where to find the source code for your front- and back-end components. You could bake these settings right into the Pulumi program itself, but it’d be better to apply them as stack-specific configuration settings, as that’d let you deploy to different stacks later (say, in CI) based on the branch of the commit. Everyone does this a little differently, so for now, let’s configure the currently selected stack (which should be dev) to use the default branch of your GitHub repository:

$ pulumi config set repo "your-github-org/your-github-repo" # e.g., cnunciato/fullstack-pulumi-mern-digitalocean
$ pulumi config set branch "your-main-branch" # e.g., main

With these values in place, you’re ready to start writing the program.

App Platform also supports GitLab and other Git-based repositories as well. See the App Specification docs for details.

Writing the program

In your IDE of choice, open index.js index.ts main.py main.go Program.cs Program.fs Program.vb App.java Pulumi.yaml main.tf and replace the sample code with the following lines to import the Pulumi and DigitalOcean SDKs and the configuration values you just set, and add a line to specify the DigitalOcean region to deploy into:

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

// Our stack-specific configuration.
const config = new pulumi.Config();
const repo = config.require("repo");
const branch = config.require("branch");

// The DigitalOcean region to deploy into.
const region = digitalocean.Region.SFO3;

import pulumi
import pulumi_digitalocean as digitalocean

# Our stack-specific configuration.
config = pulumi.Config()
repo = config.require("repo")
branch = config.require("branch")

# The DigitalOcean region to deploy into.
region = digitalocean.Region.SFO3

Next, add a few lines to declare the managed MongoDB cluster. We’ll use just one node for now—additional replica nodes can easily be added later by increasing the nodeCount value—and go with the least expensive performance settings:

// ...

// Our MongoDB cluster (currently just one node).
const cluster = new digitalocean.DatabaseCluster("cluster", {
 engine: "mongodb",
 version: "5",
 region,
 size: digitalocean.DatabaseSlug.DB_1VPCU1GB,
 nodeCount: 1,
});

// The database we'll use for our grocery list.
const db = new digitalocean.DatabaseDb("db", {
 name: "grocery-list",
 clusterId: cluster.id,
});

# ...

# Our MongoDB cluster (currently just one node).
cluster = digitalocean.DatabaseCluster("cluster", digitalocean.DatabaseClusterArgs(
 engine = "mongodb",
 version = "5",
 region = region,
 size = digitalocean.DatabaseSlug.D_B_1_VPCU1_GB,
 node_count = 1
))

# The database we'll use for our grocery list.
db = digitalocean.DatabaseDb("db", digitalocean.DatabaseDbArgs(
 name = "grocery-list",
 cluster_id = cluster.id
))

Now for the App Platform spec itself. Notice the digitalocean.App resource takes just one argument, spec, which defines all three of the components of the app: static site, service, and database. Both the static site and the service are configured to use the same GitHub repository (the sourceDir properties indicate their folders within the repository), and both are configured (via the deployOnPush flag) to be rebuilt and redeployed by DigitalOcean on every commit.

The service has a few additional settings that you can use to manage its runtime behavior and deployment topology as well. As in development, we’ll configure the service to listen on port 8000 and be available at /api—the entire app will ultimately be proxied transparently by an App Platform load balancer—and it’ll be powered by just one container instance, again using the least expensive performance settings:

// ...

// The App Platform spec that defines our grocery list.
const app = new digitalocean.App("app", {
 spec: {
 name: "grocery-list",
 region: region,

 // The React front end.
 staticSites: [
 {
 name: "frontend",
 github: {
 repo,
 branch,
 deployOnPush: true,
 },
 sourceDir: "/frontend",
 buildCommand: "npm install && npm run build",
 outputDir: "/dist",
 }
 ],

 // The Express back end.
 services: [
 {
 name: "backend",
 github: {
 repo,
 branch,
 deployOnPush: true,
 },
 sourceDir: "/backend",
 buildCommand: "npm install && npm run build",
 runCommand: "npm start",
 httpPort: 8000,
 routes: [
 {
 path: "/api",
 preservePathPrefix: true,
 },
 ],
 instanceSizeSlug: "basic-xxs",
 instanceCount: 1,

 // To connect to MongoDB, the service needs a DATABASE_URL, which
 // is conveniently exposed as an environment variable thanks to its
 // membership in this app spec (below).
 envs: [
 {
 key: "DATABASE_URL",
 scope: "RUN_AND_BUILD_TIME",
 value: "${db.DATABASE_URL}",
 },
 ],
 },
 ],

 // Include the MongoDB cluster as an integrated App Platform component.
 databases: [
 {
 // The name `db` defines the prefix of the tokens used (above) to
 // read the environment variables exposed by the database cluster.
 name: "db",

 // MongoDB clusters are only available in "production" mode.
 // https://docs.digitalocean.com/products/app-platform/how-to/manage-databases/
 production: true,

 // A reference to the `DatabaseCluster` we declared above.
 clusterName: cluster.name,

 // The engine value must be uppercase, so we transform it with JS.
 engine: cluster.engine.apply(engine => engine.toUpperCase()),
 }
 ]
 },
});

# ...

# The App Platform spec that defines our grocery list.
app = digitalocean.App("app", digitalocean.AppArgs(
 spec = digitalocean.AppSpecArgs(
 name = "grocery-list",
 region = region,

 # The React front end.
 static_sites = [
 digitalocean.AppSpecStaticSiteArgs(
 name = "frontend",
 github = digitalocean.AppSpecJobGithubArgs(
 repo = repo,
 branch = branch,
 deploy_on_push = True
 ),
 source_dir = "/frontend",
 build_command = "npm install && npm run build",
 output_dir = "/dist"
 )
 ],

 # The Express back end.
 services = [
 digitalocean.AppSpecServiceArgs(
 name = "backend",
 github = digitalocean.AppSpecJobGithubArgs(
 repo = repo,
 branch = branch,
 deploy_on_push = True
 ),
 source_dir = "/backend",
 build_command = "npm install && npm run build",
 run_command = "npm start",
 http_port = 8000,
 routes = [
 digitalocean.AppSpecServiceRouteArgs(
 path = "/api",
 preserve_path_prefix = True
 )
 ],
 instance_size_slug = "basic-xxs",
 instance_count = 1,

 # To connect to MongoDB, the service needs a DATABASE_URL, which
 # is conveniently exposed as an environment variable because the
 # database belongs to the app (see below).
 envs = [
 digitalocean.AppSpecServiceEnvArgs(
 key = "DATABASE_URL",
 scope = "RUN_AND_BUILD_TIME",
 value = "${db.DATABASE_URL}"
 )
 ]
 )
 ],

 # Include the MongoDB cluster as an integrated App Platform component.
 databases = [
 digitalocean.AppSpecDatabaseArgs(
 # The `db` name defines the prefix of the tokens used (above) to
 # read the environment variables exposed by the database cluster.
 name = "db",

 # MongoDB clusters are only available in "production" mode.
 # https://docs.digitalocean.com/products/app-platform/concepts/database/
 production = True,

 # A reference to the managed cluster we declared above.
 cluster_name = cluster.name,

 # The engine value must be uppercase, so we transform it with Python.
 engine = cluster.engine.apply(lambda engine: engine.upper())
 )
 ]
 ),
))

Technically that’s all we need to configure the application—but it wouldn’t be a bad idea to add one last thing.

By default, managed MongoDB clusters are configured to be publicly accessible—which is great if you need to be able to connect one yourself, but not so great as a strategy for preventing internet miscreants from doing the same. You can fix this easily by adding a DatabaseFirewall resource to declare the app as a trusted source, thereby rejecting all inbound traffic originating from elsewhere:

// ...

// Adding a database firewall setting grants access solely to our app.
const trustedSource = new digitalocean.DatabaseFirewall("trusted-source", {
 clusterId: cluster.id,
 rules: [
 {
 type: "app",
 value: app.id,
 },
 ],
});

# ...

# Adding a database firewall setting restricts access solely to our app.
trusted_source = digitalocean.DatabaseFirewall("trusted-source", digitalocean.DatabaseFirewallArgs(
 cluster_id = cluster.id,
 rules = [
 digitalocean.DatabaseFirewallRuleArgs(
 type = "app",
 value = app.id
 )
 ],
))

And finally, add one last line to export the app URL, to be generated by DigitalOcean, as a Pulumi stack output:

// ...

// The DigitalOcean-assigned URL for our app.
export const { liveUrl } = app;

# ...

# The DigitalOcean-assigned URL for our app.
pulumi.export("liveUrl", app.live_url)

With that, you’re ready to deploy.

Deploying

Quickly, to recap, here’s what we’ve done so far:

We took a pre-baked MERN app configured to run on localhost.
We mapped the tiers of that app to their corresponding App Platform components.
We wrote a Pulumi program to codify that mapping as an App Platform spec and a managed MongoDB cluster to go along with it.

When you deploy this app in a moment with pulumi up, Pulumi will provision a new MongoDB cluster (which usually takes a few minutes), and then once that’s available, DigitalOcean will take our spec and use it to fetch the components of the app from GitHub at the specified branch and build them. From that point forward, any commit you make to that branch will trigger DigitalOcean to fetch, rebuild, and redeploy the app automatically.

Make sure you’ve installed the DigitalOcean GitHub app as described above—you should see it listed at https://github.com/settings/installations:

Now return to the command line and run pulumi up:

$ pulumi up

Previewing update (dev)

View Live: https://app.pulumi.com/cnunciato/grocery-list/dev/previews/605bf32a-95b1-4221-bc35-0e667b30f38a

 Type Name Plan
 + pulumi:pulumi:Stack grocery-list-dev create
 + ├─ digitalocean:index:DatabaseCluster cluster create
 + ├─ digitalocean:index:DatabaseDb db create
 + ├─ digitalocean:index:App app create
 + └─ digitalocean:index:DatabaseFirewall trusted-source create

Resources:
 + 5 to create

Do you want to perform this update?
> yes

Updating (dev)

View Live: https://app.pulumi.com/cnunciato/grocery-list/dev/updates/1

 Type Name Status
 pulumi:pulumi:Stack grocery-list-dev
 + ├─ digitalocean:index:App app created
 + └─ digitalocean:index:DatabaseFirewall trusted-source created

Outputs:
 + liveUrl: "https://grocery-list-fb9bd.ondigitalocean.app"

Resources:
 + 2 created
 3 unchanged

Duration: 2m30s

Again, it’ll probably take a few minutes to get everything spun up for the first time, but when the process completes, you’ll have a working app at the URL provided by DigitalOcean, emitted as a Pulumi stack output:

$ open $(pulumi stack output liveUrl)

$ open $(pulumi stack output live_url)

You should also be able to explore your shiny new grocery-list app in the DigitalOcean Console, with all three of its components (and their build-time and runtime logs!) now represented:

Now try making a commit to your repository (any commit will do, but ideally one to the frontend or backend folder), and watch as the app redeploys automatically:

And finally, try scaling the service by bumping the instanceCount from 1 to 2 in the code—or better, if you’re up for it, making that value configurable by stack:

 const config = new pulumi.Config();
 const repo = config.require("repo");
 const branch = config.require("branch");
+ const serviceInstanceCount = config.requireNumber("service_instance_count");
 ...
 services: [
 digitalocean.AppSpecServiceArgs(
 ...
+ instanceCount: serviceInstanceCount,

 config = pulumi.Config()
 repo = config.require("repo")
 branch = config.require("branch")
+ service_instance_count = config.requireNumber("service_instance_count");
 ...
 services: [
 digitalocean.AppSpecServiceArgs(
 ...
+ instance_count: service_instance_count,

Set the instance count with pulumi config:

$ pulumi config set service_instance_count 2

Then deploy the new app spec with a final pulumi up:

$ pulumi up

Updating (dev)

 Type Name Status Info
 pulumi:pulumi:Stack grocery-list-dev
 ~ └─ digitalocean:index:App app updated [diff: ~spec]

Outputs:
 liveUrl: "https://grocery-list-fb9bd.ondigitalocean.app"

Resources:
 ~ 1 updated
 4 unchanged

Duration: 1m27s

And when you’re finished experimenting, you can tear everything down in just a few seconds with a pulumi destroy:

$ pulumi destroy

Destroying (dev)

 Type Name Status
 - pulumi:pulumi:Stack grocery-list-dev deleted
 - ├─ digitalocean:index:DatabaseFirewall trusted-source deleted
 - ├─ digitalocean:index:DatabaseDb db deleted
 - ├─ digitalocean:index:App app deleted
 - └─ digitalocean:index:DatabaseCluster cluster deleted

Resources:
 - 5 deleted

Duration: 19s

Wrapping up, and next steps

Hopefully this gives you a sense of the kinds of things you can do with Pulumi and DigitalOcean—and I definitely encourage you to spend a little time with the App Platform docs to dig a bit deeper into some of these concepts and explore a few others we weren’t able to cover. You’ll find the full source for this walkthrough on GitHub, of course, with finished branch containing the completed Pulumi program for reference.

From here, you might think about:

Adding a digitalocean.DnsRecord to give your app a custom domain name.
Creating a second stack with pulumi stack init and adjusting the program to make the source branch configurable—a production stack, say, designed to deploy in response to commits to a release branch.
Using Pulumi’s GitHub Action to run previews and updates as part of a pull-request based workflow.

Happy coding!