DEV Community: Abdullah Sheikh

How to Build a Blockchain-Based Voting System from Scratch: A Beginner’s Guide

Abdullah Sheikh — Thu, 25 Jun 2026 12:06:02 +0000

Step‑by‑step you’ll design, code, and launch a secure, transparent voting app using blockchain technology

Before We Start: What You'll Walk Away With

When you finish this guide you’ll see the whole blockchain voting system layout, from the ledger’s blocks to the user’s screen.

You’ll code a tiny smart contract, push it to a public testnet, and hook up a basic web page that lets voters cast and verify their choices.

A ready‑to‑use checklist will show you how to lock down the prototype and stretch it for real elections.

Think of the architecture like a restaurant kitchen: the blockchain is the pantry where ingredients (votes) are stored safely, the smart contract is the chef’s recipe, and the front‑end is the waiter taking orders.

Understand the three‑layer layout – network, contract, UI.
Write and test a vote() function that records a choice.
Deploy on goerli (or any testnet) and connect via Web3.js.
Run the front‑end, submit a ballot, and watch the transaction appear in the block explorer.

Tools you’ll need are simple:

Node.js – runs JavaScript scripts.
Hardhat – compiles and deploys contracts.
MetaMask – injects a wallet into the browser.
Vite – quick dev server for the UI.

Here’s a quick cheat sheet to keep on your desk:

Contract address: copy from the deployment log.
ABI file: artifacts/contracts/Vote.sol/Vote.json.
Network RPC: https://goerli.infura.io/v3/….
Gas limit: start with 200000 and adjust if needed.

With these pieces in place you’ll have a functional blockchain voting system you can demo tomorrow.

What Blockchain Voting Actually Is (No Jargon)

Blockchain voting records each ballot as a permanent entry on a shared ledger that lives on many computers at once. Once a vote is written, the network checks it against the existing chain and then locks it in place, so nobody can alter or erase it later. The result is a transparent, tamper‑resistant list that anyone can audit without trusting a single authority.

Imagine a public Google Sheet where every voter gets a unique link to add a new row. The sheet is view‑only for everyone else, and once a row appears it’s frozen—no one can go back and change the numbers. That’s essentially how a blockchain voting system works, except the “sheet” is distributed across dozens or hundreds of nodes, and the freezing happens automatically through cryptographic rules rather than a manual lock.

The 3 Mistakes Everyone Makes With Blockchain Voting

Most first attempts stumble over the same three traps.

Over‑engineering: You’ll see folks launch a full public blockchain for a small poll, then wonder why it’s crawling. Think of it like ordering a 12‑course dinner when you only wanted a sandwich. A permissioned testnet or even a simple sidechain gives you speed, lower costs, and the control you need without the unnecessary baggage.
Ignoring UX: Voters quickly bail if the interface feels like a crypto wallet instead of a ballot box. Imagine trying to navigate Google Maps with only voice commands—confusing and frustrating. Keep the flow to a few clicks: login, select candidate, confirm. Simplicity trumps flash.
Skipping security basics: Some skip hashing voter IDs or fail to safeguard private keys. That’s akin to packing a suitcase and leaving the lock off; anyone can peek inside. Use a standard hash function for IDs and store keys in a hardware security module or a vault service. Even a modest security layer stops the obvious attacks.

Avoid these pitfalls and your blockchain voting system will stay functional, friendly, and safe.

How to Build a Blockchain Voting System: Step‑by‑Step

Pick a blockchain playground. The easiest start is Ethereum’s Goerli testnet paired with Solidity contracts—think of it as a sandbox where you can experiment without real money.
Get your tools ready. Install Node.js, then pull in Hardhat (npm install --save-dev hardhat) and add the Metamask extension to your browser. This setup is like assembling a kitchen before you start cooking.
Write the smart contract. Create a .sol file that includes three core functions: registerVoter(), castVote(), and tally(). Each function should check permissions, record a vote, or sum results, respectively.
Run local tests. Use Hardhat’s built‑in network to simulate a full voting round: register a few dummy addresses, cast votes, then call tally() and assert the expected outcome.
Deploy to Goerli. Fund a test wallet via a faucet, then execute npx hardhat run scripts/deploy.js --network goerli. After deployment, paste the contract address into Etherscan’s verification page so anyone can read the source.
Build the front‑end. Scaffold a React app, install ethers.js, and write components that call the contract’s methods. Keep the UI simple—just a registration form, a list of candidates, and a “Submit Vote” button.
Hook up Metamask. When a user clicks “Submit Vote,” prompt Metamask to sign the transaction. This step is the digital equivalent of signing a ballot in person.
Show the results. Query tally() from the UI, then render a chart (e.g., using Chart.js) so every voter can see a transparent, real‑time count.

Cheat Sheet

npm i -g hardhat
npx hardhat node – local testnet
npx hardhat run scripts/deploy.js --network goerli
Metamask → Goerli test network

A Real Example: Campus Student Council Election

Maya, the IT coordinator at Greenfield University, needs a cheap, tamper‑proof vote for 250 students.

She boots up Hardhat and creates a new project folder called student‑council‑vote. Just like setting up a new playlist, the command

npx hardhat init

gives her a clean workspace.

Using the template from the guide, Maya names the Solidity contract StudentCouncilVote. The contract mirrors a simple menu: each student picks one dish (candidate) and the kitchen (blockchain) records the order.
She registers every voter by hashing their university email. The script looks like this:

const crypto = require('crypto');
function hashEmail(email) {
  return crypto.createHash('sha256').update(email).digest('hex');
}

She runs the script for the 250 emails, stores the hashes in voters.json, and calls registerVoter(hash) on the contract.
Each student receives a unique link like https://vote.greenfield.edu/2024. Think of it as a QR code on a cafeteria tray, pointing them straight to their voting seat.
On voting day, students open the React app, connect their MetaMask wallet, and see a list of candidates. When they click “Vote”, the app sends a transaction to vote(candidateId). The blockchain acts like a digital receipt printer – immutable and instantly visible.
Results update in real time on a bar chart. It’s like watching a live poll on a sports scoreboard; every new vote nudges the bars up.
Tip: Set the contract’s onlyOnce modifier to block double‑voting, just as a turnstile lets each person through only once.
Cheat sheet: Deploy with npx hardhat run scripts/deploy.js --network localhost, then start the UI with npm start.

That’s Maya’s end‑to‑end blockchain voting system, ready for the next student council election.

The Tools That Make This Easier

Grab the right gear and the rest feels like ordering a coffee—straightforward and quick.

Hardhat – Think of it as a local kitchen where you can bake, taste, and fix recipes before serving anyone. It spins up a private Ethereum node, runs tests, and lets you debug contracts without waiting for a public network.
Alchemy – This is the reliable delivery service for your dishes. Their Goerli RPC endpoint works like a Google Maps lane: fast, stable, and with a dashboard that shows traffic (request latency) at a glance.
Ethers.js – The Swiss‑army knife for wallet chores. It lets you sign, send, and read transactions with just a few lines, much like using a single app to pay for a ride, a meal, and a movie.
React + Vite – Picture a pre‑packed suitcase for your front‑end. Vite whips up a dev server in seconds, and React gives you modular compartments to drop UI pieces into without clutter.
MetaMask – Your personal ID badge at the voting booth. The browser extension stores keys, prompts signatures, and shows balances, so users can vote with a single click.

Putting them together looks like this:

Initialize a Hardhat project, add @openzeppelin/contracts, and write the ballot contract.
Deploy to Alchemy’s Goerli endpoint using npx hardhat run scripts/deploy.js --network goerli.
In your React app, import ethers and connect to MetaMask to read/write votes.

Cheat sheet

Hardhat: npx hardhat node
Alchemy dashboard: copy the Goerli API key, paste into hardhat.config.js
Ethers: const provider = new ethers.providers.Web3Provider(window.ethereum)
Vite start: npm run dev
MetaMask: ensure network set to “Goerli Testnet”

With these tools in hand, building a blockchain voting system becomes a matter of assembling, not inventing.

Quick Reference: Blockchain Voting Cheat Sheet

Grab this cheat sheet and keep it open while you code – it’s the quick‑order menu for your blockchain voting system.

✅ Pick a permissioned testnet – think of Goerli as a sandbox playground where you can experiment without paying real gas fees.
✅ Set up the toolbox – install Node.js, Hardhat, and add the MetaMask extension. It’s like assembling a kitchen before you start cooking.

✅ Smart contract skeleton – implement three core functions:

- `registerVoter(address)` – like signing up a new user on a website.

- `castVote(uint256 candidateId)` – similar to clicking “order” in a food‑delivery app.

- `tallyVotes()` – the final receipt that adds up every order.

✅ Run local tests – use Hardhat scripts to simulate registrations and votes before any live deployment. It’s the “dry‑run” before the real show.
✅ Deploy and verify – push the contract to Goerli, then verify it on Etherscan. For example, when Alice deployed her community poll, the verification link let every participant inspect the exact code they were trusting.
✅ Build the front‑end – combine React, ethers.js, and MetaMask. Think of it as a Google Maps UI that guides voters to the right address.

✅ Security checklist

- Hash voter IDs before storing them.

- Never expose private keys; keep them in environment variables.

- Enforce one‑vote‑per‑address logic in the contract.

✅ Plan for scale – once the prototype works, migrate to Polygon or a private consortium chain. It’s like moving from a small café to a larger restaurant when the crowd grows.

Keep this list handy; it’s your shortcut from idea to a working blockchain voting system.

What to Do Next

Grab the repo, spin it up, and see the voting flow in action.

Easy: Fork the GitHub repo linked below and run npm start (or python -m http.server) on your laptop. It’s like ordering a ready‑made pizza – you just heat it up and start eating.
Medium: Swap the hard‑coded voter list for a CSV import. Read the file, hash each email with keccak256, and feed the hashes into the contract. Think of it as packing a suitcase: you replace loose items with neatly folded ones that fit the space.
Hard: Deploy the contract on a permissioned Hyperledger Besu network. Set up the consortium nodes, configure privacy groups, and point your front‑end to the new RPC endpoint. This step is the “Google Maps” of the guide – you’re building your own road network instead of using the default streets.
Tools: truffle or hardhat for migrations, csv‑parser (JS) or pandas (Python) for CSV handling, and Docker for Besu.
Tip: Keep the private key for the admin account in a .env file and never commit it.

Got stuck or have a cool use case? Drop a comment or DM me – I’d love to hear how you’re using a blockchain voting system!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

With 6+ years of experience, Abdullah has built CRMs, Crypto Wallets, DeFi Exchanges, E-Commerce Stores, HIPAA Compliant EMR Systems, and AI-powered systems that drive business efficiency and innovation.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build a Blockchain-Based Voting System: A Beginner’s Step‑By‑Step Guide

Abdullah Sheikh — Wed, 24 Jun 2026 12:05:02 +0000

Create a secure, transparent voting app on a blockchain from scratch—even if you’ve never coded one before

Before We Start: What You’ll Walk Away With

By the end of this guide you’ll be able to picture a blockchain voting system the way you picture a pizza menu – you know the layers, the ingredients, and how they fit together.

First, you’ll grasp the core architecture: a network of nodes, a ledger that records every ballot, and a smart contract that enforces the rules.

Second, you’ll fire up a local testnet, write a minimal Vote contract, and push a working dApp to a browser, just like ordering a coffee and watching it appear on the screen.

Third, you’ll walk away with a concise checklist of tools, libraries, and next‑step resources that let you move from prototype to production without missing a beat.

Understand the three‑tier layout – front‑end UI, smart‑contract back‑end, and the peer‑to‑peer network.
Spin up a test network, code a simple contract, and deploy the dApp.
Use the provided checklist to scale, secure, and audit your solution.
Node setup: docker + geth (or ganache-cli)
Smart‑contract language: Solidity (latest stable)
Front‑end framework: React or plain HTML/JS
Testing tools: Truffle or Hardhat, Mocha
Deployment helpers: Remix for quick edits, Alchemy for hosted nodes
Cheat sheet: npm install -g truffle → truffle init → truffle compile → truffle migrate
Next‑step reading: Ethereum Whitepaper, OpenZeppelin contracts, OWASP blockchain checklist

Now you have a clear roadmap – let’s start building.

What Blockchain Voting Actually Is (No Jargon)

At its core, a blockchain voting system stores each ballot as an immutable transaction on a shared ledger, so once a vote lands it can’t be altered or erased.

Picture a public Google Sheet that anyone can open, watch new rows appear, but can’t change once they’re saved. Every voter writes their choice into a new row; the sheet records the time, the voter’s ID (or a pseudonym), and locks the entry forever. The sheet lives on many computers at once, so no single owner can slip in a fake row later.

This setup gives two big guarantees:

Transparency: Everyone can see the full list of votes, just like watching a live spreadsheet.
Tamper‑resistance: The moment a row is added, cryptographic hashes bind it to the previous one, creating a chain that can’t be rewritten without changing every later entry.
Decentralisation: The ledger lives on multiple nodes, so no one server can decide to delete or modify a vote.

Think of it as a community chalkboard that every neighbor can add a mark to, but once the chalk dries, it’s set in stone. If someone tries to scrape it off, the whole board’s pattern changes and everyone notices.

That’s the essence of a blockchain voting system—simple, open, and stubbornly permanent.

The 3 Mistakes Everyone Makes With Blockchain Voting

Most newcomers trip over the same three landmines when they try to launch a blockchain voting system.

Forgetting voter anonymity and ending up with a traceable ledger.

Imagine ordering a pizza and writing your full name, address, and credit‑card number on the box. Anyone who sees the box instantly knows who ordered it. In a voting app, if you store raw wallet addresses or IPs, the ballot becomes public knowledge. Use zero‑knowledge proofs or mix‑nets to strip identifiers before they hit the chain.

Deploying to a public mainnet before testing.

It’s like driving a brand‑new car off the lot without checking the brakes. A single bug can lock up funds or expose voter data, and fixing it on mainnet costs real crypto. Spin up a local ganache node, then move to a testnet such as Sepolia before you ever hit the main network.

Over‑engineering the UI before the contract works.

Think of packing a suitcase full of accessories before you know if the flight even exists. Build a minimal web page that lets you submit a vote, then verify the transaction lands in the block explorer. Once the contract logic is solid, add fancy charts and drag‑and‑drop components.

Skip these pitfalls, and you’ll save time, money, and a lot of headaches.

How to Build a Blockchain Voting System: Step‑By‑Step

Grab a coffee and follow these seven actions to get a functional blockchain voting system up and running.

Set up your local dev environment. Install Node.js, then run

npm install --save-dev hardhat

to pull in Hardhat. Add the MetaMask extension, create a test wallet, and connect it to your local Hardhat node—think of it like setting the table before a dinner.

Write a simple ERC‑20‑style voting contract. In contracts/Vote.sol define struct Proposal, a mapping for votes, and functions createProposal and vote. It mirrors a basic point‑of‑sale system: you add items (proposals) and then tally purchases (votes).
Add unit tests. Create test/vote.test.js and use Hardhat’s ethers library to simulate accounts casting votes. Assert that vote counts update correctly—like checking a receipt after ordering food.

Deploy to a testnet. Run

npx hardhat run scripts/deploy.js --network sepolia

and note the contract address. Sepolia works like a sandbox version of Mainnet, safe for experiments.

Build a minimal front‑end. Scaffold a React app (npx create-react-app client) and install ethers. In App.jsx connect MetaMask, load the contract with its address, and add buttons for createProposal and vote. Imagine the UI as a Google Maps interface: you click a pin (button) and the app talks to the blockchain.

Host on IPFS. Run

npm run build && ipfs add -r build

to get a CID, then pin it through a public gateway (e.g., Pinata). Point your domain’s DNS to gateway.ipfs.io/ipfs/yourCID so anyone can load the app without a traditional server.

Run a pilot election. Invite a handful of colleagues, let them vote through the UI, and collect screenshots of transaction hashes. Use the feedback to tighten validation rules—just like a dress rehearsal before a theater premiere.

Follow these steps, and you’ll have a working blockchain voting system you can demo in a single afternoon.

A Real Example: Campus Student Council Election

Maya, president of her university tech club, needs a fast, tamper‑proof vote for the student council.

Define the candidates – She writes a simple Solidity contract in contracts/Vote.sol that stores three names: Alex, Sam, and Jordan.
Test locally – Using Hardhat, Maya runs npx hardhat test to verify that only one vote per address is accepted, just like checking a receipt after ordering food.
Deploy to Sepolia – With npx hardhat run scripts/deploy.js --network sepolia she pushes the contract, treating the testnet like a practice run before a real concert.
Build the front‑end – A React dashboard (see snippet below) shows the three candidates, lets each of the 200 students cast a vote, and updates the tally in real time.
Distribute the link – Maya generates a QR code that encodes the URL https://myvote.app. Scanning it is as easy as pulling up a menu on a phone.
Publish the audit trail – After voting closes, she posts the final transaction hash on the club’s Discord, giving anyone the ability to trace every vote on Etherscan.
Tools: Hardhat, React, ethers.js, QR‑code generator.
Tip: Keep the contract’s owner address limited to Maya’s university email for extra trust.

