DEV Community: Hemant Sharma

Building a Production-Grade CI/CD Pipeline with GitHub Actions, GHCR, Docker, and a VPS

Hemant Sharma — Mon, 10 Aug 2026 12:00:00 +0000

Introduction

I had a NestJS backend that needed to go live, and I did not want the deploy process to be me SSHing into the VPS every time. I also did not want to outsource the whole thing to a PaaS "Deploy" button. I wanted a proper pipeline, so I can simply push code, run tests, ship a container, cut traffic over safely, and deploy the latest version.

So I built one. GitHub Actions, GHCR, Docker, nginx, and a DigitalOcean VPS. This post is about that story — what I set up, what I got wrong along the way, and what still matters after the host changed later.

The backend sat in a pnpm monorepo next to a Next.js frontend. Vercel took care of the frontend. Postgres lived on a managed provider. The part I spent real time on was getting the API from git push to a healthy process behind TLS.

Throughout the blog, I will be referring to the project codebase, to refer the codebase you can click here to see the full repo.

What I needed from the pipeline

Before I touched the YAML files, I wrote down what "good" looked like to me:

A push to the right branch should deploy. I should not be copy-pasting commands on the server for normal releases. Rather, it should be automated.
The same commit should produce the same image, so rollback is "run an older SHA", not "try to rebuild what we think we shipped."
If the new version is broken, the old one should keep serving.
Database Migrations should happen before the new backend business logic takes traffic.
Cost should stay low — I had DigitalOcean credits, so a small VPS was fine.
Dev and prod should be separate environments, but the same pipeline shape.

A managed platform would have been less work. I wanted the loop in my own hands instead: build, registry, host, cutover.

How a release works

Here is the flow I had in plain terms.

git push (main | dev branch on GitHub)
        │
        ▼
   GitHub Actions
   ┌──────────────────────────────┐
   │ 1. pnpm test (backend)       │
   │ 2. verify DB connectivity    │
   │ 3. drizzle-kit migrate       │
   │ 4. build → push GHCR (:sha)  │
   │ 5. scp deploy.sh             │
   │ 6. SSH → blue-green swap     │
   └──────────────────────────────┘
        │
        ▼
   VPS (nginx + Let's Encrypt SSL)
   idle port → health gate → upstream rewrite → SIGTERM drain

And here is the same pipeline as a full diagram — Actions through GHCR into blue-green on the VPS:

A few rules I treated as non-negotiable:

If tests fail → nothing gets built, migrated, or deployed at all.
Database connectivity is checked, and only then are the migrations run, before containers swap.
The thing we deploy is an image tagged with the git SHA — not a vague :latest tag to ensure uniqueness of the image.
The new container starts on a free port and has to pass a DB-aware /health check through the exposed API route.
If that check fails, we simply abort moving to the latest image container. The previous container stays alive and handles the traffic as usual.

The API container only listened on localhost within the VPS, and nginx terminated TLS and was the only thing exposed to the internet as what a reverse proxy should be.

Building the image (and not lying to Docker)

I build a multi-stage image from the repo root , not from apps/backend alone. In a pnpm workspace the backend depends on a shared package. If the Docker context ignores that, you get a build that looks fine until it is not.

The Dockerfile installs with --filter backend..., builds packages/shared then apps/backend, and uses pnpm deploy --prod so the runtime stage is a pruned tree instead of the whole monorepo.

A few decisions that saved me pain:

bookworm-slim (glibc), not Alpine. bcrypt and musl have bitten enough people. I picked the boring base.
Run as node, not root.
HEALTHCHECK hits /health."Process is up" is not the same as "can talk to Postgres."
Exec-form CMD. Node is PID 1, so SIGTERM reaches Nest's shutdown hooks and the pool can drain cleanly.

FROM node:22-bookworm-slim AS runtime
ENV NODE_ENV=production PORT=3001
WORKDIR /app

COPY --from=build --chown=node:node /out ./

USER node
EXPOSE 3001

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3001)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

