Forem: Antwi Isaac

Yet Another Article to Dockerizing An App — But with a twist

Antwi Isaac — Sun, 31 Aug 2025 11:12:16 +0000

Do-cker... doc-ker…. dock-er. You’ve probably heard this term so much and you’re wondering what the fuss is. What is it? Do I need it? Does it make a difference? I’ve been building apps without Docker just fine… I hear you. Just hold my mug.…

Officially, “docker is a tool that helps you develop, ship and run applications within lightweight containers.” Okay.. but what does this mean?

Say you’re building the next billion dollar app with your friend. You’re using a windows laptop while he’s using a mac. You make some changes to the code and push your updates to Github. He then pulls your updates and tries to run the application — damn, it doesn’t work. Ei? You jump on a Zoom call and show him that it works fine on your laptop; he then shares his screen and shows you a weird error… well, that’s awkward. It works fine on your machine, but it doesn’t on his. Why?

For some kinds of apps, this wouldn’t have been an issue. Your todo app built using HTML, CSS and JavaScript maybe fine ;). However, other apps, for example, a NodeJS service that requires specific OS-level drivers / packages to work would easily run into compatibility issues — Windows and MacOS are fundamentally different. Also remember that the server your application would be deployed on might come with a different OS, setup and environment.

That’s where docker comes into play. What if in building, testing and deploying, you can have the same “configuration” used everywhere? You share that “configuration” with your friend, deploy it on your production server and it runs — just like magic, except that it’s not magic *wink.

Lets dive into Docker: Concepts

To get started with Docker, download Docker Desktop here: https://www.docker.com/get-started. It installs a GUI you can use as well as the command line tools.

At the core of docker, there are three concepts to understand: Dockerfile, Images and Containers.

1. Dockerfile

It is text file with instructions on how to build a Docker image. Think of the Dockerfile as a recipe or a blueprint. It contains all the instructions — step by step — to set up your application. You specify everything your app needs and how to run / start it in the Dockerfile.

2. Image

Using the recipe (Dockerfile), you bake a cake (Image). Docker images are immutable, which means if you make any change to the Dockerfile and rebuild, you create a new image and do not modify the existing one (if any exist). Versions of an image are managed using tags.

Images can be shared with other developers anywhere — just think of it as giving a file to someone. Many developers use DockerHub to share images.

As an example, here’s the official MongoDB Image on Docker: https://hub.docker.com/_/mongo

3.Container

A container is running instance of a Docker image. This is like eating or serving the cake to your guests. The image is static, but the container is a live process running inside of an isolated environment.

Now that we’re clear with the basic concepts and rationale behind using docker, lets dockerize (create a Dockerfile, build an image and use that to spin up a container).

Here’s the repo of what we’re building: https://github.com/okraks/dockerizing-app-example

Create a Dockerfile

Create a Dockerfile in the root of your application. The Dockerfile contains instructions (remember the recipe?) on how to package and run your app.

1.Set the base image: This command sets the base image (think of it as a minimal OS that can run processes, libraries, networking and a filesystem). In this command, I use the official NodeJS image from Docker hub (it has nodejs and npm already installed)

FROM node:18.11.0

Set working directory: It’s usually good practice to set the working directory inside the container. All subsequent commands (COPY, RUN, etc.) will be executed inside /app. If /app doesn’t exist, it will be created automatically.

WORKDIR /app

Copy package.json and yarn.lock into the /app directory: This is a common optimization. You copy dependency files first, then run yarn install, so Docker can cache that layer if your dependencies haven’t changed everytime you rebuild the image.

COPY ./package.json ./yarn.lock /app/

Install Dependencies: RUN executes a command at build time (in contrast to CMD which runs at container start). This installs all dependencies listed in package.json using yarn.

RUN yarn install --frozen-lockfile

Copy code in src folder into docker: Copies your app’s source code from your local ./src folder into the container’s /app/src directory. The syntax means COPY “from” “into”

COPY ./src /app/src

Start the application. Similar to running yarn dev to invoke the dev script in package.json. CMD defines the default command that runs when the container starts. For production builds, you’d use “yarn start”

CMD ["yarn", "dev"]

Build the Image

Now that we have our instructions (Dockerfile), we can build our image using the command bellow. The flag -t assigns a name (and optionally a tag using syntax name:tag) to the image you’re building. The full stop is to point to the current folder we’re in.