Cheat sheet:

Compile: npx hardhat compile
Test: npx hardhat test
Deploy: npx hardhat run scripts/deploy.js --network sepolia

import { ethers } from "ethers";
const provider = new ethers.providers.Web3Provider(window.ethereum);
await provider.send("eth_requestAccounts", []);
const contract = new ethers.Contract(address, abi, provider.getSigner());
await contract.vote(1); // 1 = Alex

Maya’s campus election proves a blockchain voting system can be as straightforward as ordering a coffee.

The Tools That Make This Easier

Grab the tools you need first, then the voting app will start to feel like assembling a pizza rather than building a spaceship.

Hardhat (2025) – Think of it as your local kitchen where you can knead, taste, and perfect the dough before serving. Install with npm install --save-dev hardhat, run npx hardhat init, and you’ll have a sandbox Ethereum node, automatic compilation, and a test runner ready to go.
MetaMask Flask – This is the developer‑only wallet that lets you point your phone or browser to any RPC endpoint, like choosing a different lane on a highway. After adding the Flask extension, enable “Custom RPC” and paste the Hardhat node URL (usually http://127.0.0.1:8545) to interact with your contracts locally.
Remix IDE – Use the browser‑based editor when you need to whip up a quick contract fix, similar to jotting a note on a napkin. Open remix.ethereum.org, paste your Solidity code, hit compile, and test with the injected MetaMask Flask wallet.
Vercel – Treat it like a self‑service coffee machine that brews and serves your React front‑end with zero config. Push your frontend/ folder to GitHub, link the repo on Vercel, and it will auto‑deploy on every commit.
Pinata Cloud – This is the free locker for static assets, akin to a public photo album that never disappears. Upload your UI images or ballot JSON via the dashboard or CLI (pinata-cli pin-file-to-ipfs ./assets/logo.png) and copy the returned CID into your front‑end.
Cheat sheet: Hardhat node → MetaMask RPC, Remix for quick patches, Vercel for CI/CD, Pinata for IPFS.
Tip: Keep your .env file out of version control; Vercel lets you add those variables in the dashboard.

With these five tools in place, the rest of the blockchain voting system falls into place.

Quick Reference: Blockchain Voting Cheat Sheet

Grab this cheat sheet when you need a refresher, no fluff.

Core idea: Treat each vote like a pizza order that gets logged on an immutable ledger.
Stack: Node.js + Hardhat + ethers.js for the back‑end, React + MetaMask for the UI, IPFS for file storage.
Steps: Set up env → write contract → run tests → deploy → build front‑end → run a pilot.
Pitfalls: Forgetting voter anonymity, launching on mainnet too soon, polishing UI before the core works.
Tools: Hardhat, MetaMask Flask, Remix, Vercel, Pinata.
Env setup: npm init -y, install hardhat, ethers, dotenv.
Contract: Write Voting.sol with vote() and tally() functions.
Test: Use Hardhat’s describe blocks; think of them as test‑driving a car before a road trip.
Deploy: Run npx hardhat run scripts/deploy.js --network goerli—like sending a suitcase to a friend's house.
Front‑end: Connect React to MetaMask via ethers.provider, fetch vote data from IPFS.
Pilot: Invite a small group, record feedback, iterate.
Quick tip: Keep the UI minimal until the contract passes all tests.
Safety tip: Store private keys only in .env, never in repo.
Scaling tip: Move to a layer‑2 solution only after the prototype proves stable.

This cheat sheet is your go‑to for building a blockchain voting system.

What to Do Next

Grab the repo, fire up your local node, and watch the contracts spin up like a coffee machine brewing your first espresso.

Clone and run. Open a terminal, run git clone https://github.com/yourname/blockchain-voting-starter.git, then cd blockchain-voting-starter and npx hardhat node. It’s the same as pulling a ready‑made pizza dough and popping it in the oven—no kneading required.
Tweak the contract. Open contracts/Vote.sol and add a mapping for weight or a deadline variable. Think of it like adding extra toppings or setting a delivery timer on your pizza order.
Scale up. Deploy to a testnet with npx hardhat run scripts/deploy.js --network goerli, then hook a zero‑knowledge proof library (e.g., snarkjs) to mask voter identities. This step is similar to moving from a local map app to a full‑blown GPS system that keeps your route private.
Tools you’ll need: Node.js ≥ 16, Hardhat, Metamask, and snarkjs for privacy.
Tip: Commit each change before moving on; it’s like packing one suitcase at a time so you don’t forget anything.

Cheat sheet:

Start node: npx hardhat node
Deploy: npx hardhat run scripts/deploy.js --network goerli
Run tests: npx hardhat test

💬 Got stuck or have a unique use‑case? Drop a comment below and let’s troubleshoot together!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build a Blockchain-Based Voting System from Scratch: A Beginner’s Guide

Abdullah Sheikh — Tue, 23 Jun 2026 12:05:41 +0000

Step‑by‑step you’ll design, deploy, and test a secure voting dApp without needing advanced coding skills

Before We Start: What You'll Walk Away With

You’ll finish this tutorial able to spin up a working blockchain voting system without writing a single cryptographic algorithm.

First, you’ll know what pieces—smart contract, front‑end, wallet, and testnet—fit together, just like the layers of a sandwich.

Second, you’ll push a minimal dApp to a public test network using only free tools, similar to ordering a coffee with a few taps on your phone.

Third, you’ll run a mock election, collect votes, and prove the tally is correct, the way a GPS confirms you arrived at the right address.

Identify core components and their roles.
Deploy the contract and connect a simple UI.
Execute a test vote, then audit the result on chain.
Tools: Remix IDE, MetaMask, Polygon Mumbai testnet.
Languages: Solidity for the contract, JavaScript for the front‑end.
Free resources: GitHub templates, public faucet for test tokens.

This blockchain voting system tutorial gives you a repeatable workflow you can showcase to a small community or a hackathon jury.

When you’re done, you’ll have a live demo URL, source code, and a one‑page cheat sheet to reproduce the whole setup in under an hour.

Ready to roll up your sleeves and build?

What Blockchain Voting Actually Is (No Jargon)

What blockchain voting actually is can be summed up in one sentence: it stores each ballot as an unchangeable record on a shared digital ledger, so anyone can verify the count while no one can alter a vote after it’s cast. The ledger lives on many computers at once, which means there’s no single point that an attacker can target to rewrite results.

Imagine a public spreadsheet that anyone can open, but once a row is added it’s locked forever. Each voter drops a sealed envelope into the spreadsheet; the envelope’s contents (the vote) become part of the permanent record, visible to all eyes yet unreadable without the proper key. No one can erase or move that row, and because every participant holds a copy, tampering would be obvious instantly. That’s the essence of a blockchain voting system tutorial – a transparent, tamper‑resistant way to run an election without the need for a trusted central authority.

The 3 Mistakes Everyone Makes With Blockchain Voting

Most people hit the same roadblocks before they even see a vote recorded.

Over‑engineering – You’ll spend weeks building a blockchain from scratch, only to discover it’s as fragile as a homemade cardboard bridge. Pick a proven platform like Ethereum or Hyperledger and treat it like a GPS: it gets you where you need to go without you having to map every street yourself.
Ignoring user experience – Requiring voters to install a crypto wallet feels like asking diners to assemble their own cutlery before ordering. Most people will just walk out. Offer a simple web login or QR‑code scan so the voting flow feels as natural as ordering a coffee.
Skipping verification – Without an audit trail, tallying votes is like counting luggage at an airport without a manifest. You lose accountability and trust. Log every transaction hash and publish a read‑only results page so observers can replay the count at any time.

Cheat sheet:

Use ethers.js or fabric-sdk instead of writing your own consensus.
Integrate Web3Modal for one‑click wallet connections.
Store each vote’s txHash in a public IPFS file for immutable verification.

Fix these three pitfalls and your blockchain voting system tutorial will move from “nice idea” to a functional pilot.

How to Build a Blockchain Voting System: Step‑By‑Step

Grab a testnet, spin up Remix, and you’ll have a sandbox where every vote is as cheap as ordering a coffee.

Pick a testnet. Ethereum Sepolia or Polygon Mumbai work like free Wi‑Fi zones—no real money, but the same rules apply.
Install MetaMask in your browser, create a test account, and fund it from the faucet. Then open Remix IDE. It’s the online notebook you’d use to sketch a recipe.

Write a Solidity contract. Keep it tiny:

pragma solidity ^0.8.0;

contract Vote {
    struct Candidate { string name; uint256 votes; }
    mapping(uint256 => Candidate) public candidates;
    mapping(address => bool) public voted;
    uint256 public nextId;

    event Voted(address voter, uint256 candidateId);

    function addCandidate(string memory _name) public {
        candidates[nextId] = Candidate(_name,0);
        nextId++;
    }

    function vote(uint256 _id) public {
        require(!voted[msg.sender], "Already voted");
        require(_id 
- Deploy from Remix: select the testnet, hit “Deploy”, then copy the contract address. Verify it on the Sepolia or Mumbai explorer—like checking a package’s tracking number.

Build a minimal front‑end. Create `index.html` with a button for each candidate and a script that calls `vote` via `ethers.js`. Example snippet:

html
Vote
Alice
Bob

const provider = new ethers.providers.Web3Provider(window.ethereum);
const contract = new ethers.Contract('YOUR_ADDRESS','[ABI]',provider.getSigner());
async function castVote(id){ await contract.vote(id); }




MetaMask will pop up asking for confirmation—just like confirming a payment on a shopping site.
- Run a mock election. Invite three test accounts (e.g., `0xA…`, `0xB…`, `0xC…`). Each casts a vote, and you’ll see the `Voted` events appear in Remix’s console, confirming the ballot traveled.

- Check the final tally. Call `getVotes` for each candidate from the front‑end or Remix “Read Contract” tab. The numbers should match the votes you recorded, proving the **blockchain voting system tutorial** works.

Now you have a working prototype you can show to anyone curious about trustworthy elections.

## A Real Example: Campus Student Council Election

Maya, the IT club lead, punches in the final piece of her campus election prototype.

- She clones the **voting‑contract** repo, runs `npm install`, and points the `.env` file at Sepolia’s RPC endpoint.

- In Remix, Maya compiles the contract and hits **Deploy**. The transaction lands on Sepolia and Etherscan shows a new contract address, just like a food order confirmation number.

- She adds three candidates in the admin UI: `ID 1 – Alex`, `ID 2 – Priya`, `ID 3 – Jamal`. Each ID is a simple integer, no fancy cryptography needed.

- Using the React front‑end, Maya shares the link `https://vote.maya‑campus.app` on the class Discord. Students click, pick a candidate, and click “Vote”. Their transaction hash appears instantly, mirroring the way a map shows your car’s location the moment you start moving.

- While votes pour in, Maya watches the **Votes** event stream on Etherscan. Every new line is a confirmed ballot, giving everyone live proof that the count can’t be altered.

- When the deadline hits, Maya opens the contract in Remix and runs `getResults()`. The function returns a JSON array with each candidate’s final tally.

- She copies the output, saves it as `election-results.json`, and attaches the file to the student newsletter. The audit log includes transaction hashes, so anyone can verify the numbers on the blockchain.

- **Tool tip:** Use `etherscan.io/address/…#events` to filter only the `VoteCast` events for a clean view.

**Cheat sheet:** 
- `npm run start` – launches the React UI.
- `npx hardhat run scripts/deploy.js --network sepolia` – redeploys the contract.
- `contract.getResults()` – pulls the final tally.

This real‑world run shows a complete **blockchain voting system tutorial** in action, from deployment to transparent result publishing.

## The Tools That Make This Easier

Grab these five tools and you’ll spend more time voting logic than hunting for setup tricks.

- **Remix IDE** – Think of it as the online kitchen where you whip up Solidity recipes. Open [remix.ethereum.org](https://remix.ethereum.org), write your contract, hit compile, and deploy to a testnet in a few clicks. No local node needed.

- **MetaMask** – Your digital wallet is like a prepaid card for testnet gas. Install the browser extension, create a test account, and fund it from a faucet; then you can sign transactions from Remix or any web app.

- **Ethers.js** – This JavaScript library is the Google Maps of blockchain calls. It translates human‑readable addresses into the right RPC requests, letting your React front‑end read vote tallies or submit ballots with just a few lines.

- **Polygon Scan (or Etherscan)** – Use it like a receipt printer. After deployment, paste the contract address into the explorer to verify source code, check events, and confirm that votes are being recorded correctly.

- **Vercel** – Think of Vercel as a suitcase that packs your React UI and ships it worldwide instantly. Push your repo, hit “Deploy,” and you get a public URL in seconds, perfect for demo users to cast votes.

**Cheat sheet**

- Remix: `Solidity Compiler → Deploy`

- MetaMask: `Connect → Approve Tx`

- Ethers.js: `provider.getContract()`

- Polygon Scan: `Verify Contract`

- Vercel: `vercel --prod`

With these tools in place, the rest of the tutorial moves from theory to a working *blockchain voting system tutorial* you can actually show off.

## Quick Reference: Blockchain Voting Cheat Sheet

Grab this cheat sheet whenever you need a quick reminder of the whole blockchain voting system tutorial.

- ✅ Pick a testnet – think of it as choosing the right kitchen for a trial bake. **Sepolia** for Ethereum or **Mumbai** for Polygon are the most beginner‑friendly.

- ✅ Install MetaMask and fund it with faucet `ETH` or `MATIC`. It’s like loading a prepaid card before you order food.

- ✅ Write & deploy a simple Solidity contract. Define `candidates`, a `vote()` function, and a `tally()` view. Imagine a ballot box that only accepts votes for the names you listed.

- ✅ Connect the front‑end via Ethers.js & MetaMask. This step mirrors plugging a USB drive into your laptop so the files (votes) can be read and written.

- ✅ Run a mock election, watch events, then call `getResults()`. For example, *Alice* (a civic‑tech volunteer) casts a vote, the UI shows a green tick, and the contract emits a `Voted` event you can see in the console.

- ✅ Verify on a block explorer and export the audit log. It’s like checking a receipt and saving a PDF for the restaurant manager.

- **Tools**: MetaMask, Hardhat (or Remix), Ethers.js, Node.js, a code editor.

- **Tips**: Keep the contract tiny – under 200 lines – to avoid gas surprises. Use `console.log` in Hardhat scripts to see transaction hashes instantly.

- **Cheat**: Rename the compiled artifact `Voting.json` and point your front‑end to `window.ethereum` for instant wallet detection.

Keep this list handy, and you’ll spin up a trustworthy voting prototype in minutes.

## What to Do Next

Grab the repo, spin it up, and watch the ballot box work in your own terminal.

- **Easy:** Fork the `blockchain-voting-demo` repository on GitHub, `npm install`, then `npm run dev`. It’s like ordering a pizza: you pick the base (the repo) and the kitchen (your local machine) does the rest. Verify the demo by casting a few test votes and checking the blockchain explorer.

- **Medium:** Hook up email‑linked wallet addresses for voter authentication. Use `nodemailer` to send a login link, then map the confirmed email to a generated wallet. Invite about 20 friends to try it—think of it as a weekend potluck where each guest brings a dish (their vote) and you confirm everyone’s name at the door.

- **Hard:** Deploy the smart contract to Polygon mainnet and add a zero‑knowledge proof (ZKP) library like `snarkjs` for anonymous voting. This step is the equivalent of moving from a local map app to a live GPS navigation system that hides your exact route. Follow the Polygon deployment guide, then replace the public vote function with a ZKP‑validated one.

- **Tools:** GitHub, Node.js, Metamask, Polygon Scan, `snarkjs`

- **Tips:** Keep your private keys in a .env file, run a local Polygon fork with `ganache-cli`, and test ZKP circuits with the provided `test/` folder.

Which of these steps are you most excited to tackle first?

---

---

## About the Author

**[Abdullah Sheikh](https://abdullah-sheikh.com/)** is the Founder & CEO at [Exteed](https://exteed.com/), where he leads a team of skilled developers specializing in [Web2](https://abdullah-sheikh.com/) and [Web3 applications](https://abdullah-sheikh.com/), [Custom Smart Contracts](https://abdullah-sheikh.com/), and [Blockchain solutions](https://abdullah-sheikh.com/).

With 6+ years of experience, Abdullah has built [CRMs](https://abdullah-sheikh.com/), [Crypto Wallets](https://abdullah-sheikh.com/), [DeFi Exchanges](https://abdullah-sheikh.com/), [E-Commerce Stores](https://abdullah-sheikh.com/), [HIPAA Compliant EMR Systems](https://abdullah-sheikh.com/), and [AI-powered systems](https://abdullah-sheikh.com/) that drive business efficiency and innovation.

His expertise spans [Blockchain](https://abdullah-sheikh.com/), [Crypto & Tokenomics](https://abdullah-sheikh.com/), [Artificial Intelligence](https://abdullah-sheikh.com/), and [Web Applications](https://abdullah-sheikh.com/); building reliable and smooth web apps that fit the client’s goals and requirements.

📧 [info@abdullah-sheikh.com](mailto:info@abdullah-sheikh.com) · 🔗 [LinkedIn](https://www.linkedin.com/in/-abdullah-sheikh/) · 🌐 [abdullah-sheikh.com](https://abdullah-sheikh.com/)

How to Build a Blockchain-Based Voting System from Scratch: A Beginner’s Guide

Abdullah Sheikh — Sun, 21 Jun 2026 12:03:49 +0000

Step‑by‑step you’ll design, code, and launch a secure, transparent voting app on a blockchain

Before We Start: What You'll Walk Away With

By the end of this guide you will be able to sketch the whole blockchain voting system on paper, write the contract that actually counts votes, and spin up a tiny web page where anyone can cast a ballot.

Think of the architecture like ordering a pizza: you pick the crust (network), choose the toppings (smart contract logic), and then the delivery driver (frontend) brings it to the door.

Core components – you’ll know what a node, a ledger, and a consensus algorithm do together, just as a kitchen, a menu, and a chef’s recipe define a restaurant.
Smart contract – you’ll code a contract that locks in each vote the way a safe keeps a lock‑combination secret.
Front‑end – you’ll launch a page that records a vote with a single click, similar to tapping “send” on a ride‑share app.
Tools you’ll touch: Node.js, Hardhat, React (optional), and a free testnet.
Tips to avoid common snags: keep functions pure, validate inputs early, and comment every state change.

Cheat sheet:

Deploy – npx hardhat run scripts/deploy.js --network localhost
Vote – contract.vote(candidateId)
Count – contract.getResults()

Now you have a clear picture of what a blockchain voting system looks like and the three milestones you’ll hit.

What Blockchain Voting Actually Is (No Jargon)

Blockchain voting is simply a web app where each cast ballot becomes a transaction recorded on a permanent ledger. That ledger lives on a network of computers, so no single server can rewrite or delete a vote after the fact.

Think of it like a communal notebook that everyone can open at the same time. When you write your entry, the page automatically stamps the time, locks the ink, and copies the page to every other reader’s notebook. No one can sneak in later and change what you wrote, and everyone sees the exact same list of entries.

Because the ledger is immutable, the system can prove that each vote came from an authorized voter, that it was counted once, and that the final tally reflects every recorded transaction. The math that secures the ledger runs in the background, so you don’t have to manage passwords or worry about a rogue admin erasing results.

In practice, a blockchain voting system lets you build a transparent, tamper‑proof poll with just a few lines of code, and the same principles apply whether you’re running a student council election or a small municipality’s budget vote.

The 3 Mistakes Everyone Makes With Blockchain Voting

Most people hit a wall fast because they try to make the system more complicated than it needs to be.

Over‑engineering: You’d build a private permissioned chain when a public testnet does the job. It’s like ordering a five‑course gourmet meal when a sandwich will satisfy the same hunger—extra steps, extra costs, no real benefit. Stick to a public testnet, deploy a simple smart contract, and let the network handle consensus.
Ignoring user experience: Complex wallet setups scare voters away. Imagine trying to navigate Google Maps with three different apps opened at once—confusing and likely to give up. Provide a single‑click “Connect Wallet” button, hide gas‑fee details until the transaction succeeds, and offer a fallback email link for non‑crypto users.
Forgetting auditability: Many projects hide the vote tally behind opaque contract calls. That’s like packing a suitcase and refusing to show the contents to customs—suspicion follows. Expose a read‑only endpoint, e.g., /api/votes/count, that returns the current tally directly from the blockchain so observers can verify results in real time.
Tool tip: Use ethers.js’s provider.getBalance to fetch live vote counts without extra gas.
Cheat sheet: Public testnet → goerli, Wallet UI → Web3Modal, Audit endpoint → GET /votes.

Keep the system lean, voter‑friendly, and transparent, and you’ll avoid the pitfalls that trip most newcomers.

How to Build a Blockchain Voting System: Step‑By‑Step

Let’s walk through the whole flow, one concrete action after another.

Pick a blockchain and get a wallet. Think of it like choosing a restaurant before ordering: you need a place that serves test meals. Open Goerli testnet, install MetaMask, and fund the wallet with a faucet request (curl -X POST https://goerli-faucet.xyz).
Write the voting contract. It’s like drafting a ballot template before printing. Create Voting.sol with a struct Candidate {uint id; string name; uint votes;} array, a mapping for voter tracking, and functions addCandidate, vote, and getResults.

Deploy the contract. Use Remix’s “Inject Web3” environment or run Hardhat:

npx hardhat run scripts/deploy.js --network goerli

The script should import the compiled artifact, call ethers.deployContract, and log the address.

Build a thin front‑end. Treat it like a Google Maps widget that shows where you are: an index.html with a tag, a simple form for candidate selection, and a container.

Add interaction logic. In app.js connect the wallet (await ethereum.request({method:'eth_requestAccounts'})), instantiate the contract with its ABI and address, then:

Send a vote transaction when the user clicks “Submit”.
Fetch and render the tally after each vote.
Check !voted[msg.sender] to stop double voting.
Run an end‑to‑end test. Open two separate browser profiles (or use MetaMask’s “Add Account”) as Alice and Bob, cast votes, and verify the results stay the same after refreshing. The immutable ledger guarantees the counts cannot be altered.
Cheat sheet: npm i ethers hardhat, npx hardhat compile, npx hardhat run.
Tip: Keep the contract address in a .env file and read it with process.env.CONTRACT_ADDRESS.

Now you have a working blockchain voting system ready for the next step.

A Real Example: Student Council Election for a Small College

Maya, a sophomore IT volunteer, wants to run a quick student‑council election for President, Vice‑President, and Treasurer.

Set up the environment – Maya installs MetaMask, switches to the Goerli testnet, and creates a fresh wallet for the election. It’s like pulling a new credit card just for a one‑off purchase.

Deploy the contract – Using the deploy.js script from the guide, she runs:

node scripts/deploy.js --network goerli

MetaMask pops up for confirmation, then the contract address appears. She copies it to a Google Doc for reference.

Share the voting page – Maya uploads index.html to Netlify, grabs the public URL, and emails it to 120 classmates. The page looks like a simple form: pick a candidate for each slot and hit “Vote”.
Cast votes – Students open the link, connect their MetaMask wallets, and submit their choices. Each transaction is recorded on Goerli, just as a receipt is logged in a restaurant’s POS system.

Run the tally – After the deadline, Maya opens a Node console and executes:

const results = await contract.methods.tally().call();

She copies the JSON output.

Publish results – Maya pastes the tallied numbers into a pre‑formatted Google Sheet and shares the sheet with the campus community. The sheet includes a checksum link back to the blockchain for verification.
Tool tip: Keep MetaMask unlocked while deploying and tallying to avoid “signature denied” errors.
Tip for students: Remind voters to double‑check the network (Goerli) before voting; otherwise the transaction will fail.

Cheat sheet:

node scripts/deploy.js – deploy contract
node scripts/tally.js – get results
Copy address → Google Sheet → share

This hands‑on run shows a real blockchain voting system in action, ready for the next campus poll.

The Tools That Make This Easier

Grab these five utilities and the whole blockchain voting system will feel as simple as ordering a pizza.

Remix IDE – a browser‑based Solidity editor that lets you write, compile, and deploy contracts without installing anything. Think of it as the drive‑through window for smart contracts: you type your order, hit “submit,” and the contract is baked and served on the spot.
Hardhat – a local development environment that mimics an Ethereum node and supports forking mainnet state. It’s like having a miniature Google Maps that lets you test routes before you leave the house, so you can spot errors without spending real ether.
Ethers.js – a lightweight JavaScript library for connecting your front‑end to the blockchain. Picture it as the universal charger that plugs your web page into any wallet or node, handling signatures and transactions with a few clean function calls.
MetaMask – a browser extension that acts as your personal wallet for testnet transactions. It’s the digital passport you need to prove identity and sign votes, just as you would swipe a credit card at checkout.
Pinata Cloud – an IPFS pinning service that stores your HTML, CSS, and images permanently. Think of it as a luggage locker at the airport; you drop off your assets once and they stay accessible whenever voters open the voting site.

Together they form a ready‑to‑copy toolbox: write the contract in Remix, spin up a sandbox with Hardhat, hook the UI with Ethers.js, sign actions through MetaMask, and keep the front‑end online via Pinata.

With these tools in hand, building a blockchain voting system becomes a straightforward, repeatable process.

Quick Reference: Blockchain Voting Cheat Sheet

Grab this list, follow it, and you’ll have a working blockchain voting system before your coffee cools.

Pick the Goerli testnet and install MetaMask. Think of Goerli as a sandbox playground where you can experiment without spending real ETH.
Write a minimal contract: a mapping(uint=>Candidate) for candidates, a vote() function that checks msg.sender and includes a nonce or timestamp to stop replay attacks. It’s like handing out a one‑time ticket at a concert.
Open Remix, compile, and hit “Deploy”. Copy the resulting contract address—your voting booth’s street number.

Build the front‑end with ethers.js. Implement:

connectWallet() – asks MetaMask to link the user (like tapping a transit card).
submitVote(candidateId) – sends a transaction to vote().
fetchResults() – reads the mapping to display current tallies.
Test using 2‑3 accounts. For example, Alice votes for candidate 1, Bob for candidate 2, then check the on‑chain totals to confirm they never change. This is your “proof of immutability” step.
Tools: Remix (online IDE), Hardhat (local dev chain), Ethers.js (web3 library), MetaMask (wallet), Pinata (IPFS for storing candidate images).
Tips: Keep the contract simple—no need for fancy voting logic until you master the basics. Store only IDs on chain; push logos or bios to IPFS via Pinata.

Cheat Sheet:

✅ Goerli + MetaMask
✅ Smart contract with candidates mapping & non‑replay vote()
✅ Deploy via Remix → note address
✅ Front‑end: ethers.js, connectWallet(), submitVote(), fetchResults()
✅ Test with multiple accounts, verify immutability
✅ Tools: Remix, Hardhat, Ethers.js, MetaMask, Pinata

Copy, paste, run—your blockchain voting system is ready.

What to Do Next

Start by getting a working copy of the code and a local blockchain to play with.

Clone the starter repo and fire up Hardhat’s local node.

git clone https://github.com/yourname/blockchain-voting-demo.git
cd blockchain-voting-demo
npm install
npx hardhat node

Think of it like ordering a pizza: you pick the place, place the order, then wait for the oven to heat up before the first slice arrives.
Lock down who can run an election.

Add a simple role‑based check in Voting.sol so only addresses with the ADMIN_ROLE can call startElection() and closeElection().

function startElection() public onlyRole(ADMIN_ROLE) { … }

It’s similar to giving a restaurant manager the key to the kitchen—only they can open the doors.
Move the contract to a cheaper network.

Deploy to Polygon zkEVM (or another Layer‑2) instead of Goerli to shave off gas costs.

npx hardhat run scripts/deploy.js --network polygonzkevm

Imagine swapping a city‑center cab for a bike‑share: you get to the same destination, but the fare is tiny.

Tools: Hardhat, ethers.js, Metamask.
Tip: Keep the .env file secure; it holds your private keys.
Cheat sheet: npx hardhat test to verify logic before any deployment.

Got stuck or have a cool use‑case? Drop a comment below – I’d love to hear how you’re using a blockchain voting system.

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build a Blockchain-Based Voting System: A Beginner’s Step‑by‑Step Guide

Abdullah Sheikh — Sat, 20 Jun 2026 12:04:14 +0000

Create a secure, transparent voting app on a blockchain from scratch—even if you’ve never coded one before

Before We Start: What You'll Walk Away With

By the end of this guide you’ll be able to spin up a working blockchain voting system from zero to a demo you can show to friends.

First you’ll grasp the three building blocks that keep a voting app honest: the ledger that records each ballot, the smart contract that enforces one‑vote‑per‑person rules, and the front‑end that lets voters cast their choice.

Think of it like setting up a kitchen: you need the fridge (the blockchain) to store ingredients, the recipe (the contract) to tell you what to mix, and the stove (the UI) to actually cook the meal.

Install a local test network, write and deploy a simple voting contract, and hook it up to a minimal web page.
Run through a full voting cycle—register, vote, tally—just like ordering food, confirming the order, and receiving the receipt.
Apply basic hardening steps and get pointers to services that can take your prototype to a production‑grade deployment.
Test network setup: Use ganache-cli or Hardhat to simulate Ethereum on your laptop.
Smart contract basics: Write a Solidity contract that tracks voter eligibility and vote counts.
Front‑end glue: Connect the contract with web3.js or ethers.js to build a simple HTML form.

Security isn’t an afterthought; you’ll learn to lock down private keys, validate inputs, and avoid common pitfalls like replay attacks.

When the tutorial is over you’ll have a sandboxed blockchain voting system you can experiment with, plus a roadmap for scaling it up when you’re ready to go live.

Ready to roll up your sleeves?

What Blockchain Voting Actually Is (No Jargon)

Blockchain voting records each ballot as an unchangeable transaction on a shared ledger, so anyone can see the tally but nobody can rewrite a vote after it’s been cast. The ledger lives on many computers at once, which means there’s no single point that can be hacked or corrupted without the whole network noticing.

Imagine a public Google Sheet that a whole town can edit. Each time you enter a vote, the sheet saves a new row instantly. Once saved, that row is locked—no one can change the number in that cell without every viewer seeing a red flag. That’s the essence of a blockchain voting system: every vote is a permanent entry, and the community of nodes acts as the “viewers” who keep the record honest.

The 3 Mistakes Everyone Makes With Blockchain Voting

Most first‑time attempts trip over the same three pitfalls.

Over‑engineering the consensus algorithm. You could spend weeks building a custom proof‑of‑stake, but a public testnet like Goerli already handles that. It’s like trying to bake sourdough from scratch when a ready‑made pizza dough works just fine.
Storing voter identities in plain text on‑chain. Putting names or IDs directly into a transaction is a privacy nightmare. Think of it as writing your home address on a postcard that anyone can read—once it’s out there, you can’t take it back.
Skipping proper gas‑limit testing. Deploying with a guess‑work limit leads to failed votes when the network spikes. It’s similar to packing a suitcase without checking the airline’s weight rules; you’ll end up paying extra or leaving items behind.
Tool tip: Use hardhat or truffle scripts to simulate gas usage before the live launch.

Cheat sheet:

Consensus: Stick to an existing testnet.
Privacy: Hash or encrypt IDs.
Gas: Run hardhat node --fork and monitor tx.gasUsed.

Avoid these missteps, and your blockchain voting system will stay functional, private, and scalable.

How to Build a Blockchain Voting System: Step‑by‑Step

Let’s get your blockchain voting system up and running, one concrete action after another.

Pick a blockchain. For a quick start, use the Ethereum Goerli testnet. Think of it like choosing a sandbox playground where you can experiment without spending real money.

Set up the toolchain. Install Node.js, then grab Hardhat and the MetaMask browser extension.

Run npm install --save-dev hardhat in a new folder.
Add the MetaMask extension and switch it to Goerli.
Write the smart contract. Create Ballot.sol with three functions: createBallot, addCandidate, and vote. The contract stores only encrypted votes, similar to how a restaurant records orders without exposing the recipe.

pragma solidity ^0.8.0;

contract Ballot {
    struct Candidate { string name; uint256 votes; }
    mapping(uint256 => Candidate) public candidates;
    mapping(address => bool) public hasVoted;
    uint256 public candidateCount;

    function addCandidate(string memory _name) public {
        candidates[candidateCount++] = Candidate(_name, 0);
    }

    function vote(uint256 _id, bytes32 _voteHash) public {
        require(!hasVoted[msg.sender], "Already voted");
        require(_id **Build a minimal front‑end.** Scaffold a React app and connect with `ethers.js`.
- Install `npm i ethers`.
- Use `window.ethereum.request({ method: 'eth_requestAccounts' })` to prompt MetaMask.

- **Test the voting flow.** Open two Chrome profiles, each with its own MetaMask account. Cast votes and watch the UI update, just as you’d check two separate receipts after ordering coffee.

- **Add basic privacy.** Hash voter IDs off‑chain (e.g., `keccak256(abi.encodePacked(voterId))`) and store only the hash on‑chain. This mirrors the way a hotel keeps a guest’s signature but not the full ID visible to everyone.

**Document everything.** Write a concise README that lists:
- **Prerequisites:** Node, Hardhat, MetaMask.
- **Deploy steps:** command line sequence.
- **How to run the front‑end:** `npm start`.

Future contributors will thank you when they need to scale the system.

Now you have a working prototype of a blockchain voting system—time to experiment further.

## A Real Example: Campus Student Council Election

Maya, the tech lead of her campus’ student council, decides to run a quick, transparent election using the blockchain voting system she just built.

- She creates the candidate list in `candidates.json` – “Alex”, “Jordan”, and “Sam”. Think of it like setting up a menu before ordering food.

- She deploys the smart contract to the Goerli testnet with `npx hardhat run scripts/deploy.js --network goerli`. Goerli works like Google Maps’ “preview mode” – safe to test without real money.

- In the React front‑end, Maya swaps the network ID to “goerli” and points the UI to the new contract address.

- She shares the app’s URL (`https://mycampus-vote.netlify.app`) on the campus Slack channel, adding a short note: “Vote here, your ballot is on the blockchain.”

- After the voting window closes, Maya opens Etherscan’s Goerli explorer, pastes the contract address, and clicks “View Transactions”. Each vote appears as a transaction receipt, just like receipts you get after buying coffee.

- **Verify quickly:** filter by the `VoteCast` event to see every ballot.

- **Show transparency:** copy the filtered Etherscan link and pin it in Slack so anyone can audit the tally.

- **Finalize count:** run the `getResults()` function in the contract UI; the numbers match the on‑chain receipts.

Maya’s simple run‑through proves that a blockchain voting system can be set up, shared, and verified without a PhD in cryptography.

## The Tools That Make This Easier

Think of building a blockchain voting system like assembling a DIY pizza: you need the right kitchen tools before the dough even hits the oven.

- **Hardhat (2025)** – Your local sandbox. It spins up a throw‑away Ethereum network, compiles contracts, and runs automated tests. It’s like a kitchen prep station where you can experiment without burning the real thing.

- **Remix IDE** – The browser‑based skillet for Solidity. Write, compile, and debug in seconds, then push the bytecode straight to Hardhat or a testnet. It feels like ordering a custom sandwich online and seeing the ingredients appear instantly.

- **MetaMask Flask** – A test‑net wallet that lets you add any RPC endpoint you like. Use it to simulate voter wallets, just as you would swap out a credit card for a prepaid gift card when testing purchases.

- **Vercel (free tier)** – Deploy your React front‑end with one click, and it automatically serves it over HTTPS. Think of it as a luggage‑locker that ships your suitcase (the UI) to any destination without extra fees.

- **The Graph (hosted service)** – Optional indexer for audit logs. It creates a searchable view of every vote, similar to how Google Maps tags every road so you can find the fastest route later.

Putting these pieces together means you spend less time hunting for missing bolts and more time polishing the voting experience.

## Quick Reference: Blockchain Voting Cheat Sheet

Grab a pen—here’s the whole process you can tick off in a single coffee break.

- Pick a testnet and treat it like a practice kitchen: **Goerli** lets you experiment without real money.

- Set up your tools the way you’d install a coffee maker: install `Node`, `Hardhat`, and add `MetaMask` to your browser.

- Write the ballot contract—think of it as a recipe: `createBallot()`, `vote()`, `tally()` are the ingredients.

Deploy with one command, just like sending an order:

bash
npx hardhat run --network goerli scripts/deploy.js




- Build the UI the way you’d design a restaurant menu: React shows options, `ethers.js` passes the order. For example, *Alice* logs in, sees the candidate list, clicks “Vote”, and the transaction fires.

- Test like a blind taste test: use several MetaMask accounts, hash voter IDs before sending to keep anonymity.

- Push the front‑end to Vercel—think of it as moving from a kitchen counter to a storefront—then share the live link.

- Verify the contract on Etherscan, and hook The Graph for a transparent audit trail, just like checking receipts after dinner.

- **Choose platform → Goerli testnet** – safe sandbox for early runs.

- **Install Node, Hardhat, MetaMask** – your development toolkit.

- **Write Solidity ballot contract** – core logic for create, vote, tally.

- **Deploy with `npx hardhat run --network goerli`** – one‑click launch.

- **Build React UI + ethers.js** – user‑friendly front end.

- **Test with multiple accounts, hash voter IDs** – ensure privacy and correctness.

- **Deploy UI on Vercel, share link** – instant public access.

- **Verify on Etherscan, use The Graph for audit** – full transparency.

Follow this cheat sheet and your blockchain voting system will be ready to demo before the next lunch break.

## What to Do Next

Start by getting your hands dirty with the code you just read.

- **Fork the GitHub repo** and run the demo locally. It’s like ordering a sample dish before committing to a full‑course meal. Clone the repo, `npm install`, then `npm run dev`. If the vote UI pops up, you’re ready to experiment.

- **Add role‑based access control** using OpenZeppelin’s `AccessControl`. Think of it as giving each team member a different key on a shared locker. Install the package, extend your contract with `AccessControl`, and define roles such as `ADMIN_ROLE` and `VOTER_ROLE`. This step tightens security without rewriting the whole app.

- **Migrate to a production‑grade layer‑2** like Polygon zkEVM and plug in zero‑knowledge proofs for true voter anonymity. Imagine moving from a paper map to a GPS that hides your exact route. Deploy your contract to the zkEVM testnet, then integrate a ZK library (e.g., `snarkjs`) to generate proofs that a vote is valid without revealing the voter’s identity.

**Tools & tips:**

- GitHub fork button → quick copy.

- OpenZeppelin docs → ready‑made role templates.

- Polygon docs → one‑click deployment scripts.

What part of building a blockchain voting app are you most excited to tackle?

---

---

## About the Author

**[Abdullah Sheikh](https://abdullah-sheikh.com/)** is the Founder & CEO at [Exteed](https://exteed.com/), where he leads a team of skilled developers specializing in [Web2](https://abdullah-sheikh.com/) and [Web3 applications](https://abdullah-sheikh.com/), [Custom Smart Contracts](https://abdullah-sheikh.com/), and [Blockchain solutions](https://abdullah-sheikh.com/).

With 6+ years of experience, Abdullah has built [CRMs](https://abdullah-sheikh.com/), [Crypto Wallets](https://abdullah-sheikh.com/), [DeFi Exchanges](https://abdullah-sheikh.com/), [E-Commerce Stores](https://abdullah-sheikh.com/), [HIPAA Compliant EMR Systems](https://abdullah-sheikh.com/), and [AI-powered systems](https://abdullah-sheikh.com/) that drive business efficiency and innovation.

His expertise spans [Blockchain](https://abdullah-sheikh.com/), [Crypto & Tokenomics](https://abdullah-sheikh.com/), [Artificial Intelligence](https://abdullah-sheikh.com/), and [Web Applications](https://abdullah-sheikh.com/); building reliable and smooth web apps that fit the client’s goals and requirements.

📧 [info@abdullah-sheikh.com](mailto:info@abdullah-sheikh.com) · 🔗 [LinkedIn](https://www.linkedin.com/in/-abdullah-sheikh/) · 🌐 [abdullah-sheikh.com](https://abdullah-sheikh.com/)

How to Seamlessly Integrate Stripe Payments Into Your Web App

Abdullah Sheikh — Fri, 19 Jun 2026 12:03:40 +0000

Step‑by‑step guide to add, test, and launch Stripe checkout in any web application

Before We Start: What You'll Walk Away With

When you finish this guide you’ll have a working Stripe checkout button that spins up a payment intent, then tells you whether the payment succeeded or failed.

You’ll also know exactly where the publishable and secret API keys belong, how to lock down webhooks so only Stripe can talk to you, and how to run every scenario in Stripe’s sandbox without touching real money.

Every snippet you see is ready to drop into a typical Node.js or Python backend – no extra scaffolding required.

Copy‑paste the checkout button code and see a live payment flow in seconds.
Store keys in environment variables, just like you’d keep a house key in a safe, then reference them in your server.
Set up a webhook endpoint, verify signatures, and watch Stripe ping you like a delivery driver confirming a package.
Tools: Stripe Dashboard, stripe-cli, Node express or Python Flask.
Tips: Use .env files for local testing; switch to real keys only after you’ve confirmed the sandbox flow.

Cheat sheet:

STRIPE_PUBLISHABLE_KEY – public, embed in HTML.
STRIPE_SECRET_KEY – server only, create intents.
STRIPE_WEBHOOK_SECRET – verify inbound events.

Think of this as packing a suitcase: you place the essential items (keys, code, webhook) in the right compartments, zip it up, and you’re ready to travel to production.

Ready to see the first line of code?

What Stripe Payments Actually Is (No Jargon)

Stripe is a payment gateway that lets you accept credit cards, Apple Pay, Google Pay and dozens of other methods without ever touching the raw card numbers yourself. Think of it as the “cash register” you plug into your online store: you tell it the sale amount, it talks to the banks, and then it hands you back a success or failure signal.

Because Stripe handles the sensitive data, you stay out of PCI‑SS compliance nightmares. It’s like ordering food through a delivery app – you pick the dish, the app sends the order to the kitchen, and you get a notification when it’s ready, while the kitchen never sees your credit‑card details.

In practice, integrating Stripe means adding a tiny snippet of JavaScript to collect payment info, sending that token to your server, and letting Stripe decide if the charge goes through. The flow is:

Customer clicks “Buy” and enters card data.
Stripe.js creates a one‑time token and returns it to your page.
Your backend receives the token and asks Stripe to charge the amount.
Stripe replies with succeeded or an error, and you update the UI.

This is all you need to know before we dive into the actual code. Let’s get that cash register humming.

The 3 Mistakes Everyone Makes With Stripe Integration

Skipping the basics will bite you hard once real money starts flowing.

Putting secret API keys in client‑side code. It’s like leaving your house key under the welcome mat—anyone can walk in. Store sk_test_… or sk_live_… on the server, then let the frontend call a secure endpoint that talks to Stripe.
Skipping webhook verification. Think of a delivery driver shouting “Your pizza is here!” without a receipt. Without checking the Stripe-Signature header, anyone could post a fake payment_intent.succeeded event and grant access without paying.
Going live before testing the whole flow. It’s like driving off a highway without ever testing the brakes. Deploying live keys before you’ve run through test mode, simulated refunds, and edge‑case failures means you’ll discover costly bugs with real customers.

Keep these three pitfalls out of your checklist and the integration will stay clean and secure.

How to Integrate Stripe Payments: Step‑By‑Step

Create a Stripe account and copy the test Publishable key and Secret key. Think of it like signing up for a new bank account before you can write checks.

Install the SDK for your stack.

Node:

npm install stripe

Python:

pip install stripe

It’s the same as adding a new app to your phone so you can use its features.

Set up a server endpoint that creates a PaymentIntent and returns its client_secret. This is like a kitchen ticket that tells the chef what to cook and how much to charge.
Build a front‑end checkout button that calls stripe.confirmCardPayment(client_secret). The button acts like the “Place Order” button at a restaurant – it sends the ticket to the kitchen.

Configure a webhook endpoint and verify Stripe’s signature. Inside, handle the payment_intent.succeeded event.

Verify signature with stripe.webhooks.constructEvent.
Update your database, send a receipt, unlock the product.

Think of the webhook as a delivery driver ringing your doorbell when the food arrives.

Test the whole flow using Stripe’s test cards (e.g., 4242 4242 4242 4242). Once everything works, swap the test keys for live ones. It’s like doing a dress rehearsal before opening night.

Now you have a reusable, production‑ready payment flow you can drop into any new web app.

A Real Example: SaaS Startup “PixelPro” Adds Monthly Subscriptions

Maya, the CTO of PixelPro, drops a fresh /create-subscription route into her Node server and passes {amount: 1999, currency: 'usd'} to Stripe, just like you’d tell a bartender the price of a craft cocktail.

Node returns a client_secret. Maya sticks that value into the React state and mounts a Stripe Elements CardElement on the page.

When a user clicks “Subscribe”, the front‑end runs:

stripe.confirmCardPayment(client_secret, {
  payment_method: { card: elements.getElement(CardElement) }
});

Think of this as pressing “Order” on a food‑delivery app – the request travels to Stripe, which checks the card and replies with a receipt.

On the back‑end Maya adds a /webhook endpoint. She reads the stripe-signature header, verifies it with stripe.webhooks.constructEvent, and, on payment_intent.succeeded, updates the subscriptions row in PostgreSQL.
Testing tip: Use the test card 4242 4242 4242 4242. Stripe will fire the webhook instantly, letting Maya watch the DB row flip from “pending” to “active”.
Live rollout: Swap the secret keys from test to live, redeploy, and the same flow now processes real dollars.

Cheat sheet:

amount: 1999 → $19.99 monthly
payment_intent.succeeded → mark subscription as active
Store client_secret only in memory, never in a cookie.

That’s a complete, production‑ready example of how to integrate Stripe payments and watch your SaaS start billing on autopilot.

The Tools That Make This Easier

Think of these tools as the kitchen gadgets that keep your Stripe integration from turning into a mess.

Stripe Dashboard – the control panel where you can see your API keys, run test payments, and set up webhooks, just like checking the menu before ordering.
ngrok (free tier) – creates a public tunnel to your local server so Stripe can hit your webhook endpoint, similar to giving a delivery driver a temporary road map to your house.
Postman – lets you fire off requests to /create-payment-intent without building a UI, like using a phone to order food instead of walking to the restaurant.
Vite + React – spins up a lightning‑fast dev server and hot‑reloads Stripe Elements, as handy as a portable stove when you’re camping.
Sentry (free plan) – catches and reports webhook errors in production, acting like a smoke alarm that warns you before the kitchen catches fire.

When you’re ready to ship, grab the Stripe Dashboard first to copy your live and test keys. Then start ngrok http 3000 so the webhook URL looks like https://abcd1234.ngrok.io/webhook. Use Postman to verify the endpoint returns 200 before wiring the front‑end.

For the UI, scaffold a Vite project with npm create vite@latest my-app --template react, install @stripe/stripe-js and @stripe/react-stripe-js, and you’ll have a ready‑to‑use checkout form in minutes.

Finally, add a Sentry DSN to your server config; any uncaught webhook exception will show up in the dashboard, giving you a quick fix before customers notice.

These five tools turn a tangled payment setup into a smooth, repeatable process.

Quick Reference: Stripe Integration Cheat Sheet

Here’s everything you need at a glance, like a cheat sheet you can pin to your monitor.

Keys – Grab the test pk_test_… and sk_test_… keys, then swap to live keys once you’re ready. Think of it as switching from a practice golf club to the real one before the tournament.

Server – Create a PaymentIntent:

const intent = await stripe.paymentIntents.create({
  amount: 1999,
  currency: 'usd',
  metadata: {order_id: '6735'}
});

Return the client_secret to the client. It’s like a restaurant kitchen printing a ticket that the waiter later hands to the guest.
Client – Load Stripe.js, init with your publishable key, then call confirmCardPayment:

const stripe = Stripe('pk_test_...');
stripe.confirmCardPayment(clientSecret, {
  payment_method: {card: cardElement}
});

This step works like Google Maps giving turn‑by‑turn directions once you’ve entered the destination.
Webhook – Verify the signature and react to payment_intent.succeeded:

const event = stripe.webhooks.constructEvent(
  req.body, req.headers['stripe-signature'], endpointSecret
);
if (event.type === 'payment_intent.succeeded') {
  // fulfill order
}

Imagine a security guard checking a badge before letting you into a backstage area.

Testing – Use Stripe’s test cards (e.g., 4242 4242 4242 4242), run ngrok to expose your local webhook, and confirm everything in the Dashboard. It’s like a chef tasting dishes before opening the restaurant.
Go Live – Flip to live keys, point the webhook URL at your production domain, and turn off test mode. This is the final suitcase check before boarding a flight.

Keep this list handy and you’ll integrate Stripe payments without a hitch.

What to Do Next

Grab the repo, swap the demo keys for yours, and give the checkout a quick spin on your machine.

Duplicate the repo, replace STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY in .env, then run npm run dev (or python app.py). Think of it like ordering a test meal at a restaurant—you want to taste everything before the grand opening.
Add a subscription‑plan table to your database. Store your internal plan IDs and copy them into the Stripe metadata field when you create a subscription. It’s the same as labeling each suitcase with a destination tag so you know exactly where every piece belongs.
Implement retry logic for failed payments and hook up email alerts via SendGrid or Mailgun. Use Stripe’s payment_intent.payment_failed webhook, retry up to three times, then fire an alert. This works like a GPS that recalculates the route when you hit traffic, then notifies you if you’re stuck.
Tip: Keep a scripts/retry.sh helper that you can call from your webhook handler.
Cheat sheet: stripe.paymentIntents.retrieve(id) → check status → if requires_action retry.
Tool: Set up a SendGrid API key and a simple sendEmail(to, subject, body) wrapper.

Got stuck on a webhook error or need help customizing the UI? Drop a comment below – happy to help!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build Automated Email Campaigns with n8n and Gmail in 8 Simple Steps

Abdullah Sheikh — Thu, 18 Jun 2026 12:03:43 +0000

Create, schedule, and trigger personalized Gmail campaigns automatically using n8n without writing code

Before We Start: What You'll Walk Away With

By the end of this guide you’ll be able to spin up a trigger‑driven email campaign that feels personal even when it sends hundreds of messages.

You’ll know how n8n talks to Gmail the way a waiter takes your order and relays it to the kitchen.

And you’ll walk away with a reusable workflow template you can tweak for newsletters, drip sequences, or lead‑nurturing—no code required.

You’ll grasp the core building blocks of n8n and the Gmail node, just like learning the basic ingredients before cooking a dish.
You’ll assemble a fully functional, trigger‑based campaign that sends customized emails at scale, similar to setting a GPS route that automatically adjusts for traffic.
You’ll save the workflow as a template, ready to be repurposed whenever you need a new outreach series, much like packing a suitcase with versatile outfits.
Quick tip: Test each node with sample data before activating the whole flow.
Tool check: Make sure your Gmail account has Allow less secure apps disabled; n8n uses OAuth2.
Cheat sheet: Trigger → Gmail: Send Email → Set Variables → End

Now that you know what you’ll achieve, let’s get the basics set up so you can start building your first automated email campaigns with n8n.

What n8n Email Automation Actually Is (No Jargon)

Think of n8n as a visual, open‑source workflow engine that lets you stitch together apps like Gmail without writing a single line of code.

Each piece you drop onto the canvas is a node. A node can pull data, change it, or hand it off to the next step. When you hit “activate”, the nodes fire in order, moving information along automatically.

Picture a conveyor belt in a bakery. The first station slices the dough, the next adds filling, another applies icing, and the final robot packages the treat. You set the recipe once, then the belt keeps churning out pastries without you lifting a finger. In n8n, the dough is your contact list, the filling is the email template, and the icing is the personalized merge tags—each node adds its part, and the whole line runs by itself.

Because it’s visual, you see the whole process at a glance, and you can pause, rearrange, or sprinkle in extra steps (like logging to a spreadsheet) as your campaign evolves.

Open‑source: you can host it yourself or use the cloud version.
Node‑based: Gmail, Google Sheets, webhook, delay—everything is a plug‑and‑play block.
Automation: once the start node fires, the belt never stops until you tell it to.

That’s what automated email campaigns n8n look like in plain English—just a configurable conveyor that delivers personalized emails on autopilot.

The 3 Mistakes Everyone Makes With n8n Email Automation

Most people hit the wall not because n8n is hard, but because they set it up like a one‑size‑fits‑all recipe.

Hard‑coding email addresses or subjects. It’s like ordering a pizza with the same topping for every slice – you lose the personal touch. Plug a splitInBatches node and pull the address and subject from a spreadsheet or Google Sheet so each line feels custom.
Skipping a delay or rate‑limit node. Imagine driving through a red light; traffic control will stop you. Gmail works the same way. Add a Wait node (e.g., 30 seconds) or set maxRequestsPerMinute to keep your account out of the spam folder.
Ignoring error handling. It’s like packing a suitcase without checking if the zipper works – one snag and the whole trip stalls. Use an If node to catch bounce codes and route them to a log file or Slack alert so the workflow keeps running.
Tip: Store dynamic fields in a Google Sheet; n8n reads them on each run.
Tool: The Rate Limit node is your traffic light for Gmail.
Cheat sheet: email !== "" && subject !== "" before the Send Email node.

Fix these three slip-ups and your automated email campaigns n8n will run smooth as a well‑timed coffee order.

How to Create Automated Email Campaigns with n8n and Gmail: Step‑By‑Step

Kick off by signing up for n8n Cloud (or spin up a local instance) and link your Gmail through the OAuth flow – think of it like handing the barista your loyalty card so they can charge the right account.

Drop a Cron trigger node onto the canvas. Set it to fire every weekday at 9 AM, just like scheduling a daily coffee delivery.
Pull the contacts from a Google Sheet with the Google Sheets node. This is your address book, similar to opening a spreadsheet of dinner guests.
Add a Set node and map the sheet columns to variables – firstName, email, customTag. It’s like labeling each suitcase before you pack.

Insert a Function node to craft a personalized subject and body. Use template literals, e.g.:

return {
  subject: `Hey ${items[0].json.firstName}, check this out!`,
  body: `Hi ${items[0].json.firstName},

We thought you'd love our new feature: ${items[0].json.customTag}.`
};

Meet Alex, a freelance designer. For Alex, the subject becomes “Hey Alex, check this out!” and the body mentions the specific tag Alex signed up for.

Hook up a Gmail node, map the subject, body, and email fields, and toggle “HTML” if you need rich formatting.
Place a Delay node (2 seconds) after each send. This mimics pacing yourself between orders at a busy café, keeping you under Gmail’s rate limits.
Add an Error Trigger node that logs failures to a Slack channel or another Google Sheet – your safety net for missed deliveries.
Activate the workflow. Run a test with a single row first; once it’s smooth, let the campaign roll out to the full list.
Tip: Keep your template short and tweak the delay if you hit Gmail’s send limits.
Cheat sheet: Cron → Google Sheets → Set → Function → Gmail → Delay → Error Trigger → Activate.

A Real Example: Onboarding New SaaS Users

Maya, a product marketer at a B2B SaaS startup, just dropped a Google Sheet called New Users into n8n. The sheet has name, email, and startDate columns.

n8n reads the sheet with the Google Sheets node and turns each row into a JSON item.
The Function node creates the three email payloads. It builds the subject with a template like Welcome, {{ $json.name }}! and injects $json.startDate into the body so the message feels personal.
Each payload is passed to a Gmail node that schedules the send:
Day 0 – Welcome email (sent immediately).
Day 1 – Tutorial link (delay of 24 hours).
Day 3 – Case‑study (delay of 72 hours).

Here’s the tiny script Maya uses in the Function node:

const emails = [
  {delay:0, subject:`Welcome, ${$json.name}!`, body:`Hi ${$json.name}, your account starts ${$json.startDate}.`},
  {delay:1, subject:`Getting started, ${$json.name}`, body:`Here’s a quick tutorial…`},
  {delay:3, subject:`Success story for ${$json.name}`, body:`Check out this case‑study…`}
];
return emails.map(e=>({
  json:{...$json, subject:e.subject, body:e.body, delay:e.delay}
}));

When the workflow runs, Maya keeps an eye on the Slack #n8n-errors channel. Within minutes she sees a single “bounced” alert, opens the sheet, and removes the offending row. The rest of the drip continues without a hitch.

That’s automated email campaigns n8n in action – a quick set‑up, a few clicks, and Maya’s onboarding flow runs itself.

The Tools That Make This Easier

Think of building an automated email campaign like ordering a combo meal: you pick the main, add the sides, and the kitchen handles the rest.

n8n Cloud – the main dish. The free tier gives you 2,000 executions each month, enough to test a full outreach loop without paying a cent.
Google Workspace – the side dishes. Use Google Sheets to store contacts like a spreadsheet menu, and Gmail to serve the emails directly from your inbox.
Slack (free) – the kitchen timer. Set up a webhook so n8n posts error alerts to a channel, letting you catch problems faster than a missed order.
Zapier (free tier) – the optional delivery driver. When n8n doesn’t yet support an app you need, a quick Zap can pull that data into your workflow.
Loom – the walkthrough video. Record a 60‑second tour of your n8n setup and share it with teammates, just like showing a recipe to a new cook.

These tools keep the whole process low‑cost and easy to tweak, so you can focus on writing compelling copy instead of wrestling with code.

Quick Reference: n8n Gmail Automation Cheat Sheet

Grab this list whenever you need to rebuild the workflow or hand it off to a teammate.

📅 Trigger – Cron node (schedule) – Think of it like setting an alarm clock; n8n wakes up at the exact time you choose.
📄 Data source – Google Sheets → Set node (map columns) – Like pulling ingredients from a pantry and placing them on the prep table, the Set node lines up each column for the recipe.
✍️ Personalization – Function node (template literals) – Similar to customizing a coffee order, the function swaps {firstName} or {company} into your template.
📧 Send – Gmail node (HTML enabled) – This is the delivery driver, handing over the freshly packed email to Gmail’s mailbox.

⏱️ Rate limit – Delay node (2‑5 s)

Example: Alex, a freelance designer, wants to avoid Gmail’s “Too many messages” warning. Set the Delay node to 3000 ms, so each email pauses three seconds before the next one leaves.
⚠️ Errors – Error Trigger → Slack or Sheet – Like a fire alarm, this node pings you instantly if something goes wrong, routing the alert to Slack or appending a row in a “fails” sheet.
✅ Test – Run with 1 row, check logs, then activate – Treat it like a test drive: send one sample, watch the console, and only then hit “Activate” for the full list.

Keep this cheat sheet handy; it’s the quick‑reference map for building automated email campaigns with n8n.

What to Do Next

Start by cloning the template, swapping in your Gmail credentials, and firing off a single test email to yourself.

Duplicate & test – Think of this like ordering a sample dish before committing to the whole menu. In n8n, click “Duplicate,” paste your Gmail OAuth token, then hit “Execute Node.” If the email lands in your inbox, you’re ready.
Segment & switch – Expand the source list into a Google Sheet that groups contacts by industry or buyer stage. Add a “Switch” node so each segment receives a tailored template, just as a waiter would hand out different menus to vegans and meat‑eaters.
Build a drip – Chain a series of Cron triggers and drop a “Wait Until” node between them. This lets you space follow‑ups like planning stops on a road trip: you set the exact mileage (or days) before the next message fires.
Tip: Keep a cheat sheet of node IDs and sheet ranges in a sticky note for quick reference.
Tool: Use n8n’s built‑in Set node to insert dynamic variables such as {{ $json["firstName"] }} for that personal touch.

Give those steps a spin and see how your automated email campaigns n8n start to run themselves.

Got stuck or discovered a clever tweak? Drop a comment below – I’d love to hear how you customized the flow!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build a Personal AI Assistant Using Open Source Tools

Abdullah Sheikh — Wed, 17 Jun 2026 12:04:42 +0000

Create a fully functional, customizable AI helper from scratch with free software you can deploy today

Before We Start: What You'll Walk Away With

You’ll finish this guide with a clear mental map of how a personal AI assistant hangs together, just like a kitchen layout shows where the stove, sink, and fridge belong.

Next, you’ll have the know‑how to pull together open‑source language, speech, and automation engines, configure them, and stitch them into a single running service—think of it as assembling a DIY smart speaker from off‑the‑shelf parts.

Finally, you’ll launch a working prototype that can answer casual questions, pull events from your calendar, and run your own scripts on command, similar to having a reliable personal secretary who never asks for a raise.

Understand the architecture: identify the language model, voice interface, and task executor, and see how data flows between them.
Install and configure each component: download models, set up virtual environments, and connect them with simple API bridges.
Run a prototype: issue voice or text queries, watch the assistant fetch calendar entries, and trigger custom scripts like a home‑automation hub.
Language core: an open‑source transformer that handles text generation.
Speech layer: a whisper‑style model for transcription and a text‑to‑speech engine for replies.
Automation glue: a lightweight task runner that executes Python or shell scripts on demand.
Cheat sheet: git clone the repo, conda create -n ai-assist python=3.10, then pip install -r requirements.txt.
Tip: Keep your models in a ~/models folder and point each service to it with an environment variable.
Tip: Test each piece separately before wiring them together; it’s easier to debug a single component than a tangled system.

By the end, you’ll have a private, expandable assistant ready to take on everyday tasks.

What a Personal AI Assistant Actually Is (No Jargon)

Personal AI assistant is simply a program you run on your own computer that listens to voice or reads text, runs an AI model locally, and then does something for you – sending an email, opening a file, or adjusting a setting.

Imagine it as a virtual coworker you can hand‑off tasks to, just like you would tell a real teammate, “Can you pull the latest sales report?” The difference is you talk to it through a microphone or a chat window, and it executes the request on your device without contacting external services.

Think of the assistant as a smart‑home hub, but instead of turning lights on, it manages your calendar, drafts replies, or runs a data‑cleanup script. You set up the rules, give it access to the apps you use, and it becomes a personalized productivity layer that never leaves your network.

Because everything lives on your machine, you keep full control over privacy and can add new skills whenever you like – a bit like adding a new plug‑in to your favorite IDE.

In short, a personal AI assistant is a locally hosted, voice‑or‑text‑driven agent that runs AI models and performs actions on your devices, giving you a private, extensible helper for everyday work.

The 3 Mistakes Everyone Makes With Personal AI Assistants

Most people hit the same roadblocks before their personal AI assistant actually works.

Chasing the latest giant model – It’s like ordering a deluxe pizza when you only need a snack. You spend hours downloading a massive model that never fits on your laptop, then watch it choke on simple queries. Pick a lightweight, locally runnable model such as distilbert-base-uncased or llama‑7b‑q4 and upgrade only when you truly need more horsepower.
Ignoring data privacy – Storing API keys or passwords in plain text is like leaving your house keys on the kitchen counter. A single slip and anyone can walk in. Keep secrets in an encrypted .env file and load them with python-dotenv or use a password manager that writes to the environment at runtime.
Building a monolithic script – Imagine packing a suitcase for a week’s trip and throwing everything in one bag. When one item breaks, the whole trip is ruined. Split your assistant into clear modules—speech‑to‑text, intent routing, response generation, and output handling—so you can swap out a component without rewriting the entire codebase.

Fix these early, and you’ll spend more time chatting and less time untangling.

How to Build a Personal AI Assistant: Step‑By‑Step

Pick a model and spin up an inference server. Grab Llama-3-8B-Open-Chat and run it with Ollama or vLLM. Think of it like ordering a custom pizza: you choose the toppings (the model) and the kitchen (the server) bakes it right on your machine.
Plug in speech‑to‑text. Install Whisper.cpp and point it at your microphone. It works offline, like a personal stenographer that never takes a coffee break.
Add a voice for replies. Set up Open-Voice-Engine for text‑to‑speech. Now your assistant can talk back, similar to a GPS that reads directions aloud instead of just displaying them.
Lay down an automation layer. Pull in LangChain-Lite to map user intents to actions. It’s the “Google Maps” of your workflow, routing requests to the right destination.
Write a tiny skill library. Create Python functions for things like lookup_calendar(), draft_email(), or search_files(). Each function is a “pocket tool” you can call on demand.
Tie everything together. Use a docker-compose.yml or a systemd unit to launch the model, Whisper, voice engine, and automation framework together. This is the suitcase you pack once and carry everywhere.
Lock down credentials. Store API keys and passwords with Bitwarden CLI and enable TLS on any local HTTP endpoints. Think of it as keeping your diary in a safe.
Cheat sheet:
docker compose up -d – start the stack
bitwarden login – authenticate the vault
curl -k https://localhost:8000/chat – test the API

Now you have a fully local personal AI assistant ready to expand.

A Real Example: Sarah’s Meeting‑Prep Assistant

Sarah, a product manager, tells her AI, “Hey AI, prep my 10 AM meeting,” and watches the whole routine unfold.

Voice capture: whisper converts her spoken request into text.
LangChain routes the intent to the “calendar skill.”
The skill calls the Google Calendar API, pulls the 10 AM event, and returns the title, attendees, and location.
Llama‑3 crafts agenda bullets based on the event data.
The result is sent to Open‑Voice‑Engine, which reads the brief back to Sarah.
Calendar skill setup: create a service account, download credentials.json, and grant read access to the calendar.
Agenda generator: a tiny Python function that formats the meeting details into bullet points.
Voice command binding: add “prep my * meeting” to the LangChain prompt map.

Here’s the Python snippet Sarah drops into calendar_skill.py:

import os
from googleapiclient.discovery import build
from datetime import datetime, timedelta

def get_next_meeting():
    creds = None
    # assumes GOOGLE_APPLICATION_CREDENTIALS env var points to credentials.json
    service = build('calendar', 'v3', credentials=creds)
    now = datetime.utcnow().isoformat() + 'Z'
    events = service.events().list(
        calendarId='primary', timeMin=now,
        maxResults=1, singleEvents=True,
        orderBy='startTime').execute().get('items', [])
    if not events:
        return None
    e = events[0]
    return {
        'title': e['summary'],
        'time': e['start'].get('dateTime', e['start'].get('date')),
        'attendees': [a['email'] for a in e.get('attendees', [])]
    }

def format_agenda(meeting):
    bullets = [
        f"**Topic**: {meeting['title']}",
        f"**When**: {meeting['time']}",
        f"**Who**: {', '.join(meeting['attendees']) or 'No invites'}",
        "‑ Review last sprint metrics",
        "‑ Prioritize upcoming features"
    ]
    return "
".join(bullets)

When Sarah speaks, Whisper hands the text to LangChain, which triggers get_next_meeting(), feeds the result into format_agenda(), and lets Llama‑3 add a short intro. Open‑Voice‑Engine then reads the polished brief, giving Sarah a ready‑to‑go meeting prep without leaving her desk.

The Tools That Make This Easier

Here’s the handful of utilities that turn a messy DIY project into a kitchen‑counter‑simple workflow.

Ollama – Think of it as a local restaurant where you can order any LLM on the menu, from Llama‑3 to Mistral, without leaving your house. Install the binary, drop the model files in ~/.ollama/models, and start the server with ollama serve. Your personal AI assistant talks to Ollama just like a phone calls a local pizzeria.
Whisper.cpp – This is the voice‑to‑text equivalent of a pocket notebook that never needs Wi‑Fi. Compile the single‑file C++ program, feed it an audio clip, and it spits out a transcript instantly. No Python, no Docker, just whisper.cpp -m tiny.en.bin -f input.wav.
Open‑Voice‑Engine – Imagine a family of actors ready to read your script on a CPU‑only stage. Install with pip install open-voice-engine and select a voice profile in your code; the engine renders speech in real time, perfect for replying on the fly.
LangChain‑Lite – This is the Google Maps of LLM workflows, charting routes without charging tolls. Import the library, define a Chain of prompts, and run it locally. It gives you the same composability as the full LangChain stack but without the heavyweight dependencies.
Bitwarden CLI – Treat it like a secure suitcase for your API keys. Store a token with bw login, then retrieve it in a script via bw get item my‑assistant‑token. No plaintext files, no accidental leaks.

Cheat sheet

Start Ollama: ollama serve
Transcribe audio: whisper.cpp -m base.en.bin -f note.wav
Synthesize speech: open-voice-engine --voice en_female --text "Ready"
Run a LangChain‑Lite chain: python run_chain.py
Fetch secret: bw get item assistant‑key

With these tools in place, building a personal AI assistant feels as straightforward as assembling a suitcase for a weekend trip.

Quick Reference: Personal AI Assistant Cheat Sheet

Think of your personal AI assistant like a restaurant order: you speak, the kitchen prepares, and the server delivers the response.

Architecture: STT → LLM → Intent Router → Skills → TTS. Like a food‑prep line, each stage hands off a clean dish.
Core stack: Ollama (model host), Whisper.cpp (speech‑to‑text), Open‑Voice‑Engine (text‑to‑speech), LangChain‑Lite (orchestration). These are your kitchen appliances.

7‑step build:

Pick a lightweight Ollama model (e.g., phi-3-mini).
Set up Whisper.cpp for offline STT.
Install Open‑Voice‑Engine for TTS.
Wire the components with LangChain‑Lite (or a simple Flask router).
Write modular skills as independent functions.
Secure secrets using .env and OS‑level permissions.
Containerize with Docker and run locally.

Common pitfalls:

Choosing a model that exceeds RAM – like ordering a banquet for a two‑person table.
Storing API keys in plain text – leaving the kitchen door unlocked.
Bundling all skills into one file – makes debugging as hard as finding a single spice in a mixed bulk bag.

First skill example: Calendar lookup for Alice, a product manager who wants to ask, “When is my next sprint demo?”

def get_next_meeting():
    import os, requests
    token = os.getenv("GOOGLE_TOKEN")
    resp = requests.get(
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        headers={"Authorization": f"Bearer {token}"},
        params={"maxResults":1,"orderBy":"startTime","singleEvents":True}
    )
    return resp.json()["items"][0]["summary"]

Add this function to the Intent Router and map the phrase “next meeting” to get_next_meeting().

Keep this cheat sheet handy; it’s the quick‑order menu for your personal AI assistant.

What to Do Next

Grab the starter repo, hit docker-compose up, and you’re chatting with your own personal AI assistant in minutes.

✅ Easy: Fork the GitHub template yourname/personal-ai-assistant. Clone it, run docker-compose up, and open http://localhost:8000. Think of it like ordering a ready‑made sandwich – you choose the bread and it arrives hot.
🚀 Medium: Add a new skill. Copy the langchain-lite example, rename the folder to email_summarizer, and edit skill.py to call your mail API. It’s like swapping one topping for another on a pizza you already baked.
💪 Hard: Move the whole stack to a Raspberry Pi 5. Install Docker on the Pi, push the images, and expose a webhook at https://your‑pi.local/webhook. Then link that URL to a mobile shortcut. This is the “pack your luggage for a road trip” step – you’re making the assistant travel with you wherever you go.
Tools: Git, Docker, LangChain‑Lite, Pi OS.
Tips: Keep .env files out of the repo; use docker secret for API keys.
Cheat sheet: git clone … → docker compose up -d → curl -X POST …

Got stuck or have a cool skill idea? Drop a comment below – I’ll help you troubleshoot!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Deploy a Next.js App to a Self-Hosted Server Without Hassle

Abdullah Sheikh — Tue, 16 Jun 2026 12:04:03 +0000

Deploy your Next.js site to your own Linux server step‑by‑step and keep it running smoothly

Before We Start: What You'll Walk Away With

When you finish this guide you’ll have a fully‑functional Next.js site answering requests at your own domain name.

You’ll be able to point Nginx at your Node process the same way you’d set a restaurant’s front door to the kitchen, then hand out HTTPS certificates from Let’s Encrypt like a maître d’ handing out napkins.

PM2 will keep the app alive and restart it automatically, just like a reliable dishwasher that never lets a plate slip through.

Everything works on a fresh Ubuntu or Debian VPS, and you only need the command line you already use for git pulls and npm installs.

Install system dependencies and your code.
Configure Nginx as a reverse proxy.
Obtain and install a free SSL certificate.
Set up PM2 to manage the Node process.
Verify the site is live and secure.
Prerequisite: SSH access to a VPS with root or sudo rights.
Tools: nginx, certbot, pm2, git, node/npm.
Tip: Keep a copy of your nginx config file; you’ll revert to it if something goes wrong, just like you’d keep a spare key.

By the time you close the terminal you’ll have a production‑ready deployment you can point friends at and trust to stay up.

What Deploying a Next.js App Actually Is (No Jargon)

Deploying a Next.js app simply means taking the code you ran locally, copying it to a remote Linux box, and configuring that box so the site stays online and responds to visitors.

First you run npm run build to turn your React pages into static files and server‑side bundles. Then you move the .next folder, package.json, and any static assets to the VPS. The server needs Node installed, a process manager like pm2 to keep the app alive, and a web server (usually Nginx) that hands incoming HTTP requests to your Node process.

Think of your app as a restaurant kitchen. The build step is the recipe you write down—without it the chef can’t cook. The VPS is the dining room where guests sit; it must be clean, have power, and stay open. The reverse proxy (Nginx) and SSL are the waitstaff and health inspector: they take orders, deliver plates securely, and make sure everything complies with safety standards.

When the kitchen (your Next.js code) follows the recipe, the waitstaff (Nginx) routes each order (request) to the right chef (Node process), and the health inspector (SSL) guarantees the food travels over a safe, encrypted path. If any part fails—say the kitchen closes early—the guests leave disappointed, just like a site that crashes or shows “not secure”.

In short, deploy next.js self hosted is about moving the recipe, setting up the dining room, and hiring the right staff so the experience runs smoothly every night.

The 3 Mistakes Everyone Makes With Next.js Deployments

Here’s what trips most people up when they try to deploy next.js self hosted for the first time.

Skipping next build on the server. It’s like ordering a pizza and forgetting to bake it before delivery – the crust arrives, but there’s no cheese. Without running next build on the VPS, the .next folder never gets populated, so static assets and server‑side bundles are missing. The result? 404s on every page that should be pre‑rendered.
Running the default Node server directly. Think of it as driving a sports car on city streets without traffic lights – you’ll get somewhere, but you’ll hit a lot of red lights (slow performance) and you’ll have no protection from the elements (no HTTPS). A reverse proxy like Nginx or Caddy handles SSL termination and serves static files efficiently, leaving Node to focus on rendering React.
Not installing a process manager. Imagine packing a suitcase for a trip and leaving the zipper open; a sudden gust will blow everything away. Without a tool such as pm2 or systemd, your app disappears after a reboot or after an uncaught error, forcing you to manually restart it each time.
Quick fix: Add npm run build && npm start to your deployment script.
Proxy tip: Use Nginx with proxy_pass http://localhost:3000; and enable ssl_certificate directives.
Stay alive: Install pm2 and run pm2 start npm --name "next-app" -- start, then pm2 save.

Fix these three, and your Next.js app will stay up, run fast, and actually show the pages you built.

How to Deploy a Next.js App: Step‑by‑Step

Grab a fresh Ubuntu 22.04 VPS, log in, and create a regular user so you don’t run everything as root.

Create a non‑root user and give it sudo rights.

adduser deployer
usermod -aG sudo deployer

Switch to that user, install nvm, then pull the LTS Node version.

su - deployer
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v
npm -v

Clone your repository into the web directory and install exact dependencies.

git clone https://github.com/yourname/your-app.git /var/www/your-app
cd /var/www/your-app
npm ci

Build the production bundle – think of it like packing a suitcase before a trip.

npm run build

Run the app with PM2. Imagine PM2 as a reliable restaurant manager who keeps the kitchen open 24/7.

npm i -g pm2
pm2 start npm --name "my-next" -- start

Save the process list and make PM2 start on boot, just like setting an alarm that never forgets.

Install Nginx, then create a server block that forwards traffic to http://localhost:3000.

sudo apt-get update
sudo apt-get install -y nginx
sudo nano /etc/nginx/sites-available/your-app

Inside, set proxy_pass http://localhost:3000;
Enable with ln -s /etc/nginx/sites-available/your-app /etc/nginx/sites-enabled/
Test and reload: nginx -t && systemctl reload nginx

Secure the site with a free Certbot certificate – it’s like getting a lock for your front door.

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Verify everything works, set up automatic renewal, and keep an eye on logs.

Renewal: sudo certbot renew --dry-run
PM2 logs: pm2 logs
Visit https://yourdomain.com to confirm the app serves correctly.

Now your Next.js app is live, managed, and ready for traffic.

A Real Example: Deploying a SaaS Dashboard for “Acme Corp”

Maya just finished coding the Acme Corp dashboard and now it’s time to push it to her DigitalOcean droplet.

She clones the repo:

git clone https://github.com/maya/acme-dashboard.git
cd acme-dashboard

Think of this like picking up a take‑out order before heading home.

Install dependencies and build the production bundle:

npm ci
npm run build

Start the app with PM2 so it survives crashes and reboots:

pm2 start npm --name "acme-dashboard" -- start

She then runs pm2 status and sees the process listening on port 3000 – like checking that the kitchen has finished cooking.

Configure Nginx to act as a reverse proxy for acme-dashboard.com:

server {
    listen 80;
    server_name acme-dashboard.com www.acme-dashboard.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Now Nginx is the traffic cop, sending visitors to the right lane.

Obtain a free TLS certificate with Certbot:

sudo certbot --nginx -d acme-dashboard.com -d www.acme-dashboard.com

Result: HTTPS is active, and the browser shows a green lock.
Persistence: pm2 save writes the current process list so it restarts on boot.

With these steps, Maya’s dashboard is live at https://acme-dashboard.com and will stay up even after the server reboots. That’s how you deploy next.js self hosted in a real‑world scenario.

The Tools That Make This Easier

Grab these five tools and the deployment process feels as smooth as ordering take‑out.

nvm – Node Version Manager lets you pull the exact LTS Node release you need, then switch back with a single command. Think of it as a kitchen drawer where each drawer holds a different version of the same utensil.
PM2 – A process manager that watches your Next.js server, restarts it if it crashes, and keeps logs tidy. It works like a reliable delivery driver who never leaves the restaurant until the order is completed.
Certbot – The free helper that talks to Let’s Encrypt, fetches SSL certificates, and renews them automatically. It’s the equivalent of a self‑service kiosk that hands you a fresh ticket every 90 days without you lifting a finger.
DigitalOcean Droplets (or any Ubuntu VPS) – A low‑cost, single‑click Ubuntu machine that gives you full control over the stack. Picture it as a rented studio apartment: you bring the furniture (your app) and set up the utilities (Node, Nginx) yourself.
Git – Version control that pushes code over SSH, eliminating passwords during deployment. It’s like having a trusted courier who knows the exact address and never asks for a PIN.

Quick cheat sheet:

nvm install --lts – get the latest LTS Node.
pm2 start npm --name "my-next-app" -- start – launch Next.js under PM2.
certbot --nginx -d yourdomain.com – obtain and install SSL.
git push origin main – update the server code.

With these tools in place, deploying a Next.js app self‑hosted becomes a repeatable, low‑maintenance routine.

Quick Reference: Next.js Deployment Cheat Sheet

Here’s the entire workflow in bite‑size steps, like a recipe you can follow every time you need to deploy Next.js self hosted:

Provision an Ubuntu VPS and create a non‑root user. Think of it as getting a new kitchen and assigning a chef.
Install nvm and run nvm install --lts. This gives you the right version of Node, just like choosing the right oven temperature.
Clone your repository with git clone …. It’s the same as picking up the ingredients you’ll cook with.
Install dependencies using npm ci. This locks the recipe exactly as you tested locally.
Build the app: npm run build. Imagine packing a suitcase; everything you need is now neatly folded.
Start the process with PM2: pm2 start npm --name "app" -- start. PM2 acts like a reliable sous‑chef that keeps the stove on.
Save the PM2 process list and enable startup: pm2 save && pm2 startup. This ensures your app restarts automatically after a power cut.
Install Nginx and configure it as a reverse proxy. Nginx is the front‑door guard, directing visitors to the right room.
Secure the site with Certbot: certbot --nginx -d yourdomain.com. It’s like handing out ID badges so only trusted guests get in.
Test everything, monitor with pm2 logs, and set up automatic certificate renewals.
Quick tip: Keep your SSH keys handy; they’re the master key to your VPS.
Safety net: Run pm2 status after each change to verify the app is alive.
Future updates: Pull new code, run npm ci and npm run build, then pm2 restart app.

What to Do Next

Start small, then level up as you get comfortable.

Easy: Add a health‑check endpoint (/api/health) and let a service like UptimeRobot ping it. Think of it as leaving a “doorbell” on your app so you know it’s home before anyone else knocks.

Medium: Wire a CI/CD pipeline (GitHub Actions works fine). On every push run

npm ci && npm run build && pm2 reload all

. It’s like setting up a coffee machine that brews a fresh cup automatically whenever you order a new blend.

Hard: Containerize the app with Docker and orchestrate with Docker Compose, adding services like a database or Redis. Imagine packing a suitcase where each item (app, DB, cache) has its own compartment, all ready for a quick grab‑and‑go.

Tools/Tips

Health‑check: return {status:"ok"} and a 200 status.
UptimeRobot: free tier checks every 5 minutes.
GitHub Actions: store PM2_HOME as a secret.
Docker: keep .dockerignore lean to speed builds.

Got stuck or have a better tip? Drop a comment below – I’d love to hear how your deployment went!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Host Multiple Websites on One VPS: A Step‑by‑Step Guide

Abdullah Sheikh — Mon, 15 Jun 2026 12:04:01 +0000

Learn to configure Apache/Nginx, set up DNS, and isolate sites on a single VPS so you can launch and manage dozens of domains yourself

Before We Start: What You’ll Walk Away With

By the time you finish this guide you’ll be able to add a fresh domain to your VPS in under five minutes, just like ordering a coffee and getting it right away.

You’ll know exactly when to use a virtual host versus a container or a classic shared‑hosting setup—think of it as choosing between a single‑room apartment, a studio loft, or a full‑house rental depending on how much privacy each client needs.

Next, you’ll have a working Apache or Nginx configuration that serves any number of sites from the same server, similar to how Google Maps can display countless pins without slowing down.

Finally, you’ll walk away with a concise checklist that guarantees each site stays isolated and secure, like packing separate zip‑lock bags for different foods to avoid cross‑contamination.

Identify the right isolation method: virtual host, container, or shared hosting.
Set up the web server: edit apache2.conf or nginx.conf to add new host blocks.
Apply the security checklist: permissions, firewalls, SSL, and backups.
Virtual hosts: lightweight, perfect for dozens of low‑traffic sites.
Containers: add a full OS sandbox when a client needs custom software.
Shared hosting style: use when you want a quick, throw‑away test site.

Checklist:

Create a dedicated system user for each domain.
Set file ownership to that user.
Generate a free Let's Encrypt certificate.
Open only required ports in ufw.

With these tools in hand, hosting multiple websites on one VPS becomes a routine task, not a puzzle.

What Hosting Multiple Websites on One VPS Actually Is (No Jargon)

Hosting multiple websites on one VPS means you run several independent web‑applications on the same physical server, each pointed to its own folder by a virtual‑host configuration. The server’s resources—CPU, RAM, disk—are shared, but the sites stay isolated because the web server knows which files belong to which domain.

Think of a VPS as an office building and each website as a separate office. The building (the server) stays the same, but every office (site) has its own door (domain) and lock (config file). Visitors use the address on the door to get inside, and the security system makes sure they can’t wander into a neighboring office.

The 4 Mistakes Everyone Makes With Multi‑Site VPS Setups

Most people ruin their multi‑site VPS before they even finish the first deployment.

Overwriting the default virtual host – Think of it like changing the address on the front door of your house; every visitor now ends up at the wrong place. When you replace the default 000-default.conf with a new site’s config, the original site disappears. Keep the original file untouched and create a separate .conf for each domain.
Sharing one document root – Imagine stuffing every client’s luggage into the same suitcase; items collide and get lost. Using /var/www/html for all domains means index.html from one site overwrites another. Assign a unique folder, e.g., /var/www/site1, /var/www/site2, and point each virtual host there.
Skipping the reload/restart step – It’s like ordering food and never telling the kitchen it’s ready; the meal never arrives. After editing .conf files, run sudo systemctl reload nginx (or apache2) so the server reads the new settings.

Ignoring file‑system permissions – Think of leaving every drawer unlocked in a shared apartment; anyone can rummage through anyone else’s stuff. Set proper ownership and permissions, for example:

sudo chown -R www-data:www-data /var/www/site1
sudo chmod -R 750 /var/www/site1

This keeps each site’s files isolated and blocks cross‑site attacks.

Fix these four pitfalls and you’ll get a clean, secure environment for hosting multiple websites on one VPS.

How to Host Multiple Websites on One VPS: Step‑by‑Step

Refresh the system and pull in your web server. Think of it like updating the kitchen before cooking:

apt-get update && apt-get install nginx

Lay out a separate folder for each site under /var/www. It’s like assigning a different drawer for every client’s paperwork:

mkdir -p /var/www/site1.com

Set the folder ownership so the web server can read the files. This is the “hand‑off” to the kitchen staff:

chown -R www-data:www-data /var/www/site1.com

Create a server block for the domain. Imagine giving the delivery driver a map that points straight to the right doorstep:

nano /etc/nginx/sites-available/site1.com

server {
    listen 80;
    server_name site1.com www.site1.com;
    root /var/www/site1.com;
    index index.html;
}

Then enable it:

ln -s /etc/nginx/sites-available/site1.com /etc/nginx/sites-enabled/

Tell the world where to find the site. Sarah, a freelance photographer, adds an A‑record for photo‑studio.com that points to 203.0.113.45 in her registrar’s DNS panel.

Check the config for syntax errors and reload. It’s like tasting the sauce before serving:

nginx -t && systemctl reload nginx

Secure the site with a free certificate. Think of it as sealing the envelope with a tamper‑proof sticker:

certbot --nginx -d site1.com -d www.site1.com

Optional: Add a firewall rule if you want traffic to a specific site to stay on its own lane. Example with ufw:

ufw allow from 203.0.113.0/24 to any port 80 comment 'site1.com traffic'

A Real Example: Jane’s Portfolio & Client Blog on a Single VPS

Jane spins up a $10/mo VPS and wants her showcase at portfolio.janedoe.com and a client’s blog at blog.clientx.com on the same machine.

sudo mkdir -p /var/www/portfolio.janedoe.com/public_html
sudo mkdir -p /var/www/blog.clientx.com/public_html

Assign ownership to the www-data user:

sudo chown -R www-data:www-data /var/www/portfolio.janedoe.com
sudo chown -R www-data:www-data /var/www/blog.clientx.com

Copy a simple index file into each folder (think of packing a suitcase with just the essentials):

Jane Doe – Designer
Welcome to my portfolio.

Client X Blog
Latest updates from Client X.

Create two Nginx server blocks, one for each domain (like ordering two separate meals from the same kitchen):

sudo tee /etc/nginx/sites-available/portfolio.janedoe.com > /dev/null  /dev/null 
Enable the blocks and reload Nginx:

bash
sudo ln -s /etc/nginx/sites-available/portfolio.janedoe.com /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/blog.clientx.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx


Obtain free SSL certificates with Certbot (think of wrapping each site in a safety blanket):

bash
sudo certbot --nginx -d portfolio.janedoe.com -d www.portfolio.janedoe.com
sudo certbot --nginx -d blog.clientx.com -d www.blog.clientx.com




- Verify DNS points to the VPS IP for both domains (like setting the right address on a Google Maps pin).

- Test both URLs; each loads its own content over HTTPS and runs in its own directory.

Result: Jane’s portfolio and the client’s blog are live, each secured with HTTPS, and completely isolated from one another on the same VPS.

## The Tools That Make This Easier

First, grab the utilities that will keep your multi‑site VPS tidy and secure.

- Install **Certbot** and let it auto‑renew Let’s Encrypt certificates. Think of it as a coffee subscription that never runs out—once set, you never worry about it again.

- Deploy **Cockpit** for a graphical view of your virtual hosts. It’s like ordering food from a menu instead of typing every dish’s ingredients.

- Enable **Fail2Ban** to block repeated login attempts. Picture a bouncer that recognizes the same troublemaker and keeps them out without you lifting a finger.

- Configure **UFW** as the front‑door firewall. It’s the simple lock on your suitcase that you can set per site, so one domain’s rules don’t affect another.

- Set up **Git‑Deploy** to push code straight into `/var/www`. Imagine mailing a package that lands exactly where you need it, no unpacking required.

- **Certbot** – free client, runs `certbot renew` via cron, works with Nginx and Apache.

- **Cockpit** – web UI at `:9090`, edit `/etc/nginx/sites‑available` with a click.

- **Fail2Ban** – default jail for SSH, add `nginx‑auth` to protect each site’s login.

- **UFW** – simple commands like `ufw allow from 203.0.113.0/24 to any port 80` to isolate traffic.

- **Git‑Deploy** – drop a `post-receive` hook into `~/.ssh/authorized_keys` to auto‑copy a repo into the site folder.

With these tools in place, hosting multiple websites on one VPS becomes as painless as packing a suitcase with pre‑sorted compartments.

## Quick Reference: Multi‑Site VPS Cheat Sheet

Grab a pen and follow these bite‑size actions to keep every site tidy on a single VPS.

- Refresh the OS and pull in your web server: `apt update && apt install nginx` (or `apache2` if you prefer).

- Make a folder for each domain, e.g. `mkdir -p /var/www/example.com`. Think of it like assigning a separate drawer for each client’s paperwork.

- Give the web‑user ownership so the server can read and write: `chown -R www-data:www-data /var/www/example.com`.

- Create a server block (nginx) or virtual host (Apache) that points the domain to its folder. It’s the map that tells traffic which suitcase to open.

- Update DNS: set the **A‑record** of `example.com` to your VPS IP. *Maria, a freelance designer, does this in her domain registrar’s panel and the domain instantly knows where to go.*

- Validate the config – `nginx -t` or `apachectl configtest`. It’s the quick “does the recipe smell right?” check before you bake.

- Reload the service so changes take effect: `systemctl reload nginx` (or `apache2`).

- Secure the site with Let’s Encrypt: `certbot --nginx -d example.com`. One command, automatic renewals, no extra paperwork.

- **Optional**: tighten access with a firewall rule, e.g. `ufw allow from 203.0.113.0/24 to any port 22` for SSH.

- **Tip**: Keep a master `sites-available` list; copy it when you add a new site.

- **Tip**: Test each domain locally with `curl -I http://example.com` before DNS propagates.

Follow this cheat sheet and you’ll host multiple websites on one VPS without breaking a sweat.

## What to Do Next

Give it a quick test drive: add a second domain just like you did for the first, then pop it in the browser.

- **Easy** – Create a new `example2.com` config in `/etc/nginx/sites‑available`, link it, reload Nginx, and point the DNS to your VPS. It’s like ordering a second coffee after the first – same process, fresh result.

- **Medium** – Set up automated backups. A nightly `rsync` job or a Borg repository will copy each site’s `/var/www` folder to a safe location. Think of it as packing a spare suitcase for a trip; you’ll thank yourself if anything gets lost.

- **Hard** – Containerize every site with Docker Compose. Write a `docker‑compose.yml` that spins up an isolated Nginx, PHP, and DB container per domain while sharing the host’s network. This gives you the isolation of separate apartments in the same building.

- **Tip:** Keep a `backup.sh` script version‑controlled so you can recreate any site with one command.

- **Tip:** Use `docker‑compose logs` to troubleshoot container issues without digging through host logs.

Got a unique multi‑site setup or ran into a snag? Drop a comment below – I’d love to help!

---

---

## About the Author

**[Abdullah Sheikh](https://abdullah-sheikh.com/)** is the Founder & CEO at [Exteed](https://exteed.com/), where he leads a team of skilled developers specializing in [Web2](https://abdullah-sheikh.com/) and [Web3 applications](https://abdullah-sheikh.com/), [Custom Smart Contracts](https://abdullah-sheikh.com/), and [Blockchain solutions](https://abdullah-sheikh.com/).

With 6+ years of experience, Abdullah has built [CRMs](https://abdullah-sheikh.com/), [Crypto Wallets](https://abdullah-sheikh.com/), [DeFi Exchanges](https://abdullah-sheikh.com/), [E-Commerce Stores](https://abdullah-sheikh.com/), [HIPAA Compliant EMR Systems](https://abdullah-sheikh.com/), and [AI-powered systems](https://abdullah-sheikh.com/) that drive business efficiency and innovation.

His expertise spans [Blockchain](https://abdullah-sheikh.com/), [Crypto & Tokenomics](https://abdullah-sheikh.com/), [Artificial Intelligence](https://abdullah-sheikh.com/), and [Web Applications](https://abdullah-sheikh.com/); building reliable and smooth web apps that fit the client’s goals and requirements.

📧 [info@abdullah-sheikh.com](mailto:info@abdullah-sheikh.com) · 🔗 [LinkedIn](https://www.linkedin.com/in/-abdullah-sheikh/) · 🌐 [abdullah-sheikh.com](https://abdullah-sheikh.com/)

How to Use PostgreSQL Effectively in Node.js Applications

Abdullah Sheikh — Sun, 14 Jun 2026 12:03:39 +0000

Learn step‑by‑step how to integrate, query, and optimise PostgreSQL in your Node.js projects for fast, reliable apps

Before We Start: What You'll Walk Away With

By the end of this guide you’ll have a production‑grade PostgreSQL connection pool wired into your Node.js app, ready to handle dozens of concurrent requests without dropping a connection.

You’ll know how to run migrations, write safe parameterized queries, and spot the usual performance culprits before they turn your API into a snail‑race.

Finally, you’ll walk away with a drop‑in code template that fits straight into any Express or Koa project, so you can start building features instead of wrestling with boiler‑plate.

Connection pool: configure pg.Pool with sensible defaults, just like ordering a combo meal—you pick the size, the timeout, and the side dishes.
Migrations & queries: use a CLI tool (e.g., node-pg-migrate) to version‑control schema changes, and write queries that are as safe as a seatbelt‑locked car.
Performance cheat sheet: monitor pg_stat_activity, add indexes where the database would otherwise scan every row, and cache frequent lookups like a Google Maps shortcut.

What PostgreSQL in Node.js Actually Is (No Jargon)

PostgreSQL is a relational DBMS that keeps your data in structured tables, and Node.js talks to it through a client library such as pg. Think of PostgreSQL as the kitchen of a restaurant and Node.js as the waiter who takes orders, sends them to the kitchen, and brings the dishes back to the table.

When a request hits your API, the Node.js “waiter” builds a SQL query, hands it off, and waits for the result. The kitchen (PostgreSQL) cooks the data exactly as instructed and returns a plate (result set). If the kitchen is busy, the waiter can’t keep the whole table waiting, so you add a fleet of waiters.

Connection pool: a ready‑made group of database connections that act like multiple waiters, each able to serve a different table without queuing for a single line.

Query: the order slip the waiter writes – e.g.,

SELECT * FROM users WHERE id = $1

Result: the plated dish that the waiter brings back to the client code.

This simple picture removes the buzzwords and shows why you need a pool: without it, every request would wait for the previous one to finish, turning a smooth service into a bottleneck.

Now that you see the roles, let’s explore how to set up that pool so your Node.js app never leaves a customer hanging.

The 4 Mistakes Everyone Makes With PostgreSQL in Node.js

Here’s where most developers trip up when they try to stitch PostgreSQL Node.js together.

Opening a new client for every request is like ordering a fresh coffee for each sip—slow and wasteful. The pool sits idle, connections pile up, and the database soon says “no more seats”. Use a connection pool and reuse it across requests.
Hard‑coding credentials in source files is the digital equivalent of leaving your house key under the doormat. Anyone with read access can walk straight to your DB. Store secrets in environment variables or a vault.
Skipping parameterised queries is inviting SQL injection, just as sharing a public Wi‑Fi password lets strangers snoop on your traffic. Always bind values instead of concatenating strings.
Skipping migrations or sprinkling ALTER TABLE statements into production code is like packing a suitcase haphazardly—you’ll lose track of what’s inside and end up with mismatched items. Adopt a migration tool and run schema changes through it.

Fix these habits and your app will run smoother, safer, and easier to maintain.

How to Use PostgreSQL in Node.js: Step‑by‑Step

Install the official PostgreSQL driver. Think of it as getting the right adapter before you plug a device in.

npm i pg

Create a .env file and store the connection string. It’s like writing the address on a postcard so every part of the app knows where to send the mail.

DATABASE_URL=postgres://user:pass@localhost:5432/mydb

Load it at startup with dotenv:

require('dotenv').config();

Spin up a single Pool instance and export it. This is the “one kitchen” that all chefs share, preventing everyone from cooking on separate stoves.

const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
module.exports = pool;

Build a tiny helper that runs parameterised queries and catches errors. It’s the “menu card” that guarantees the right dish is ordered every time.

async function query(text, params) {
  try {
    const { rows } = await pool.query(text, params);
    return rows;
  } catch (err) {
    console.error('DB error:', err);
    throw err;
  }
}
module.exports = { query };

Set up migrations with node-pg-migrate. Think of migrations as the blueprint updates you file when you remodel a house.

Install: npm i -D node-pg-migrate
Add scripts:

{
  "scripts": {
    "migrate": "node-pg-migrate up",
    "migrate:down": "node-pg-migrate down"
  }
}

In each route, request a client from the pool, execute the query, and let the pool release it automatically. It works like a valet: you hand over the car, it runs the task, then parks it back.

const { query } = require('./db');
app.get('/users', async (req, res) => {
  const users = await query('SELECT * FROM users WHERE active = $1', [true]);
  res.json(users);
});

Add lightweight logging. A simple console log tells you when a query starts and ends; a library like pg-monitor gives you a dashboard view.

Console example:

pool.on('connect', () => console.log('✅ PostgreSQL connected'));
pool.on('error', (err) => console.error('❌ Pool error', err));

Or install pg-monitor for richer metrics.

A Real Example: Building a Todo API for a Startup Founder

Maya, a full‑stack founder, wants a tiny Todo API that runs locally and on Railway without rewriting anything.

Set up the environment. She adds a .env file with POSTGRESQL_URL=postgres://user:pass@localhost:5432/todos. It’s like putting the address on a delivery label – everything else finds the database automatically.
Create a shared pool. In db/pool.js she writes:

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.POSTGRESQL_URL,
});
module.exports = pool;

This singleton is the “single kitchen” that every request can order from, preventing the “too many cooks” problem.

Run the first migration. Maya adds migrate.js:

const { up } = require('node-pg-migrate');
up({
  databaseUrl: process.env.POSTGRESQL_URL,
  migrationsDir: __dirname + '/migrations',
  direction: 'up',
});

Inside migrations/001-create-todos.sql she writes:

CREATE TABLE todos (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  completed BOOLEAN DEFAULT FALSE
);

Running node migrate.js creates the table – think of it as laying out the restaurant’s menu before opening.

Wire the routes. In routes/todos.js she uses the pool’s query helper:

const express = require('express');
const router = express.Router();
const pool = require('../db/pool');

// CREATE
router.post('/', async (req, res) => {
  const { title } = req.body;
  const { rows } = await pool.query(
    'INSERT INTO todos (title) VALUES ($1) RETURNING *',
    [title]
  );
  res.json(rows[0]);
});

// READ ALL
router.get('/', async (_, res) => {
  const { rows } = await pool.query('SELECT * FROM todos ORDER BY id');
  res.json(rows);
});

// UPDATE
router.patch('/:id', async (req, res) => {
  const { id } = req.params;
  const { title, completed } = req.body;
  const { rows } = await pool.query(
    'UPDATE todos SET title = $1, completed = $2 WHERE id = $3 RETURNING *',
    [title, completed, id]
  );
  res.json(rows[0]);
});

// DELETE
router.delete('/:id', async (req, res) => {
  const { id } = req.params;
  await pool.query('DELETE FROM todos WHERE id = $1', [id]);
  res.sendStatus(204);
});

module.exports = router;

All statements use $1‑style placeholders, just like filling a coffee order with numbered slots.

Run and deploy. Maya starts locally with npm run dev, confirms the endpoints work, then pushes the repo to Railway. Railway injects the same POSTGRESQL_URL into the environment, so the code runs unchanged.
Tip: Keep .env.example in the repo so any new teammate knows which variables to set.

Cheat sheet:

Pool file: db/pool.js
Migrate command: node migrate.js
CRUD routes: use $1 placeholders

With these steps Maya’s Todo API is production‑ready and still feels as simple as ordering a sandwich.

The Tools That Make This Easier

Think of your Node.js stack as a kitchen; these tools are the appliances that keep everything from burning to staying organized.

pg – the official PostgreSQL client. Like a reliable chef’s knife, it slices through queries with minimal fuss. Install with npm install pg and you’ll have a simple Pool object ready for reuse.
node-pg-migrate – zero‑config migration runner with TypeScript support. It works like Google Maps for your schema: you plot a route (migration files) and it guides the database to the destination without getting lost.
pg-monitor – lightweight monitoring dashboard you can drop into any Express app. Imagine a kitchen timer that flashes when a dish is ready; this adds a real‑time view of query latency, errors, and connection counts.
Supabase Studio – free web UI for managing tables, rows, and auth. It’s the “restaurant front‑of‑house” where you can glance at data, edit a row, or check permissions without opening a terminal.
dotenv – loads environment variables securely from a .env file. Think of it as a sealed lunchbox that keeps your database passwords safe while you’re on the go.

require('dotenv').config();
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

These five utilities give you a solid foundation for any PostgreSQL Node.js project, from quick prototyping to production‑grade deployments.

Quick Reference: PostgreSQL in Node.js Cheat Sheet

Grab this cheat sheet and keep it beside your editor—you’ll stop hunting for snippets.

Install: npm i pg dotenv. Think of it like ordering the right ingredients before you start cooking.
.env: DATABASE_URL=postgres://user:pass@host:5432/db. It’s your kitchen’s pantry label, so every recipe knows where the supplies live.

Pool singleton:

const {Pool}=require('pg');
const pool=new Pool({connectionString:process.env.DATABASE_URL});

Like a single checkout lane at a grocery store—everyone queues through the same line, avoiding bottlenecks.
Query helper:

async function q(sql,params){
  const {rows}=await pool.query(sql,params);
  return rows;
}

It’s the “grab‑and‑go” slot in a vending machine: you drop in the request and get the snack (rows) instantly.

Migrations: run npx node-pg-migrate up. Imagine Alex, a freelance dev, moving furniture from a draft floor plan to the final layout—each migration is a piece of that furniture.
Param placeholders: use $1, $2 …. Just like a GPS asks for waypoints; you feed the numbers and it routes safely, preventing SQL injection.
Release automatically: a simple await pool.query(...) inside try/catch is enough. The connection checks out and returns itself, like a library book that’s auto‑shelved when you close the cover.
Monitor: add app.use(require('pg-monitor').express()). Think of it as installing a dashcam for your DB traffic—see every query without extra effort.

Stick this list on your screen and let PostgreSQL Node.js work smoothly every time.

What to Do Next

Grab the repo, run the install, and you’ll have a sandbox that mirrors the article’s examples.

Clone the starter repo from the article’s GitHub link and execute npm install. Think of it like picking up a ready‑made pizza dough – the base is already there, you just add your toppings.
Create a migration that adds an index on the column you query most often, then fire up pg-monitor to compare response times before and after. It’s similar to placing a shortcut sign on a busy road and watching the traffic flow improve.
Turn the simple query helper into a dedicated repository class, sprinkle in TypeScript typings, and write a handful of unit tests using jest-pg-mock. This step is like packing a suitcase: you organize everything into compartments so you can find it quickly later.
Tools: node-pg-migrate for migrations, pg-monitor for live metrics, jest-pg-mock for isolated tests.
Tips: Commit after each step, run npm run lint to catch stray errors, and keep your index names descriptive (e.g., idx_users_email).

Cheat sheet:

npm run migrate up – apply migrations
npm run migrate down – roll back last migration
npm test – run Jest suite

💬 Got stuck or have a different use‑case? Drop a comment below or share your own pattern on LinkedIn!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com

How to Build an AI-Powered Job Application Bot in 7 Easy Steps

Abdullah Sheikh — Sat, 13 Jun 2026 12:03:51 +0000

Create a fully automated bot that drafts, customizes, and submits job applications for you

Before We Start: What You'll Walk Away With

You’ll finish this guide with a clear mental map of how an AI job application bot fits together, just like a kitchen layout shows where the stove, sink, and fridge belong.

Next, you’ll have a working prototype that can scrape new listings, tweak your résumé, draft a cover letter, and push the application with a single command—think of it as ordering a complete meal with one tap on a food‑delivery app.

Finally, you’ll know how to tinker, test, and keep the bot playing nicely with applicant‑tracking systems, similar to regularly updating a GPS map so you never end up on a dead‑end road.

Grasp the overall architecture and data flow of the bot.
Build a functional prototype that automates pulling jobs, customizing docs, and submitting.
Learn iteration, testing, and ATS‑compliance best practices.
Tool tip: Use requests for scraping, OpenAI API for content generation, and selenium for submission.
Cheat sheet: Keep a config.yaml with your target keywords, resume template path, and email credentials.
Testing hint: Run the bot in a sandbox job board before hitting real sites.

By the end of the next sections you’ll be ready to turn the copy‑paste nightmare into a single click and spend more time preparing for interviews.

What an AI‑Powered Job Application Bot Actually Is (No Jargon)

AI job application bot is a lightweight script that calls an LLM—think GPT‑4o—to read a job posting, compare it with the details you’ve saved about yourself, then spit out a customized resume, cover letter, and even click the submit button on the employer’s site.

It works like a personal assistant who skims the ad while you sip coffee, drafts a tailored cover note, fills every field in the online form, and hits “send” without you lifting a finger.

Read the posting → extract required skills, keywords, and job title.
Match against your stored profile → pick the most relevant experiences.
Generate documents → resume and cover letter that echo the job description.
Submit automatically → navigate the company’s portal and upload the files.

Imagine ordering a pizza: you tell the app your favorite toppings, it checks the menu, builds the perfect order, and places it for you. The bot does the same with applications, turning a repetitive chore into a single click.

Because it’s just a script, you can run it from your laptop, tweak the prompts, or add new job boards as they appear. The result is fewer copy‑paste battles and more time spent prepping for interviews.

The 4 Mistakes Everyone Makes With AI Job Bots

Most people who tinker with an AI job application bot hit the same snags, and they waste hours before they even see a single response.

Using a generic prompt for every role. It’s like ordering the same sandwich at every restaurant – it never matches the local flavor. The bot ends up spitting out bland cover letters that hiring managers can’t tell apart.
Ignoring ATS parsing rules. Think of an ATS as a strict bouncer; if your résumé isn’t dressed in the right format, it never gets past the door. Mis‑aligned tables or quirky bullet points cause instant rejections.
Hard‑coding credentials. Storing usernames and passwords directly in the script is like leaving your house keys under the doormat. One change on the site and the bot crashes, plus you expose sensitive data.
Skipping testing on a sandbox. Deploying straight to live applications is like sending a suitcase full of items without checking the weight limit first – you only discover broken zippers after you’ve paid the extra fees. A sandbox reveals bugs before they cost you dozens of wasted submissions.
Fix #1: Create role‑specific prompt templates; swap in the job title and key skills each time.
Fix #2: Follow the ATS‑friendly format guide – plain text, standard headings, simple bullet points.
Fix #3: Store secrets in environment variables or a vault service instead of the code.
Fix #4: Build a mock application page or use a service’s test endpoint to run the bot safely.

How to Build an AI Job Application Bot: Step‑by‑Step

Grab a coffee and follow these nine actions to get your AI job application bot up and running.

Set up the environment. Install Python 3.11 and pip, then create a virtualenv:

python3.11 -m venv botenv && source botenv/bin/activate

. Think of the virtualenv like a clean kitchen counter ready for a new recipe.

Gather data. Export your master resume to resume.pdf, build a skills.json file with tags like "python" or "data analysis", and save a few cover‑letter drafts in templates/. This is the luggage you’ll pack before a trip.

Choose an LLM API. Sign up at OpenAI, drop the key into a .env file (OPENAI_API_KEY=your_key), and run a quick test:

import openai, os; openai.api_key=os.getenv("OPENAI_API_KEY"); print(openai.ChatCompletion.create(model="gpt-4o",messages=[{"role":"user","content":"Hello"}]))

. It’s like checking that your GPS satellite signal works before you drive.
Scrape job listings. Use BeautifulSoup or Selenium to pull title, description, and apply link from LinkedIn or Indeed:

from bs4 import BeautifulSoup; import requests; html=requests.get(url).text; soup=BeautifulSoup(html,"html.parser")

. Imagine a robot waiter collecting menu items for you.
Prompt engineering. Write a reusable prompt that injects the job description and your profile, then asks the model to draft a resume snippet and cover letter. Example:

prompt = f"""You are a career coach. Given the job description: {desc} and the candidate profile: {profile}, write a concise resume bullet and a cover letter paragraph."""

. This is the recipe you’ll follow for every order.
Format output. Convert the markdown response to PDF with WeasyPrint and add ATS‑friendly headings:

from weasyprint import HTML; HTML(string=markdown).write_pdf("application.pdf")

. Think of it as folding a suitcase so everything fits the airline’s size limits.
Automate submission. Drive a Selenium browser to fill fields, upload application.pdf, and click submit. If a CAPTCHA appears, call 2captcha:

driver.find_element_by_name("resume").send_keys("/path/application.pdf")

. It’s like a self‑service kiosk that handles the checkout for you.
Logging & error handling. Write each attempt to log.csv, add retry logic, and fire a Slack webhook on success or failure:

import csv; with open("log.csv","a") as f: csv.writer(f).writerow([job_id,status])

. This acts like a travel diary that notes every hiccup.

Review & iterate. Run the bot on 2–3 real postings, tweak the prompt, and add rate‑limit checks to avoid API bans. Treat this as a test drive before a long road trip.

Once these steps click together, your AI job application bot will handle the paperwork while you prep for the interview.

A Real Example: Maya’s Switch‑to‑Product‑Management Job Hunt

Maya uploads her resume.json (Python/SQL focus) and a generic product‑oriented cover letter into the bot.

Bot scans the three startup job pages, just like a price‑comparison app gathers restaurant menus.
It pulls the required keywords—“roadmap,” “KPIs,” “user research”—and appends a new Product Analytics section to her resume, swapping out the old “Data Analyst” bullet points.
For each posting, the bot rewrites the cover letter, inserting the startup’s latest product launch (e.g., “your new AI‑driven analytics dashboard”) as a hook, exactly the way you’d mention a dish you love when ordering at a new café.
It converts the tailored resume and cover letter into PDFs, drops them into a pre‑created Google Drive folder, and clicks “Submit” on the career portals, mimicking a shopper checking out with one click.
Finally, the bot sends Maya a Slack message for every submission, attaching the PDF link and a brief status update.
Tool tip: Set SLACK_WEBHOOK_URL in .env so alerts land in the right channel.
Tip for PDFs: Use pdfkit.from_string(html, output_path) to keep formatting consistent.
Speed hack: Run the scraper with asyncio.gather() to hit all three sites in parallel.

With this flow, Maya turns a three‑hour manual grind into a handful of seconds, leaving her free to prep for interviews.

The Tools That Make This Easier

Grab the toolbox below and you’ll be ready to turn a handful of scripts into a full‑blown AI job application bot.

Python 3.11 – the official interpreter is free and packs the newest syntax sugar. Think of it as the fresh espresso shot that powers every sip of your automation.
OpenAI GPT‑4o API – the freemium tier hands you enough tokens to generate dozens of personalized cover letters each month. It’s like ordering a custom sandwich; you pay per bite, not per whole menu.
BeautifulSoup 4 + Requests – these libraries fetch web pages and pull out the bits you need, just as a grocery list lets you snag only the ingredients you actually use.
Selenium WebDriver with ChromeDriver – an open‑source browser robot that can click, type, and upload files. Running Chrome in headless mode is the same as using a GPS that silently guides you without showing the map.
WeasyPrint – converts HTML/CSS into PDF while preserving ATS‑friendly layouts. Imagine packing a suitcase: the suit stays neat, folded, and ready for inspection.

Quick cheat sheet:

Install: pip install python==3.11 openai beautifulsoup4 requests selenium weasyprint
Run Chrome headless: webdriver.Chrome(options=options) with options.add_argument("--headless")
Call GPT‑4o: openai.ChatCompletion.create(model="gpt-4o", …)
Render PDF: WeasyPrint(html_string, base_url=".").write_pdf("output.pdf")

With these tools in hand, building an AI job application bot becomes a matter of wiring them together.

Quick Reference: AI Job Application Bot Cheat Sheet

Grab this cheat sheet whenever you start a new run; it packs every command and file you’ll touch.

🔧 Environment: Install Python 3.11, create a venv, then run pip install -r requirements.txt. Think of it as setting up a clean kitchen before cooking.
📄 Data: Convert master_resume.docx to resume.json, keep a sample_cover.md ready. Like prepping ingredients and a sauce recipe before you grill.
🤖 LLM: Load OPENAI_API_KEY from .env, use the GPT‑4o prompt template. It’s your sous‑chef that knows every flavor.
🕸️ Scrape: requests → BeautifulSoup → build job_dict with {title, desc, url}. Picture a Google Maps search that pulls the exact address you need.

✍️ Generate: Feed the prompt with resume_snippet + cover_letter (markdown). Example for Alice applying to Acme Corp:

prompt = f"""You are a hiring manager at Acme Corp...
Resume: {alice_resume}
Cover: {alice_cover}
"""

📄 Format: Convert markdown to HTML, then to PDF with WeasyPrint. Like packing a suitcase: first fold, then zip.
🚀 Submit: Selenium fills fields, uploads PDFs, clicks submit. Automation acts like a robot waiter taking your order.
📝 Log: Append a line to applications.csv and fire a Slack webhook. Keeps a trail as tidy as a receipt folder.

Keep this list beside your code; the bot will thank you.

What to Do Next

Give the repo a quick spin on a single posting and watch each piece fire in sync.

Clone the starter repo, drop a real job URL into run.py, and hit python run.py. It's like ordering a single dish to test a new restaurant menu – you see if the flavors match before committing to a full feast.
Tailor the prompt to sound like you, then plug in a second LLM such as Claude 3.5 for backup. Think of it as adding a spare tire; if the primary model stalls, the extra engine keeps you moving.
Push the bot to a cloud scheduler (GitHub Actions, Render, etc.) and build a tiny web UI so a friend can press “apply” without touching code. This is the equivalent of packing a suitcase with everything you need for a trip – you set it once, then just zip it up and go.
Tools: GitHub Actions, Render Scheduler, Streamlit for the UI.
Tip: Keep your API keys in .env and reference them with os.getenv to avoid accidental leaks.
Cheat sheet: python -m pip install -r requirements.txt → python run.py → commit → push → watch the workflow trigger.

Got stuck or have a cool tweak? Drop a comment below – I’d love to hear how you’ve automated your job search!

About the Author

Abdullah Sheikh is the Founder & CEO at Exteed, where he leads a team of skilled developers specializing in Web2 and Web3 applications, Custom Smart Contracts, and Blockchain solutions.

His expertise spans Blockchain, Crypto & Tokenomics, Artificial Intelligence, and Web Applications; building reliable and smooth web apps that fit the client’s goals and requirements.

📧 info@abdullah-sheikh.com · 🔗 LinkedIn · 🌐 abdullah-sheikh.com