CMD ["node", "dist/main"]

Images go to GHCR as <image>:<git-sha>, with an env *-latest tag only as a convenience. The deploy script always gets the SHA. Buildx cache (type=gha) keeps rebuilds from starting from zero every push.

Migrate first, then cut traffic

This one is easy to get backwards.

If you swap the container and then migrate, the new code can boot against an old schema and fall over in front of users. If you migrate first (and keep schema changes expand/contract-friendly), the old container keeps serving while the database moves forward. Then the new container takes over.

"Migration failed" often means "we never connected." drizzle-kit can sit behind a spinner for a long time without telling you much. So the workflow prints host/port/user (password stays out of the logs) and runs a quick select 1 with a 10s timeout before migrate.

On GitHub-hosted runners, some managed Postgres hosts prefer IPv6 so, forcing NODE_OPTIONS=--dns-result-order=ipv4first helped clear a set of hangs that looked like flaky CI and were really DNS.

- name: Verify DB connectivity
  working-directory: apps/backend
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
  run: |
    # Log host/port/user (never the password), then:
    # new Client({ connectionString, connectionTimeoutMillis: 10000 }).query('select 1')

- name: Run DB migrations
  working-directory: apps/backend
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
  run: pnpm exec drizzle-kit migrate

Blue-green on the VPS

I did not want a 502 window where the old process is gone, and the new one is still starting creating a time space where user requests might hit a wall, and they simply see a broken application. So each environment has two ports (prod 3001 / 3002, dev 3101 / 3102). The new container always starts on the idle one.

Only after /health succeeds do we rewrite nginx's upstream and reload. Then we stop the old container with a 30s grace period so in-flight work can finish.

infra/deploy.sh lives in the repo and gets scp'd on every deployment, so the script on the VPS cannot silently drift from git:

# Health gate: up to ~60s for the new container to report DB-ready.
OK=0
for _ in $(seq 1 30); do
  if curl -fsS "http://127.0.0.1:$IDLE/health" >/dev/null 2>&1; then OK=1; break; fi
  sleep 2
done
if ["$OK" != 1]; then
  echo "!! health check FAILED — aborting, leaving $OLD live" >&2
  docker logs --tail 80 "$NEW" || true
  docker rm -f "$NEW" || true
  exit 1
fi

echo "upstream backend_$ENV { server 127.0.0.1:$IDLE; }" \
  | sudo tee "/etc/nginx/conf.d/upstream-$ENV.conf" >/dev/null
sudo nginx -t
sudo systemctl reload nginx

Containers bind to 127.0.0.1 (localhost) only. nginx handles HTTPS with Let's Encrypt as the reverse proxy.

One small debugging habit that paid off: the SSH step prints hostname, whoami, and a directory listing first. If a secret points at the wrong machine, you see it immediately instead of "deploy succeeded" on a host you did not mean to touch.

The alternative I refused was the classic pull → stop → start on a single port. That leaves a gap where nothing healthy is listening, and there is no automatic "keep the old one."

The host itself

I provisioned the VPS with an idempotent infra/setup-vps.sh: Docker, nginx, Certbot, ufw (22/80/443), fail2ban, swap, key-only SSH, and a deploy user whose sudo is limited to reloading nginx.

Secrets stay on the host in env files (/opt/<app>/<env>/backend.env) and get passed in with --env-file. They do not get baked into the image, and they do not get committed.

More scripting up front than clicking through a panel. Everything about the host is in git and can be re-run.

A few CI details that mattered in a monorepo