docker build -t our_awesome_app .

So now we have an image called “our_awesome_app” and we can start a container using it, or even share it.

Here’s the example image shared on DockerHub: https://hub.docker.com/r/okraks/dockerizing-app-example

Start a Container using the Image

This command tells docker take the image “our_awesome_app” and start a new container using it. If the image doesn’t exist locally, it would try to pull it from DockerHub or any other registry.
“-p” is the port mapping flag. It connects a port inside the container to a port on your machine (the host). In our app, we started our server on PORT 8080 so we expose that same PORT from our container to our host machine. The syntax is
-p <host_port>:<container_port>

docker run -p 8080:8080 our_awesome_app

That’s it! Your application is running now and is available on your laptop on port 8080. In another article, we’d explore a setup of several applications (for example, a frontend, a database server and a backend service) using a popular library: docker-compose.

Enough talk. Time to build.

Resources

Learn Docker in 7 Easy Steps — Full Beginner’s Tutorial
https://www.youtube.com/watch?v=gAkwW2tuIqE

The Only Docker Tutorial You Need To Get Started https://youtu.be/DQdB7wFEygo

Docker Docs
https://docs.docker.com/get-started/docker-overview/

Seamless Payments with Stripe: A Developer’s Guide to Easy Integration

Antwi Isaac — Sat, 16 Aug 2025 17:35:16 +0000

Stripe has firmly established itself as a leader in payment processing, simplifying the payment acceptance process for developers. In this guide, we’ll walk through setting up a Node.js Express service integrated with Stripe using Checkout Sessions. We’ll focus solely on Checkout Sessions for a hands-on introduction. For other integration options, view the docs here: Stripe Payment Options

High Level Design & Flow

Before diving into the code, here’s a high-level overview of the integration process.

Gotchas & Things to Note

Handle Currency and Amount Formatting: Stripe expects amounts in minor units (e.g., $10.00 should be passed as 1000 cents).
Use Webhooks for Reliable Payment Confirmation: Don’t rely on the client-side redirect for payment status.
Ensure Metadata is Passed Correctly: To track payments efficiently
Enable Webhook Signature Verification: Always verify Stripe webhook signatures to prevent unauthorized or spoofed events.

Let’s Code 🚀

1.Initialise a package.json file
yarn init -y

2.Install dependencies
yarn add express stripe dotenv

3.Install dev dependencies.
yarn add -D nodemon typescript @types/express @types/node

4.Initialise Typescript
This would create a new tsconfig.json file that tells typescript how to transpile our app

npx tsc --init

5.Update your scripts in package.json

"scripts": {
    "build": "yarn install && tsc",
    "dev": "nodemon src/server.ts",
    "start": "node dist/server.js"
  }

Your package.json should look like this

6.Create your src folder and create a server.ts file in it

import express, { Request, Response } from "express";
import dotenv from "dotenv";
import Stripe from "stripe";

// Environment config
dotenv.config();

// Stripe initialization
let _stripe: Stripe | null = null;
export const getStripe = (): Stripe => {
  if (!_stripe) {
    _stripe = new Stripe(process.env.STRIPE_TEST_KEY as string);
  }
  return _stripe;
};

// create an express app
const app = express();

// Express Middleware setup
app.use(express.json());

const port = process.env.PORT || 3001;

// Default Route
app.get("/", (_, res) => {
  res.status(200).json({
    success: true,
    message: "Our express app is live!",
  });
});

// Start Server
app.listen(port, () => {
  console.log(`🚀 Server up and running on port: ${port}`);
});

7.Create an .env file in the root of your project

PORT=8080
STRIPE_TEST_KEY=your_stripe_test_key
STRIPE_WEBHOOK_SECRET=stripe_webhook_secret

Follow this guide to obtain your Stripe Test Key: https://docs.stripe.com/keys

8.Our app is ready... well almost. Run yarn dev to start the server. You should get this feedback.

Lets Handle Payment Requests

Now that our server is running. We’re going to do two things.

Accepting incoming payment requests from the client.
Listen for Stripe webhook events and process them

1.Accepting Incoming Payment Requests

When a payment request arrives, calculate the total amount to be paid. For example, in an e-commerce app, send the product_id and quantity, then retrieve the product price and compute the final amount. (Calculate the total amount in the backend, not the frontend, to ensure security and prevent tampering.)

When creating a Checkout Session with Stripe:

Specify the currency in lowercase (e.g. “usd”).
Convert the price to cents (e.g. $10.00 → 1000).
Include relevant metadata (e.g. order_id, productName, productId).
Set success and cancel URLs for proper redirection after payment.

Learn more about Checkout Sessions here: Stripe Checkout Sessions

// POST  /checkout to process incoming payment requests from client
app.post("/checkout", async (req: Request, res: Response) => {
  /*  
    Retreive cart from request, calculate final amount to be paid.
    In this example we're purchasing only one product with quantity 1
  */

  const product: { id: number; name: string; priceInCents: number } = {
    id: 1,
    name: "Sunglasses",
    priceInCents: 4500,
  };

  // Create an order, store it on your database with paymentStatus "unpaid"
  // This article is focused on stripe so I'm not doing that fully.
  const orderId = Math.floor(Math.random() * 1000);

  try {
    const session = await getStripe().checkout.sessions.create({
      currency: "usd",
      metadata: {
        productName: product?.name,
        productId: product?.id,
        orderId: orderId,
      },
      line_items: [
        {
          price_data: {
            currency: "usd",
            product_data: {
              name: product?.name,
              metadata: product,
            },
            unit_amount: product.priceInCents,
          },
          quantity: 1,
        },
      ],
      mode: "payment", // other modes are 'subscription' and 'setup'
      success_url: `http://localhost:3000/checkout?status=failed`,
      cancel_url: `http://localhost:3000/checkout?status=failed`,
    });

    res.status(200).json({ checkoutUrl: session.url });
  } catch (e) {
    console.log("e", e);
    res.status(500).json({ error: "Something went wrong" });
  }
});

2.Listen for events strom Stripe via Webhook

Add this code block before the app.use(express.json()) line. This is because, for Stripe to validate the signature of your webhook, it has to be raw without any json parsing.

// Stripe webhook to listen for events
app.post(
  "/stripe-webhook",
  express.raw({ type: "application/json" }),
  async (req: Request, res: Response) => {
    const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

    try {
      if (endpointSecret) {
        // Get the signature sent by Stripe
        const signature = req.headers["stripe-signature"];

        if (!signature) {
          throw new Error("Missing Stripe signature");
        }

        const event = getStripe().webhooks.constructEvent(
          req.body,
          signature,
          endpointSecret
        );

        switch (event.type) {
          case "checkout.session.completed": {
            const checkoutSession = event.data.object;

            const {
              currency,
              subscription,
              amount_total,
              status,
              payment_status,
              metadata,
              created,
            } = checkoutSession;

            // Get order ID from metadata since it was passed
            const orderId = metadata?.orderId;

            /*
             Mark order as complete based on the payment_status
             You have access ti other information from the checkout session
             including the amount_total, date created, currency and so much more
             checkoout the Checkout session object in stripe docs: https://docs.stripe.com/api/checkout/sessions/object
            */

            // handle your database updates and any other logic
            if (payment_status == "paid") {
              //
            }

            break;
          }

          default:
            console.log(`⚡️ Unhandled Stripe Webhook ->  ${event.type}`);
        }

        res.json({ received: true });
      } else {
        res.status(500).json({ message: "Something went wrong" });
      }
    } catch (error: any) {
      console.error(`Webhook error: ${error?.message}`);
      res.status(400).send(`Webhook error: ${error?.message}`);
    }
  }
);

Forwarding Stripe Events to your local machine

Add your local event listener in the Stripe dashboard. Ensure that your webhook endpoint has been configured with the “checkout.session.completed” event included.

View the docs here: Webhooks

Install the Stripe CLI, login and run this command. This would listen to webhook events and forward them to the endpoint we specified.

stripe listen --forward-to localhost:8080/stripe-webhook

Now we’re ready to test our setup.

Interactive Testing With Stripe Test Keys

When testing interactively, use a card number, such as 4242 4242 4242 4242 to simulate a successful payment.

Use a valid future date, such as 12/34.
Use any three-digit CVC (four digits for American Express cards).
Use any value you like for other form fields.

Read More About Testing Cards: Stripe Testing

Full Code for this tutorial is available on Github

You can view the full code on Github: https://github.com/okraks/stripe-integration-guide

Related Articles & Resources

WebDev Simplified: How to Accept Payments with Stripe: https://youtu.be/1r-F3FIONl8
https://docs.stripe.com/checkout/quickstart?client=next&lang=node