There were path filters on apps/backend/ **, packages/shared/**, and the workflow file — so, a frontend-only change should not redeploy the backend or vice versa.
GitHub Environments were set for both Production vs. Development, so secrets and rules differ by branch without copying the whole workflow.
Concurrency per branch with cancel-in-progress: false — so overlapping deploys to the same env should wait, not interleave mid-swap.
packages: write so GITHUB_TOKEN can push to GHCR without a long-lived PAT for the normal path.
workflow_dispatch for the days when I want to ship by hand without relying on a push trigger.

What I considered instead

Option	Why it was tempting	Why I did not start there
Manual SSH + Compose	Fast on day one	Easy to drift, easy to mess up prod, no clean audit trail
Build on the VPS from git	Simple to picture	Ties the host to your build toolchain; weaker "same commit = same backend" story
PaaS (e.g. Render) from day one	Less nginx and SSH	Less control over cutover and health gating
Something like Coolify	Quick UI setup	It would consume more VPS resources just for one single project, which I mostly wouldn't need since deployment is fully automated through GHA

I wanted those rules sitting in the repo where I could read them.

When the host changed

Later the live backend moved off the always-on VPS to a cheaper managed host. The important part: I did not have to redesign the release model. The GHA workflow is still there and can still builds the image, GHCR still can stores it by SHA, migrations still run before the new revision serves traffic. The VPS workflow is still in the repo if I want self-hosting again.

That was the part I was happiest about. The backend travels. The host is replaceable.

Wrapping up

If I do this again, I am keeping the same core:

Images tagged by commit SHA
Migrate before cutover, with a real connectivity check
Health-gated traffic flip, abort if unhealthy
Secrets on the runtime side, never in the image
Path-filtered CI so the monorepo does not waste deploy runs

That is the pipeline I built and ran. It shipped for AmbitiousYou — workflows and host scripts are under .github/workflows/ and infra/ if you want the full files.

Originally published at https://hemantsharma.tech/blog/7-building-production-grade-cicd-pipeline.

Stop Breaking Your Forms: Type-Safe Server Actions in Next.js

Hemant Sharma — Mon, 15 Dec 2025 16:43:11 +0000

Build Next.js forms you can't break. Learn the pattern I use to create type-safe Server Actions that catch errors at compile-time, not in production.

Problem: Inefficient Forms

I have been building forms in applications for years at this point and after building so many forms, I found out some real issues that always stand in place if you want to scale your application because then you would need real strict conventions for your entire stack. When I was building one of my side projects, I was simply building the form just how the docs or any other blogpost suggested on the internet but sooner as my project grew in size, I found several difficulties maintaining the form and the engineer in me thought it wasn’t quite OK to be honest. The form gave me no confidence in pushing it to production as there were multiple return statements in places then too many if-else blocks in my client component it just created cognitive load and didn’t quite work well for complex forms handling multiple data types and different situations and that was when I decided I need to find a proper solution to this, I dug deeper over the internet and docs and questioning LLMs everywhere I found almost the same solution that I was already implementing that’s when I decided to think through forms myself and I came upon this really good solution myself.

Solution: Stateful Contracts

Let’s think of forms in the aspect of “States“ (like states of matter or even state in React if you would). States are an analogy we can apply on forms as well. Any form can have states, for e.g. a form with just 2 fields has a total of 3 states for it’s fields - none filled, 1 filled, all filled. So that means our forms can be in any state and in order to not flush out the input values from the user, we always try to maintain the input data. So in order to maintain the state of our forms we are going to be using the useActionState() hook from React.

Next up, Types!

Types are a really really great way of reducing runtime bugs or even catch bugs in comilation of your code before it hits production ensuring you have a really great developer experience and boosted confidence in your code in production, eventually reducing the 3 AM debuggings you had to do 😂

I have not seen much solutions where developers apply types to React hooks but for a matter of fact and saviour, these hooks do have Types support! I don’t understand why we don’t use types as often, it might increase development time a little bit, but at least after that you have a peace of mind about your code not breaking in production at least without any reason.

Let’s see the solution in Action!

Complete code to copy/refer has been provided at the end of this explanation section

We will create a form where I expect the user to fill in Name, Email, Age. So we have data types of string and number.

Since our forms are states and would be using useActionState hook consider extracting away the form from your server component since we will need to make the form a client component, we first create a TypeScript Interface that looks something like this

remember to export the interface since we are going to need it in our server actions as well since this is what is our Stateful Contract that will be communicated between the form and the server action.

After this we create a new file where we describe our server action and this is how thing look initially

Let’s begin by adding the useActionState hook for the form

as of this, let’s ignore any warnings and errors since we are creating a fully typed form and server action contract this is what’s expected, the TypeScript compiler will definitely throw error at you that is what’s going to force you to write a really good and type-safe code.

I have udpated the server action to be inferring the same types, for the sake of this blog, I won’t be performing any network calls like submitting or anything since that is not our concern in this case

Notice how I have wrapped the age in Number because I have inferred the return type as the contract interface that we defined initially which forced me to make that string value a number since that is what we expect to be.

Now I update the component and add types to my useActionState hook to ensure a proper contract between the form and the server action.

Now that we have completed the solution to the problem, let’s handle the formState using useEffect or you can even handle it in your TSX if you want.

This way we are going to ensure that we don’t exchange any data among the form and the server action that is not present in the interface that we created initially.

I also updated the Server Actions and added some basic validation

This practice of adding type to the useActionState hook and the Server Action return type, TypeScript forces us to make sure the exchanging the data is not hindering the contract and ensure seamless two-way data binding.

Now if you want to add any new field in the form, you will be prompted through an error in both the places in Server Action and the React form that tells you to add it to the contract lowering your chances of breaking anything in production.

Final Code

page.tsx

"use client";

import { useActionState, useEffect, useState } from "react";
import { submitForm } from "./action";

export interface FormState {
  name: string;
  email: string;
  age: number;

  error?: string;
}

export default function Home() {
  const [formValues, setFormValues] = useState<FormState>({
    name: "",
    email: "",
    age: 0,
  });
  const [formState, formAction, isFormPending] = useActionState<FormState, FormData>(submitForm, formValues);

  useEffect(() => {
    if (formState.error) {
      alert(formState.error);
    }
  }, [formState.error]);

  return (
    <form action={formAction} className="flex flex-col gap-4 max-w-sm mx-auto py-10">
      <label htmlFor="name">Name</label>
      <input
        type="text"
        name="name"
        id="name"
        value={formValues.name}
        onChange={(e) => setFormValues({ ...formValues, name: e.target.value })}
      />
      <label htmlFor="email">Email</label>
      <input
        type="email"
        name="email"
        id="email"
        value={formValues.email}
        onChange={(e) => setFormValues({ ...formValues, email: e.target.value })}
      />
      <label htmlFor="age">Age</label>
      <input
        type="number"
        name="age"
        id="age"
        value={formValues.age}
        onChange={(e) => setFormValues({ ...formValues, age: Number(e.target.value) })}
      />

      <button type="submit">{isFormPending ? "Submitting..." : "Submit"}</button>
    </form>
  );
}

action.ts

"use server";

import { FormState } from "./page";

export async function submitForm(previousState: FormState, formData: FormData): Promise<FormState> {
  const submittedFormValues = {
    name: formData.get("name") as string,
    email: formData.get("email") as string,
    age: Number(formData.get("age") as string),
  };

  console.log("submittedFormValues", submittedFormValues);

  if (submittedFormValues.name === "") {
    return {
      ...previousState,
      error: "Name is required",
    };
  }

  if (submittedFormValues.email === "") {
    return {
      ...previousState,
      error: "Email is required",
    };
  }

  if (submittedFormValues.age === 0 || submittedFormValues.age < 0) {
    return {
      ...previousState,
      error: "Age is required and must be greater than 0",
    };
  }

  return submittedFormValues;
}

This way we can handle the errors and the data gracefully while still maintaing the Form State

Page Visibility API

Hemant Sharma — Mon, 28 Oct 2024 12:00:00 +0000

Introduction

The Page Visibility API provides events you can watch for to know when a webpage is visible or in focus or not. This can be useful for saving resources or improving user experience when the user is not actively interacting with the page.

How to use Page Visibility API

The Page Visibility API provides two events that you can listen for: visibilitychange and fullscreenchange.

Here is an example of how to use the visibilitychange event to detect when the page is hidden or visible:

document.addEventListener("visibilitychange", function() {
  if (document.hidden) {
    console.log("Page is hidden");
  } else {
    console.log("Page is visible");
  }
});

You can also use the document.hidden property to check if the page is currently hidden or visible:

if (document.hidden) {
  console.log("Page is hidden");
} else {
  console.log("Page is visible");
}

Let's see it in action

To see the Page Visibility API in action, let's create a simple web page that logs the visibility state of the page:

<body>
  <h1>Page Visibility API Example</h1>

  <script>
    document.addEventListener("visibilitychange", function() {
      if (document.hidden) {
        console.log("Page is hidden");
      } else {
        console.log("Page is visible");
      }
    });
  </script>
</body>

In this example, we are logging the visibility state of the page whenever the visibilitychange event is triggered.

Practical Applications

The Page Visibility API can be incredibly useful in various scenarios:

Pause/Resume Animations and Videos: Automatically pause animations or videos when the page is hidden and resume them when the page becomes visible again.
Optimize Resource Usage: Save CPU and memory by stopping resource-intensive tasks when the user is not actively interacting with the page.
Track User Engagement: Monitor user engagement by tracking how often and how long users keep your webpage in focus.

By incorporating the Page Visibility API into your web applications, you can create a more efficient and user-friendly experience. Start using this powerful API today and take your web development skills to the next level!

The Page Visibility API can be useful for scenarios where you want to pause or resume animations, videos, or other resource-intensive tasks based on whether the page is visible or not. It can also be used to track user engagement and optimize the user experience based on the visibility state of the page.

Originally published at https://hemantsharma.tech/blog/6.

sessionStorage in browsers

Hemant Sharma — Mon, 12 Aug 2024 12:00:00 +0000

Introduction

sessionStorage is a type of web storage that allows JavaScript sites and apps to store and access data right in the browser with an expiration date. This means the data stored in the browser will be available only for the duration of the page session.

How to use sessionStorage

sessionStorage is similar to localStorage, but the data stored using sessionStorage is available only for the duration of the page session. This means the data will be cleared when the page session ends, i.e., when the browser window is closed.

Here is an example of how to use sessionStorage to store and retrieve data:

// Store data in sessionStorage
sessionStorage.setItem("name", "John Doe");

// Retrieve data from sessionStorage
const name = sessionStorage.getItem("name");

console.log(name); // Output: John Doe

// Remove data from sessionStorage
sessionStorage.removeItem("name");

// Clear all data from sessionStorage
sessionStorage.clear();

Let's see it in action

To see sessionStorage in action, let's create a simple web page that stores and retrieves data using sessionStorage.

<body>
  <h1>sessionStorage Example</h1>

  <input type="text" id="name" placeholder="Enter your name" />
  <button onclick="storeData()">Store Data</button>
  <button onclick="retrieveData()">Retrieve Data</button>
  <button onclick="removeItem()">Remove Data</button>

  <script>
    function storeData() {
      const name = document.getElementById("name").value;
      sessionStorage.setItem("name", name);
    }

    function retrieveData() {
      const name = sessionStorage.getItem("name");
      alert("Hello, " + name);
    }

    function removeItem() {
      sessionStorage.removeItem("name");
    }
  </script>
</body>

Implementation Example

Browser Console output

In this example, we have created a simple web page that allows users to store and retrieve data using sessionStorage. The data stored using sessionStorage will be available only for the duration of the page session.

See sessionStorage in browser DevTools

You can also interact with sessionStorage using the browser DevTools. To access sessionStorage in the DevTools:

Open the browser DevTools by pressing F12 or right-clicking on the page and selecting "Inspect".
Go to the "Application" tab in the DevTools.
In the "Storage" section, you will find "sessionStorage" under the "Storage" section. Here, you can see the data stored using sessionStorage and interact with it.

Here's an example of how sessionStorage looks in the browser DevTools:

That's it! You have learned how to use sessionStorage to store and access data in the browser with an expiration date. Try using sessionStorage in your web projects to store temporary data that is available only for the duration of the page session.

Conclusion

sessionStorage is a useful feature in web development that allows you to store and access data in the browser with an expiration date. It is similar to localStorage but has a shorter lifespan, making it ideal for storing temporary data that is required only for the duration of the page session. Use sessionStorage in your web projects to enhance user experience and improve data management.

Originally published at https://hemantsharma.tech/blog/5.

localStorage in browsers

Hemant Sharma — Mon, 12 Aug 2024 12:00:00 +0000

Introduction

localStorage is a type of web storage that allows JavaScript sites and apps to store and access data right in the browser with no expiration date. This means the data stored in the browser will persist even after the browser window is closed.

How to use localStorage

localStorage is a simple key-value store that can be used to store data in the browser. It is supported by all modern browsers and can be accessed using the localStorage object.

Here is an example of how to use localStorage to store and retrieve data:

// Store data in localStorage
localStorage.setItem("name", "John Doe");

// Retrieve data from localStorage
const name = localStorage.getItem("name");

console.log(name); // Output: John Doe

// Remove data from localStorage
localStorage.removeItem("name");

// Clear all data from localStorage
localStorage.clear();

Let's see it in action

To see localStorage in action, let's create a simple web page that stores and retrieves data using localStorage.

<body>
  <h1>localStorage Example</h1>

  <input type="text" id="name" placeholder="Enter your name" />
  <button onclick="storeData()">Store Data</button>
  <button onclick="retrieveData()">Retrieve Data</button>
  <button onclick="removeItem()">Remove Data</button>

  <script>
    function storeData() {
      const name = document.getElementById("name").value;
      localStorage.setItem("name", name);
    }

    function retrieveData() {
      const name = localStorage.getItem("name");
      alert("Hello, " + name);
    }

    function removeItem() {
      localStorage.removeItem("name");
      alert("Data removed from localStorage");
    }
  </script>
</body>

Implemented Example

In this example, we have created a simple web page with an input field to enter a name and two buttons to store and retrieve the name using localStorage.

See localStorage in browser DevTools

You can also see the data stored in localStorage using the browser DevTools. Here's how you can do it:

Open the browser DevTools by either pressing F12 or right-clicking on the page and selecting "Inspect".
Go to the "Application" or "Storage" tab in the DevTools.
In the "Storage" section, you will see "Local Storage" on the left-hand side. Click on it and select the domain/URL you wish to view the data stored in localStorage for.
You should see the data stored in localStorage, including the key-value pairs that you have set.

Pros and Cons of localStorage

| Pros | Cons | | --- | --- | | Persistence — Data stored in localStorage persists after the browser window is closed. Ideal for user preferences, session data, and other cross-session information. | Security — Data is not encrypted and can be read by anyone with browser access. Do not store passwords, payment details, or other sensitive data. | | Simple API — Straightforward key-value setItem, getItem, and removeItem methods with a low learning curve. | No expiration — Entries persist until explicitly removed, which can lead to stale data or storage bloat without cleanup. | | Large capacity — Typically ~5–10 MB per origin, far more than cookies for client-side storage needs. | Same-origin only — Data is scoped to protocol, domain, and port; not shared across origins or subdomains by default. |

Conclusion

localStorage is a powerful feature that allows web developers to store data in the browser without any expiration date. It can be used to store user preferences, session data, and other information that needs to persist across browser sessions.

I hope this article has helped you understand how localStorage works and how you can use it in your web applications. If you have any questions or feedback, feel free to leave a comment below.

Originally published at https://hemantsharma.tech/blog/4.