DEV Community: Caleb Ajibade

Deploying a Next.js and Spring Boot Monorepo to One EC2 Instance

Caleb Ajibade — Tue, 15 Sep 2026 16:23:49 +0000

I started with two repositories: a Next.js forum frontend and a Spring Boot API. I wanted one deployable unit: a monorepo, two immutable Docker images, and one EC2 instance exposing the complete application.

git push (devops)
        ↓
GitHub Actions using OIDC
        ↓
Amazon ECR: API image + frontend image
        ↓
private S3 release package → AWS Systems Manager → EC2
        ↓
Docker Compose: Nginx → Next.js at /, Spring Boot at /api, MongoDB privately

The API is Java 21 / Spring Boot 3.5 with MongoDB and JWT authentication. The frontend is Next.js 15. Both now live in one repository:

forum-api/
├── src/                 # Spring Boot API
├── frontend/            # Next.js application
├── deploy/
│   ├── docker-compose.yml
│   ├── nginx.conf
│   └── deploy-on-ec2.sh
└── .github/workflows/deploy.yml

1. Containerise both applications

The API image is built from the repository root with its existing multi-stage dockerfile. The frontend has its own multi-stage build in frontend/dockerfile:

FROM node:22-alpine AS builder
WORKDIR /app
ARG NEXT_PUBLIC_API_BASE_URL
ENV NEXT_PUBLIC_API_BASE_URL=${NEXT_PUBLIC_API_BASE_URL}
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "start"]

The important frontend build argument is:

docker build --file frontend/dockerfile \
  --build-arg NEXT_PUBLIC_API_BASE_URL=/api \
  --tag forum-frontend:local frontend

/api is a relative browser URL. The browser calls the same hostname that served the frontend, which avoids exposing a second public port or relying on CORS between separate origins.

2. Run both containers behind Nginx

Docker Compose runs four services on the EC2 host: frontend, api, mongo, and nginx. Only Nginx publishes a host port.

services:
  api:
    image: ${IMAGE_URI:?Set IMAGE_URI to the ECR image URI}
    env_file: [${RUNTIME_ENV_FILE:-../.env}]
    expose: ["8080"]

  frontend:
    image: ${FRONTEND_IMAGE_URI:?Set FRONTEND_IMAGE_URI to the ECR image URI}
    expose: ["3000"]

  mongo:
    image: mongo:7
    volumes: [mongo-data:/data/db]

  nginx:
    image: nginx:1.27-alpine
    depends_on: [api, frontend]
    ports: ["80:80"]
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

The Nginx configuration has two deliberately different routes:

location /api/ {
    proxy_pass http://api:8080;
}

location / {
    proxy_pass http://frontend:3000;
}

The API proxy keeps the /api prefix because the Spring controllers are already mapped below it. Every other route, including Next.js page routes, reaches the frontend container.

3. Use two private ECR repositories

I created two immutable, scan-on-push ECR repositories in eu-north-1:

forum-api
forum-frontend

The GitHub deployment role can push only to those repositories. The EC2 instance role can pull only from those repositories and download releases from one private S3 bucket. This keeps AWS permissions narrow while still allowing one workflow to deploy the complete stack.

The GitHub repository variables are:

Variable	Value
`AWS_REGION`	`eu-north-1`
`ECR_REPOSITORY`	`forum-api`
`FRONTEND_ECR_REPOSITORY`	`forum-frontend`
`EC2_INSTANCE_ID`	the target instance ID
`DEPLOYMENT_BUCKET`	the private release bucket

The one GitHub environment secret is AWS_DEPLOY_ROLE_ARN. It is an IAM role ARN, not an access key. The JWT secret and runtime database/mail settings stay in /opt/forum-api/.env on EC2 and are never committed or copied into GitHub.

4. Build and deploy through GitHub Actions

The devops workflow uses GitHub OIDC to obtain short-lived AWS credentials. It builds both images, tags each one with the commit SHA, and only pushes a tag if it does not already exist because the ECR repositories reject overwritten tags.

docker build --file dockerfile --tag "$REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" .
docker build --file frontend/dockerfile \
  --build-arg NEXT_PUBLIC_API_BASE_URL=/api \
  --tag "$REGISTRY/$FRONTEND_ECR_REPOSITORY:$IMAGE_TAG" frontend

The workflow then packages deploy/, uploads it to private S3, and sends an SSM command to EC2. The host script logs into ECR, sets both image URIs, then runs:

docker compose -f deploy/docker-compose.yml pull
docker compose -f deploy/docker-compose.yml up -d --remove-orphans

No SSH port, GitHub deploy key, or long-lived AWS access key is required on the server. On a small EC2 root disk, use Next.js output: "standalone" and copy only .next/standalone, .next/static, and public into the runtime image. This avoids downloading a full development dependency tree. I also prune unused images before a pull, never volumes or running containers.

5. Verification and next steps

After a successful workflow, visit the EC2 public IP or a domain pointed to it:

http://YOUR_EC2_PUBLIC_IP/

You should see the Next.js frontend. A request such as /api/topics/ should be handled by Spring Boot through Nginx. The API, MongoDB, and frontend ports remain private to the Docker network; port 80 is the only public application port. Because Nginx reads its configuration when it starts, I explicitly recreate that one stateless container after extracting a release package; otherwise a changed bind-mounted configuration would not take effect until its next restart.

For a real production deployment, I would add a custom domain and HTTPS, configure a working SMTP provider, add an unauthenticated health endpoint, and move MongoDB to a managed database before the application needs durability across instance replacement.

The useful pattern here is modest but robust: a monorepo gives one release version, ECR gives immutable images, Nginx gives one public entry point, and GitHub Actions plus OIDC and SSM gives an automated deployment without managing server SSH credentials.

How to Set Up AdGuard Home as Network-Wide DNS and DHCP on an Airtel Router

Caleb Ajibade — Sun, 13 Sep 2026 18:37:39 +0000

Many Airtel home routers provide DHCP but do not expose a setting for
choosing the DNS server distributed to connected devices.

That creates a problem if you want to run AdGuard Home for the entire
network. You can install AdGuard and manually configure every phone,
laptop, and TV to use it, but that quickly becomes inconvenient.

A cleaner solution is to let AdGuard Home provide both DNS and DHCP,
while the Airtel router continues to provide Wi-Fi, NAT, and internet
access.

This tutorial shows how to build that setup using:

an Airtel home router
a Fedora computer
Docker and Docker Compose
AdGuard Home

The example network used here is:

Router:        192.xxx.x.1
Fedora:        192.xxx.x.13
Network:       192.xxx.x.0/24
Subnet Mask:   255.255.255.0
DHCP Pool:     192.xxx.x.100 - 192.xxx.x.200

Your Airtel router may use different addresses. Check your own network
before copying the IP addresses in this tutorial.

What We Are Building

The final architecture will look like this:

                         Internet
                            │
                            ▼
                    ┌───────────────┐
                    │ Airtel Router │
                    │ 192.xxx.x.1  │
                    │               │
                    │ Gateway + NAT │
                    │ DHCP: OFF     │
                    └───────┬───────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
    ┌──────────────────┐             Other Devices
    │ Fedora Computer  │
    │ 192.xxx.x.13    │
    │                  │
    │ AdGuard Home     │
    │ DNS  → Port 53   │
    │ DHCP → Port 67   │
    └──────────────────┘

The responsibilities are split like this:

Airtel Router
├── Wi-Fi
├── Internet connection
├── Default gateway
└── NAT

Fedora + AdGuard Home
├── DNS
├── DNS filtering
├── DNS caching
└── DHCP

Your normal internet traffic does not pass through the Fedora
computer.

DNS:
Phone → AdGuard → Upstream DNS

Normal internet traffic:
Phone → Airtel Router → Internet

This distinction is important. AdGuard is the DNS and DHCP server, not
the router.

Before You Start

You should already have Docker and Docker Compose available on Fedora.

Verify them:

docker --version
docker compose version

You should also know the name of your active network interface.

Run:

ip link

For this tutorial, the Wi-Fi interface is:

wlo1

You can find your router's address with:

ip route | grep default

For example:

default via 192.xxx.x.1 dev wlo1

Here:

192.xxx.x.1

is the Airtel router.

Step 1: Create the AdGuard Home Docker Compose Project

Create a directory for AdGuard:

mkdir -p ~/Documents/Dev/compose/adguard
cd ~/Documents/Dev/compose/adguard

Create:

compose.yaml

with:

services:
  adguardhome:
    image: adguard/adguardhome:edge
    container_name: adguardhome
    restart: unless-stopped

    network_mode: host

    volumes:
      - adguard_work:/opt/adguardhome/work
      - adguard_conf:/opt/adguardhome/conf

volumes:
  adguard_work:
  adguard_conf:

Start it:

docker compose up -d

Check:

docker ps

You should see the adguardhome container running.

Step 2: Why We Use Host Networking

The important line in the Compose file is:

network_mode: host

AdGuard will eventually act as the DHCP server.

DHCP clients initially have no IP configuration, so they use broadcast
packets to discover a DHCP server.

The process is:

Client                         AdGuard
  │                               │
  │──── DHCP Discover ───────────►│
  │                               │
  │◄──── DHCP Offer ──────────────│
  │                               │
  │──── DHCP Request ────────────►│
  │                               │
  │◄──── DHCP ACK ────────────────│

This is commonly called the DHCP DORA process.

Using host networking lets AdGuard interact directly with Fedora's
physical network interface instead of sitting behind Docker's normal
bridge network.

Do not add a ports: section when using this configuration. With host
networking, AdGuard binds directly to ports on the Fedora host.

Step 3: Complete the Initial AdGuard Setup

Open the AdGuard Home interface in your browser.

Depending on the initial AdGuard setup state, the installation wizard
may initially use another port. Complete the wizard and configure the
final administrative interface to listen locally.

For the finished configuration, use:

Web interface:
127.0.0.1:80

This keeps the administrative dashboard accessible from the Fedora
computer without exposing it unnecessarily to every device on the Wi-Fi.

After configuration, open:

http://127.0.0.1

Step 4: Give the Fedora Computer a Static IP

Before making Fedora the network's DNS and DHCP server, give it a
predictable address.

Find the active NetworkManager connection:

nmcli connection show --active

Copy its UUID.

You may have multiple saved connections with the same Wi-Fi name, so
using the UUID is safer than using the connection name.

For this example, Fedora will use:

192.xxx.x.13/24

Configure it:

sudo nmcli connection modify <CONNECTION-UUID> \
  ipv4.method manual \
  ipv4.addresses "192.xxx.x.13/24" \
  ipv4.gateway "192.xxx.x.1" \
  ipv4.dns "127.0.0.1" \
  ipv4.ignore-auto-dns yes

Reconnect:

nmcli connection down <CONNECTION-UUID>
nmcli connection up <CONNECTION-UUID>

Verify:

ip addr show wlo1 | grep 'inet '

You should see:

192.xxx.x.13/24

without the dynamic flag.

Check the default route:

ip route | grep default

It should still point to the Airtel router:

default via 192.xxx.x.1 dev wlo1

The Airtel router remains your gateway.

Step 5: Reserve the Fedora Address on the Airtel Router

Open the Airtel router's administration page.

For this network:

http://192.xxx.x.1

Look for a feature named something similar to:

MAC-IP Bind
IP-MAC Binding
Address Reservation
Static Lease

The exact name depends on the Airtel router model and firmware.

Find Fedora's active Wi-Fi MAC address:

ip link show wlo1

Create a binding between that MAC address and:

192.xxx.x.13

This prevents the router from accidentally assigning the server address
to another device.

Be aware that modern Wi-Fi systems may use randomized MAC addresses. Use
the MAC address actually active on the Airtel Wi-Fi connection rather
than assuming the adapter's permanent hardware address is being used.

Step 6: Configure AdGuard's DNS Listeners

AdGuard should listen for DNS requests on:

127.0.0.1
192.xxx.x.13

with DNS port:

The purpose of each listener is:

127.0.0.1:53
    Fedora itself can use AdGuard.

192.xxx.x.13:53
    Other devices on the LAN can use AdGuard.

Keep the dashboard on:

127.0.0.1:80

if you only want it accessible from the Fedora machine.

Restart AdGuard if necessary:

docker restart adguardhome

Verify:

sudo ss -lntup | grep ':53'

You should see AdGuard listening on both:

127.0.0.1:53
192.xxx.x.13:53

Step 7: Do Not Disable systemd-resolved

Fedora normally runs systemd-resolved.

You may see:

127.0.0.53:53
127.0.0.54:53

when checking port 53.

For example:

sudo ss -lntup | grep ':53'

may show:

127.0.0.1:53     AdGuardHome
192.xxx.x.13:53 AdGuardHome
127.0.0.53:53    systemd-resolved
127.0.0.54:53    systemd-resolved

This is valid.

The processes use different IP addresses even though they use the same
port number.

There is no need to disable systemd-resolved.

Step 8: Test AdGuard Locally

Test DNS directly against AdGuard:

dig @127.0.0.1 google.com

Then test the LAN address:

dig @192.xxx.x.13 google.com

Both should return successful DNS responses.

At this point:

Fedora → AdGuard DNS → Upstream DNS

is working.

Do not disable Airtel DHCP yet.

Step 9: Open DNS in Fedora's Firewall

Other LAN devices need permission to reach Fedora on port 53.

Open UDP DNS:

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --add-port=53/udp \
  --permanent

Open TCP DNS:

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --add-port=53/tcp \
  --permanent

Reload:

sudo firewall-cmd --reload

Verify:

firewall-cmd --zone=FedoraWorkstation --list-ports

You should see:

53/tcp
53/udp

among the configured ports.

Step 10: Test AdGuard from Another Device

Before changing DHCP, test whether another device can reach AdGuard.

Temporarily configure a phone or another computer to use:

DNS Server:
192.xxx.x.13

Browse normally and check:

AdGuard Home → Query Log

You should see DNS requests from the device.

This proves that LAN DNS works before making the entire network
dependent on it.

Return the test device to automatic DNS afterward if desired. DHCP will
distribute the AdGuard address automatically later.

Step 11: Allow DHCP Through Fedora's Firewall

AdGuard also needs to receive DHCP traffic.

Run:

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --add-service=dhcp \
  --permanent

Reload:

sudo firewall-cmd --reload

Verify:

firewall-cmd --zone=FedoraWorkstation --list-services

You should see:

dhcp

Do not confuse this with dhcpv6-client, which is a separate service.

Step 12: Configure AdGuard's DHCP Server

Open:

http://127.0.0.1

Go to AdGuard's DHCP settings.

Select the physical Wi-Fi interface:

wlo1 - 192.xxx.x.13

Do not select one of Docker's bridge interfaces.

Configure IPv4 DHCP as:

Gateway:       192.xxx.x.1
Range Start:   192.xxx.x.100
Range End:     192.xxx.x.200
Subnet Mask:   255.255.255.0
Lease:         86400

The pool deliberately does not contain 192.xxx.x.13.

Save the configuration and enable AdGuard's DHCP server.

Verify:

sudo ss -lunp | grep ':67'

A successful configuration should show AdGuardHome listening on UDP
port 67 on wlo1.

For example:

0.0.0.0%wlo1:67

At this point AdGuard is ready to provide DHCP.

Step 13: Disable DHCP on the Airtel Router

Only do this after confirming that AdGuard is listening on port 67.

Open:

http://192.xxx.x.1

Navigate to the Airtel router's LAN/DHCP settings.

A typical Airtel interface may show something similar to:

IP Address:      192.xxx.x.1
Subnet Mask:     255.255.255.0
DHCP Server:     Enable
DHCP IP Pool:    192.168.18.2 - 192.168.18.253
DHCP Lease Time: 24 hours

Change:

DHCP Server: Enable

to:

DHCP Server: Disable

Apply the change.

Do not change the router's LAN address.

It should remain:

192.xxx.x.1

because it is still the network's gateway.

Step 14: Reconnect a Client

Take a phone or another computer and make sure its network configuration
is set to:

IP:  Automatic / DHCP
DNS: Automatic

Disconnect and reconnect it to the Airtel Wi-Fi.

Then open:

AdGuard Home → DHCP → DHCP Leases

The device should appear as a dynamic lease.

A client should receive something similar to:

IP:      192.xxx.x.105
Gateway: 192.xxx.x.1
DNS:     192.xxx.x.13

The exact IP can be anywhere inside:

192.xxx.x.100 - 192.xxx.x.200

Step 15: Verify DNS Filtering

From Fedora:

dig @192.xxx.x.13 google.com

Then open websites from another connected device and inspect:

AdGuard Home → Query Log

You should see the client's DNS requests.

If you have a domain intentionally blocked through a custom rule, you
can test it directly:

dig @192.xxx.x.13 blocked-example.com

Depending on AdGuard's configured blocking mode, a blocked request may
return 0.0.0.0, NXDOMAIN, or another configured blocking response.

Step 16: Add Blocklists Carefully

AdGuard Home can use DNS blocklists to block advertising, tracking,
telemetry, malicious domains, and other unwanted endpoints.

It is tempting to enable every available list.

Avoid doing that.

Several lists can contain substantial overlap:

List A
├── ads.example.com
├── tracker.example.com
└── telemetry.example.com

List B
├── ads.example.com
├── tracker.example.com
└── another-tracker.example

More rules do not automatically mean better filtering.

Large numbers of overlapping lists can increase:

memory usage
update time
filter reload time
false positives
application breakage
troubleshooting difficulty

Start with a reputable general-purpose filter and add complementary
lists only when you identify a specific gap.

Step 17: Configure Per-Device Policies

Not every device on a home network needs identical filtering.

AdGuard Home can maintain persistent clients and apply different
policies.

For example:

Personal Laptop
└── Standard filtering

Parent Phone
└── Standard filtering

Child Phone
├── Filtering
├── Parental controls
├── Safe Search
└── Restricted services

You can create static DHCP leases for devices that should always receive
predictable addresses.

This provides policy control at the DNS layer without applying parental
restrictions to every person on the network.

Remember that DNS filtering is not equivalent to full network isolation.
Devices using encrypted DNS, hard-coded IP addresses, VPNs, or other
bypass mechanisms may require controls at the router/firewall level.

Step 18: Understand the Query Log

The Query Log is one of AdGuard Home's most useful diagnostic tools.

It shows:

Client
  ↓
Requested Domain
  ↓
Allowed / Blocked
  ↓
Matching Filter

However, a DNS request does not prove that someone intentionally visited
a website.

Applications frequently contact domains in the background for:

advertising
analytics
telemetry
notifications
updates
content delivery

For deeper investigation, combine AdGuard with packet-capture tools such
as Wireshark or PCAPdroid.

A useful mental model is:

AdGuard Query Log
        │
        └── What DNS name was requested,
            and was it blocked?

Wireshark / PCAPdroid
        │
        └── What network connection
            was actually attempted?

Step 19: Observe DHCP with Wireshark

This setup also provides a useful networking exercise.

Start Wireshark on Fedora and capture traffic on:

wlo1

Use the display filter:

dhcp

Disconnect and reconnect another device to Wi-Fi.

You should be able to observe:

DHCP Discover
DHCP Offer
DHCP Request
DHCP ACK

The DHCP process that is normally hidden inside the router is now being
performed by a service running on your own Fedora machine.

For DNS traffic, use:

dns

as the display filter.

Step 20: Remember That Fedora Is Now Infrastructure

Once Airtel DHCP is disabled, the Fedora computer becomes an important
part of the network.

If Fedora:

shuts down
sleeps
disconnects from Wi-Fi
leaves the house
stops Docker
stops the AdGuard container

then new devices may fail to obtain DHCP leases and existing clients may
lose DNS resolution.

The Airtel router can still have a perfectly good internet connection
while devices appear unable to browse.

For experimentation, a laptop is fine.

For a permanent deployment, move AdGuard to an always-on device such as:

Raspberry Pi
low-power mini PC
home server
dedicated networking appliance

Once family members start asking why the internet stopped when you
rebooted your laptop, the experiment has officially become
infrastructure.

Emergency Recovery

If something goes wrong during the DHCP handover, the fastest recovery
is:

AdGuard DHCP → OFF
Airtel DHCP  → ON

Reconnect your devices afterward.

That restores the Airtel router as the DHCP server.

Full Rollback

If you want to return Fedora to normal router-managed networking, first
disable AdGuard DHCP and re-enable DHCP on the Airtel router.

Then restore NetworkManager:

sudo nmcli connection modify <CONNECTION-UUID> \
  ipv4.method auto \
  ipv4.addresses "" \
  ipv4.gateway "" \
  ipv4.dns "" \
  ipv4.ignore-auto-dns no \
  ipv6.dns "" \
  ipv6.ignore-auto-dns no

Reconnect:

nmcli connection down <CONNECTION-UUID>
nmcli connection up <CONNECTION-UUID>

Verify:

ip addr show wlo1 | grep 'inet '

You should see an address marked:

dynamic

Check the route:

ip route | grep default

It should resemble:

default via 192.xxx.x.1 dev wlo1 proto dhcp

Check DNS:

resolvectl status wlo1

The router should once again appear as the DNS server, for example:

Current DNS Server: 192.xxx.x.1

Remove the firewall rules added for AdGuard:

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --remove-port=53/tcp \
  --permanent

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --remove-port=53/udp \
  --permanent

sudo firewall-cmd \
  --zone=FedoraWorkstation \
  --remove-service=dhcp \
  --permanent

sudo firewall-cmd --reload

If you created a MAC-IP binding for Fedora in the Airtel router, remove
it as well.

You do not have to delete AdGuard.

You can keep the container and its configuration for future use. With
AdGuard DHCP disabled and Fedora returned to router-provided DNS, the
normal network no longer depends on it.

Final Architecture

When everything is enabled, the network is:

                         Internet
                            ▲
                            │
                      Airtel Router
                      192.xxx.x.1
                       Gateway + NAT
                            ▲
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
        Phone              TV              Laptop
          │                 │                 │
          └──────── DNS + DHCP ──────────────┘
                            │
                            ▼
                       Fedora Host
                      192.xxx.x.13
                       AdGuard Home
                        DNS + DHCP

The important idea is not simply that AdGuard blocks advertisements.

The setup separates services that consumer routers normally hide inside
one device:

Routing ≠ DHCP ≠ DNS

The Airtel router can remain the internet gateway while another machine
provides DHCP and DNS to the LAN.

That makes AdGuard Home a useful filtering tool, but it also turns a
normal home network into a practical environment for learning how DNS,
DHCP, Linux networking, Docker, firewalls, and client configuration work
together.

Tracing a Complete HTTP Request with Wireshark: From DNS to TCP to HTTP

Caleb Ajibade — Mon, 07 Sep 2026 17:46:42 +0000

When you type a URL into your browser, it feels almost instantaneous.

You enter:

http://example.com

and a webpage appears.

But underneath that simple action, your computer performs several separate networking operations. It may need to discover the server's IP address, establish a connection, send an HTTP request, receive a response, and eventually close or reuse the connection.

Wireshark lets us watch these operations happen packet by packet.

In this tutorial, we're going to generate a simple HTTP request and trace its journey through:

DNS → TCP → HTTP → TCP termination

We'll also use Wireshark's Flow Graph to turn the packets into a visual conversation between our computer and the servers involved.

What Is Wireshark?

Wireshark is a network protocol analyzer.

It captures network traffic passing through a network interface and allows us to inspect the individual packets.

Instead of seeing:

Browser → Website

Wireshark lets us see what is actually happening:

Application
    ↓
HTTP
    ↓
TCP
    ↓
IP
    ↓
Ethernet / Wi-Fi
    ↓
Network

This makes Wireshark particularly useful for learning networking because concepts such as TCP handshakes, ports, DNS queries, HTTP headers, and IP addresses stop being purely theoretical.

We can actually see them.

What Happens When We Make an HTTP Request?

Before opening Wireshark, let's understand what we're looking for.

Suppose we request:

curl http://example.com

At a simplified level, the process looks like this:

Computer
   │
   │  "What is the IP address of example.com?"
   ▼
DNS Resolver
   │
   │  "example.com is x.x.x.x"
   ▼
Computer
   │
   │  Establish TCP connection
   ▼
Web Server
   │
   │  Send HTTP GET request
   ▼
Web Server
   │
   │  Return HTTP response
   ▼
Computer

There are therefore several different protocols involved in what appears to us as one operation.

We'll trace them individually.

Step 1: Start Wireshark

Open Wireshark.

You'll see a list of network interfaces available on your computer.

Examples might include:

eth0
eno1
wlan0
wlo1
lo

On my Fedora machine, the Wi-Fi interface is wlo1.

If you're unsure which interface you're using, Linux users can run:

ip addr

or:

ip link

Look for the interface that is currently active.

Select that interface in Wireshark and start capturing.

You'll immediately see packets appearing.

Don't worry if there are hundreds of them.

Your computer is constantly communicating over the network even when you aren't actively doing anything.

Step 2: Generate an HTTP Request

We're deliberately going to use HTTP instead of HTTPS.

Why?

HTTPS encrypts HTTP traffic using TLS. Wireshark would still be able to observe the connection, but we wouldn't normally be able to simply read the HTTP request and response.

Plain HTTP makes the experiment much easier to understand.

Open another terminal and run:

curl -v http://example.com

Another useful test site is:

curl -v http://httpforever.com/

The -v option tells curl to display additional information about the request.

Once the request finishes, stop the Wireshark capture.

Now we can begin investigating.

Step 3: Find the HTTP Request

Wireshark probably captured a lot more than our curl command.

Let's filter the traffic.

Enter this into the display filter:

http

You should see packets containing something similar to:

GET / HTTP/1.1

and a response such as:

HTTP/1.1 200 OK

Click the GET packet.

In the packet details panel, expand:

Hypertext Transfer Protocol

You should see information similar to:

GET / HTTP/1.1
Host: example.com
User-Agent: curl/...
Accept: */*

This is the actual HTTP request sent by our computer.

It's no longer an abstract example from a networking textbook.

That's the request that just left our machine.

Step 4: Find the TCP Connection

HTTP doesn't independently deliver the request across the Internet.

With HTTP/1.1 in this example, the HTTP messages are transported using TCP.

Right-click the HTTP GET packet and select:

Follow → TCP Stream

Wireshark will reconstruct the conversation belonging to that TCP connection.

This is also extremely useful when investigating larger packet captures because Wireshark identifies the TCP stream for us.

After identifying the stream number, close the TCP Stream window.

Suppose Wireshark identifies it as stream 4.

We can filter for the entire connection using:

tcp.stream == 4

Now instead of seeing every TCP packet captured by our computer, we see only the TCP conversation containing our HTTP request.

Step 5: Find the TCP Three-Way Handshake

Before our computer could send the HTTP request, it first needed to establish a TCP connection with the web server.

TCP does this using the famous three-way handshake:

Client                         Server
   │                              │
   │──────── SYN ────────────────>│
   │                              │
   │<────── SYN + ACK ────────────│
   │                              │
   │──────── ACK ────────────────>│
   │                              │

The first packet is the client saying:

I want to establish a TCP connection.

The server responds:

I received your request, and I'm ready.

The client then acknowledges the server's response.

The connection is established.

In Wireshark, click the first TCP packet and expand:

Transmission Control Protocol

Then inspect:

Flags

The first packet should have the SYN flag set.

The response should have both SYN and ACK set.

The third packet should have ACK set.

We have now observed the TCP three-way handshake directly.

Step 6: Look at the Ports

While inspecting the TCP information, look at the source and destination ports.

You might see something resembling:

Source Port: 48732
Destination Port: 80

Port 80 is the conventional port for HTTP.

But why is our source port something random like 48732?

Our operating system chooses a temporary ephemeral port for the client side of the connection.

So our connection might effectively look like:

192.168.1.20:48732 → 93.x.x.x:80

The combination of IP addresses and ports allows the operating systems to identify the connection.

This becomes especially important because your computer may have many TCP connections open simultaneously.

Step 7: Inspect the HTTP GET Request

After the TCP connection has been established, we should eventually see:

GET / HTTP/1.1

Select that packet.

Wireshark will show several layers.

Something similar to:

Frame
└── Ethernet II
    └── Internet Protocol Version 4
        └── Transmission Control Protocol
            └── Hypertext Transfer Protocol

This is one of my favorite parts of the experiment because it demonstrates encapsulation.

The HTTP message isn't simply thrown onto the network.

Conceptually, we have:

HTTP Request
     ↓
TCP Segment
     ↓
IP Packet
     ↓
Ethernet/Wi-Fi Frame

Each layer adds information required for its particular job.

HTTP understands things such as:

GET
Host
User-Agent

TCP understands things such as:

Ports
Sequence numbers
Acknowledgements
Flags

IP understands things such as:

Source IP
Destination IP

The lower network layer handles delivery over the local network.

Wireshark lets us expand these layers individually.

Step 8: Inspect the HTTP Response

The server now needs to answer our request.

Look for something similar to:

HTTP/1.1 200 OK

Depending on the website, the exact status code may be different.

Expand the HTTP section.

You might see headers such as:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: ...

The server may then send the HTML document requested by the client.

If the response is sufficiently large, it won't necessarily fit inside a single TCP segment.

You may therefore see multiple packets transporting parts of the response.

TCP is responsible for making sure that this data can be correctly reconstructed by the receiving application.

Step 9: What Happened Before TCP? DNS

There's still something missing.

How did our computer know the server's IP address?

We gave curl a domain name:

example.com

TCP ultimately needs to connect to an IP address.

This is where DNS comes in.

Remove the TCP stream filter and enter:

dns

Look for a DNS query involving the domain you requested.

You may see something resembling:

Standard query
A example.com

The A query asks for an IPv4 address.

The DNS resolver may then return something resembling:

Standard query response
A example.com
A x.x.x.x

Our computer can now use that IP address to establish the TCP connection.

One important caveat is caching.

If your operating system or local DNS resolver already knows the address, you might not see the DNS request you expect on your network interface.

Using a domain that hasn't recently been requested can make the experiment easier.

Step 10: Visualize Everything with Wireshark's Flow Graph

Reading individual packets is useful, but Wireshark has another feature that makes this experiment much easier to understand.

Go to:

Statistics → Flow Graph

Wireshark can represent network communication using arrows between endpoints.

Instead of interpreting dozens of rows, we can get something conceptually similar to:

Client                         Server

  │                              │
  │──────── SYN ────────────────>│
  │                              │
  │<────── SYN, ACK ─────────────│
  │                              │
  │──────── ACK ────────────────>│
  │                              │
  │────── GET / HTTP/1.1 ───────>│
  │                              │
  │<──── HTTP/1.1 200 OK ────────│
  │                              │
  │<──── Response Data ──────────│
  │                              │

This is especially useful when learning TCP because the request becomes a conversation instead of a table of packets.

The Flow Graph can also be useful as a screenshot when documenting the experiment.

Building a Clean Flow Graph

There's one trap here.

If we filter Wireshark using only:

http

and then create our graph from only displayed packets, we may hide the TCP packets.

Our graph would show the HTTP request and response but not the TCP handshake that made them possible.

Instead, identify the TCP stream associated with the HTTP request and use something like:

tcp.stream == 4

Replace 4 with your actual stream number.

Now the Flow Graph can show the entire TCP conversation rather than just HTTP packets.

For a more complete investigation, DNS can be examined separately because DNS resolution is a separate conversation from the TCP connection.

The Complete Journey

After examining the capture, we can finally reconstruct what happened when we executed one simple command:

curl http://example.com

The high-level process was:

1. Application requests example.com
             ↓
2. DNS resolves the domain
             ↓
3. Client obtains server IP
             ↓
4. TCP SYN
             ↓
5. TCP SYN-ACK
             ↓
6. TCP ACK
             ↓
7. TCP connection established
             ↓
8. HTTP GET request
             ↓
9. Server processes request
             ↓
10. HTTP response
             ↓
11. Response data transferred
             ↓
12. TCP connection eventually closed or reused

What appeared to be one operation was actually cooperation between several protocols.

What I Learned

Before doing this experiment, it's easy to think about HTTP as:

Computer → Website → Response

Wireshark exposes how much is hidden behind that abstraction.

DNS answers:

Where is the server?

IP answers:

Where should this packet go?

TCP handles:

How do we reliably exchange this stream of data?

HTTP handles:

What resource does the client want, and what should the server return?

Each protocol solves a different problem.

And together they make something as simple as:

curl http://example.com

possible.

That's what makes Wireshark such a useful tool for learning networking.

Instead of just reading about SYN packets, ACKs, ports, DNS queries, HTTP headers, and encapsulation, you can generate a request yourself and watch every layer do its job.

Setting Up a Local DNS Resolver with Custom Domains on Fedora Using Unbound

Caleb Ajibade — Mon, 07 Sep 2026 15:58:59 +0000

I recently gave myself a simple networking task:

Set up a local DNS resolver and add custom domains.

Before jumping into Unbound and configuration files, it's worth understanding what we're actually building.

If you've used the internet, you've used DNS constantly — usually without realizing it.

What Is DNS?

DNS (Domain Name System) is the system that translates human-readable domain names into IP addresses.

Computers communicate over networks using IP addresses.

For example, a server might have an address like:

142.250.151.100

Humans, however, don't want to remember IP addresses for every website they visit.

We'd much rather type:

google.com

DNS provides the mapping between the two:

google.com
      │
      │ DNS
      ▼
142.250.151.100

You can think of DNS somewhat like the contacts app on your phone.

You don't memorize:

+234 801 234 5678

You save:

John

and your phone knows which number belongs to John.

DNS does something similar:

google.com → 142.250.x.x
github.com → 140.82.x.x

This means when you enter:

https://google.com

your computer first needs to answer an important question:

What IP address should I connect to for google.com?

That's where a DNS resolver comes in.

What Is a DNS Resolver?

A DNS resolver is the component responsible for taking your DNS question and finding an answer.

For example, your browser wants to visit:

google.com

It needs an IP address, so a simplified version of what happens looks like this:

Browser
   │
   │ "What is the IP for google.com?"
   ▼
DNS Resolver
   │
   │ finds the answer
   ▼
142.250.151.100
   │
   ▼
Browser connects to server

Usually, you don't manually choose the resolver every time you browse the internet.

Your computer receives DNS configuration from your network, often through your router.

Your ISP may provide the DNS server, or you might use a public resolver such as Google's or Cloudflare's.

For example:

8.8.8.8 → Google Public DNS
1.1.1.1 → Cloudflare DNS

So DNS is the overall naming system, while a DNS resolver is one of the components that helps you find answers within that system.

That's an important distinction:

DNS
│
└── The overall system for translating names into network information

DNS Resolver
│
└── A service that receives DNS questions and finds/returns answers

Why Run My Own DNS Resolver?

This was the part that made the project interesting.

Instead of relying entirely on whatever DNS resolver my network gives me, I can run one on my own computer.

For example:

My Computer
     │
     │ google.com?
     ▼
My DNS Resolver
     │
     ▼
142.250.x.x

But there's another benefit.

Because I control the resolver, I can teach it names that don't exist on the public internet.

For example, I can create:

myserver.home.arpa

and decide:

myserver.home.arpa → 127.0.0.1

Or:

website.home.arpa → 127.0.0.1

Nobody needs to register these domains with a public domain registrar.

My resolver knows about them because I told it about them.

So our resolver will eventually be able to handle two types of questions:

                    My DNS Resolver
                         │
             ┌───────────┴───────────┐
             │                       │
             ▼                       ▼
       Public domain             My domain
        google.com         website.home.arpa
             │                       │
             ▼                       ▼
       Ask upstream DNS         Local record
             │                       │
             ▼                       ▼
       142.250.x.x              127.0.0.1

That's what we're going to build.

What We're Building

We'll use Unbound, a DNS resolver, and run it locally on Fedora.

By the end, we'll have this:

                    ┌─────────────────────┐
                    │       Unbound       │
                    │     127.0.0.1:53    │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       google.com       myserver.home.arpa   website.home.arpa
              │                │                │
              ▼                └───────┬────────┘
        Upstream DNS                   ▼
              │                    127.0.0.1
              ▼
       Google's IP

Let's build it incrementally.

1. What DNS Am I Already Using?

Before installing anything, I wanted to see how DNS currently worked on my machine.

On Fedora, I ran:

resolvectl status

My Wi-Fi interface showed:

Current DNS Server: 192.168.18.1
DNS Servers: 192.168.18.1

192.168.18.1 is my router.

I also checked:

cat /etc/resolv.conf

and found:

nameserver 127.0.0.53

At first this might seem contradictory.

Why does one command say 192.168.18.1 while another says 127.0.0.53?

Because Fedora is using systemd-resolved.

The path is roughly:

Application
    │
    ▼
127.0.0.53
systemd-resolved
    │
    ▼
192.168.18.1
Router
    │
    ▼
Internet DNS

127.0.0.53 is a local DNS stub provided by systemd-resolved.

The actual upstream DNS server in my case was being provided by my network.

We can see this when querying a domain:

dig google.com

Part of my output looked like:

;; ANSWER SECTION:
google.com.    214    IN    A    142.251.209.110

;; SERVER: 127.0.0.53#53

So normal DNS was already working.

Now I wanted to create another DNS resolver that I controlled myself.

2. Install Unbound

I chose Unbound as the resolver.

Install it on Fedora with:

sudo dnf install unbound

Then verify the installation:

unbound -V

I was running:

Version 1.26.0

Start the service:

sudo systemctl start unbound

Then check its status:

systemctl status unbound

It should show something like:

Active: active (running)

3. Is Unbound Actually Listening for DNS Requests?

DNS normally uses port 53, so we can inspect what's listening on that port:

sudo ss -tulpn | grep ':53'

Among the output, I found:

127.0.0.1:53

being used by Unbound.

This means I now effectively had two local DNS-related services:

127.0.0.53 → systemd-resolved
127.0.0.1  → Unbound

That's an important distinction for the rest of this tutorial.

4. Query Unbound Directly

Normally I can run:

dig google.com

But that uses my system-configured DNS.

dig also lets us explicitly choose which DNS server to query.

The syntax is:

dig @DNS_SERVER DOMAIN

Therefore, to query Unbound:

dig @127.0.0.1 google.com

Initially, mine returned:

status: SERVFAIL

Unbound was running and receiving my request, but wasn't successfully resolving the domain.

So I configured upstream DNS servers.

5. Configure Unbound

Create a custom configuration file:

sudo nano /etc/unbound/conf.d/local.conf

I started with:

server:
    interface: 127.0.0.1
    access-control: 127.0.0.0/8 allow

forward-zone:
    name: "."
    forward-addr: 1.1.1.1
    forward-addr: 8.8.8.8

The important part here is:

forward-zone:
    name: "."

The "." represents the DNS root, so this forwarding rule catches queries that aren't answered locally.

The two forward-addr entries specify upstream DNS resolvers.

Our setup is now:

dig
 │
 │ google.com?
 ▼
Unbound
127.0.0.1
 │
 │ I don't have a local record
 ▼
Upstream DNS
 │
 ▼
google.com IP

6. Validate Before Restarting

Instead of blindly restarting Unbound and hoping the configuration works, we can validate it first:

sudo unbound-checkconf

A valid configuration should give:

unbound-checkconf: no errors in /etc/unbound/unbound.conf

Then restart:

sudo systemctl restart unbound

Now try again:

dig @127.0.0.1 google.com

This time I got:

status: NOERROR

and:

;; ANSWER SECTION:
google.com.    150    IN    A    142.250.151.138
google.com.    150    IN    A    142.250.151.100
google.com.    150    IN    A    142.250.151.101
...

More importantly:

;; SERVER: 127.0.0.1#53

We now have a working local DNS resolver.

7. Creating Our Own Domains

Now for the fun part.

I wanted domains that don't exist on the public internet:

myserver.home.arpa
website.home.arpa

I used home.arpa rather than something like .local.

home.arpa is reserved for naming resources within home networks, while .local has special meaning for multicast DNS (mDNS).

Edit the configuration again:

sudo nano /etc/unbound/conf.d/local.conf

My complete configuration became:

server:
    interface: 127.0.0.1
    access-control: 127.0.0.0/8 allow

    local-zone: "home.arpa." static

    local-data: "myserver.home.arpa. IN A 127.0.0.1"
    local-data: "website.home.arpa. IN A 127.0.0.1"

forward-zone:
    name: "."
    forward-addr: 1.1.1.1
    forward-addr: 8.8.8.8

Check it again:

sudo unbound-checkconf

Then:

sudo systemctl restart unbound

8. Test the Custom Domains

Now let's ask our resolver:

dig @127.0.0.1 myserver.home.arpa

I got:

;; ANSWER SECTION:
myserver.home.arpa.    3600    IN    A    127.0.0.1

Try the second domain:

dig @127.0.0.1 website.home.arpa

Result:

;; ANSWER SECTION:
website.home.arpa.    3600    IN    A    127.0.0.1

Both queries took essentially no time:

Query time: 0 msec

That's because Unbound already knows the answers. They're defined directly in its configuration.

9. What Does the `A` Mean?

Consider:

website.home.arpa. IN A 127.0.0.1

This is a DNS A record.

An A record maps a hostname to an IPv4 address:

website.home.arpa
        │
        │ A record
        ▼
    127.0.0.1

We could point another name at another machine on our network:

local-data: "server.home.arpa. IN A 192.168.18.50"

Now our resolver would answer:

server.home.arpa → 192.168.18.50

This is essentially the same fundamental concept used by public DNS.

The difference is that these particular records only exist inside our resolver.

10. Local Domains vs Internet Domains

We can now ask the same DNS server three questions:

dig @127.0.0.1 google.com

dig @127.0.0.1 myserver.home.arpa

dig @127.0.0.1 website.home.arpa

Conceptually:

                        Unbound
                      127.0.0.1
                          │
           ┌──────────────┼──────────────┐
           │              │              │
           ▼              ▼              ▼

      google.com     myserver...    website...
           │              │              │
           ▼              ▼              ▼
      Not local        LOCAL          LOCAL
           │              │              │
           ▼              └──────┬───────┘
     Upstream DNS                ▼
           │                 127.0.0.1
           ▼
     Google IP

That's the part that made DNS click for me.

A DNS resolver isn't necessarily some mysterious server sitting somewhere on the internet.

I can run one on my own laptop.

And I can tell it:

If someone asks for this name, give them this IP address.

11. Why Didn't I Change Fedora's DNS?

There was one more decision to make.

I could configure Fedora to use:

127.0.0.1

as its normal DNS server.

Then applications would automatically use Unbound.

For this experiment, however, I decided not to change my system DNS.

My normal Fedora DNS remains:

Applications
     │
     ▼
systemd-resolved
127.0.0.53
     │
     ▼
Router
     │
     ▼
Internet

And my experimental resolver remains:

dig @127.0.0.1
       │
       ▼
    Unbound
       │
       ├── custom domains
       │
       └── upstream DNS

That means I can experiment with Unbound without accidentally breaking DNS for the rest of my system.

When I want to test it, I explicitly use:

dig @127.0.0.1 example.com

12. Starting and Stopping the Resolver

Because I'm using this as a local experiment, I don't necessarily need Unbound running every time my computer starts.

Start it with:

sudo systemctl start unbound

Check it:

systemctl status unbound

And stop it:

sudo systemctl stop unbound

If I eventually decide I want it permanently available, I can enable it:

sudo systemctl enable --now unbound

What I Learned

This was a small project, but it cleared up several concepts I'd previously treated as separate things.

I now have a much better mental model of:

What DNS actually does
What a DNS resolver is
The difference between a DNS resolver and the overall DNS system
The difference between my system's DNS stub and its upstream DNS server
Why 127.0.0.53 appears in /etc/resolv.conf
How DNS uses port 53
How to query a specific DNS server with dig
How DNS forwarding works
What an A record does
How custom/private DNS names can exist without being registered publicly
How a local resolver can answer some queries itself and forward others upstream

The final setup is surprisingly small:

                    My Laptop
                       │
              ┌────────┴─────────┐
              │                  │
        Normal Fedora       My DNS Lab
              │                  │
       127.0.0.53           127.0.0.1
              │                  │
    systemd-resolved           Unbound
              │                  │
           Router         ┌──────┴──────┐
              │           │             │
         Internet     Local DNS      Internet
                      records        forwarding

And all it took to create a domain of my own was essentially:

local-data: "website.home.arpa. IN A 127.0.0.1"

Obviously, this is only the beginning of DNS.

But building a tiny working version locally made the bigger system much easier to understand.

Environment used:

Fedora Linux
Unbound 1.26
systemd-resolved
dig / BIND utilities

Building Vercel-Style Pull Request Preview Deployments with Jenkins, GitHub Checks, Terraform, AWS EC2, Trivy and SonarQube

Caleb Ajibade — Mon, 31 Aug 2026 19:41:00 +0000

Like most people, I spent my weekend building CI/CD pipelines.

The challenge I gave myself was simple to explain:

Can I recreate the basic developer experience of Vercel preview deployments, but using Jenkins and infrastructure I control?

I wanted this flow:

A developer opens or updates a pull request.
Jenkins automatically discovers the PR.
Jenkins tests the code as it would exist after merging into the target branch.
The application is built into a Docker image.
The code and image go through security/quality checks.
The image is pushed to Amazon ECR.
Terraform provisions or reuses an EC2 preview host.
Jenkins deploys a temporary container to that host.
Jenkins health-checks the deployment.
Jenkins publishes a WhisperGate Preview check back to the GitHub pull request.
Clicking Details on the GitHub check opens the live preview.

The finished experience looks deceptively simple:

Open PR
   ↓
Jenkins runs
   ↓
Build + Scan + Push + Provision + Deploy
   ↓
GitHub PR
   ├── ✓ Jenkins
   └── ✓ WhisperGate Preview
           └── Details → http://preview-host:port

Getting there involved more moving parts than I expected: Jenkins agents, Docker socket permissions, GitHub App authentication, GitHub's old Status API versus the newer Checks API, AWS IAM, ECR, Terraform state, EC2 cloud-init timing, SSH, dynamic ports, cron cleanup, SonarQube, Trivy, and a few mistakes that produced very confusing behavior.

This article walks through the whole system from scratch.

What we are building

The architecture in this tutorial is intentionally understandable rather than maximally sophisticated.

The CI infrastructure runs Jenkins with a dedicated Docker-capable agent. SonarQube is available to Jenkins on the same Docker network. AWS is used for the preview infrastructure.

                         GitHub
                           │
                           │ Pull request / webhook
                           ▼
                  ┌───────────────────┐
                  │ Jenkins Controller│
                  └─────────┬─────────┘
                            │ schedules job
                            ▼
                  ┌───────────────────┐
                  │ Jenkins Agent     │
                  │ label: agent1     │
                  │                   │
                  │ Node / npm        │
                  │ Docker CLI        │
                  │ AWS CLI           │
                  │ Terraform         │
                  │ Trivy             │
                  │ SonarScanner      │
                  └───────┬───────────┘
                          │
          ┌───────────────┼────────────────┐
          │               │                │
          ▼               ▼                ▼
     SonarQube         Amazon ECR      Terraform/AWS
                                            │
                                            ▼
                                      ┌───────────┐
                                      │ EC2 host  │
                                      │ Docker    │
                                      └─────┬─────┘
                                            │
                                  temporary container
                                            │
                                            ▼
                                     Preview URL
                                            │
                                            ▼
                                      GitHub Check

A few deliberate choices:

Jenkins is a Multibranch Pipeline, not a single static Pipeline job.
PRs use the merge discovery strategy so CI tests the PR merged with the current target branch.
The Jenkins agent owns the build tools; the controller stays mostly orchestration-only.
Docker images are stored in Amazon ECR.
Terraform creates the EC2 host, key pair registration, security group and an EC2 IAM role.
The EC2 host receives ECR read access through an instance profile, not copied AWS access keys.
Jenkins uses SSH only for the deployment step.
Preview containers expire automatically.
GitHub authentication uses a GitHub App, because publishing GitHub Checks requires it.
The final PR shows a normal Jenkins check plus a separate WhisperGate Preview check whose detailsURL is the live deployment.

1. Prerequisites

You should already be comfortable with the basics of:

Git and GitHub
Docker
Linux shell commands
Jenkins Pipelines
basic AWS concepts
Terraform fundamentals

You will need:

a GitHub repository
Docker and Docker Compose
an AWS account
an AWS IAM principal Jenkins can use for infrastructure/ECR operations
an existing or bootstrapped ECR repository
an EC2 SSH key pair private key stored in Jenkins, with the public half passed into Terraform
a Jenkins controller
a Jenkins build agent
SonarQube
a GitHub App
the Jenkins plugins listed later in this guide

This tutorial uses:

AWS region: eu-north-1
Jenkins agent label: agent1
Application container port: 3001
Preview host port scheme: 3000 + Jenkins BUILD_NUMBER
ECR repository example: ci-cd/jenkins
SonarQube project key: whispergate

Replace all account-specific values with your own.

2. Repository structure

I keep infrastructure code in a normal committed terraform/ directory.

It is important not to confuse that with Terraform's generated .terraform/ directory.

A useful layout is:

.
├── Dockerfile
├── Jenkinsfile
├── package.json
├── package-lock.json
├── sonar-project.properties
├── deploy-preview.sh
├── delete-cron.sh
├── src/
└── terraform/
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    └── versions.tf

Your .gitignore should include Terraform-generated state/cache files, but not the provider lock file:

# Terraform local/generated data
.terraform/
*.tfstate
*.tfstate.*
tfplan
crash.log

# Keep this committed
# .terraform.lock.hcl

# Local app secrets
.env
.env.*

# Generated CI files
preview-url.txt
trivy-report-*.txt
sonar-metrics.json

Commit:

terraform/.terraform.lock.hcl

Do not commit:

terraform/.terraform/
terraform/tfplan
terraform.tfstate

The tfplan file is created by CI for that particular run. It is not source code.

3. Run Jenkins, the build agent and SonarQube

My build agent is a custom image based on:

jenkins/ssh-agent:alpine-jdk21

The agent needs more than Java because it performs the actual CI work.

Dockerfile.agent

Create Dockerfile.agent:

FROM jenkins/ssh-agent:alpine-jdk21

USER root

ARG DOCKER_GID=969

RUN apk add --no-cache \
    bash \
    curl \
    git \
    openssh-client \
    docker-cli \
    nodejs \
    npm \
    aws-cli \
    terraform

# Install Trivy CLI
RUN curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh \
    | sh -s -- -b /usr/local/bin

# The Docker socket is mounted from the host. The group inside the container
# needs the same GID as the group that owns /var/run/docker.sock on the host.
RUN addgroup -g "${DOCKER_GID}" docker \
    && adduser jenkins docker

USER jenkins

Why the Docker GID matters

The agent uses the host's Docker daemon through:

/var/run/docker.sock

Run this on the Docker host:

stat -c '%g' /var/run/docker.sock

or:

getent group docker

Use that GID as DOCKER_GID.

On one Fedora setup this was 969, which is why that number appears in the example. It is not universal.

Also understand the security consequence:

Access to the Docker socket is effectively highly privileged host access.

Only use this pattern for a trusted Jenkins agent. Do not run untrusted arbitrary PR code on an agent that can control your host Docker daemon.

docker-compose.yml

A compact development setup looks like this:

services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - jenkins_home:/var/jenkins_home
    networks:
      - jenkins_network

  agent1:
    build:
      context: .
      dockerfile: Dockerfile.agent
      args:
        DOCKER_GID: ${DOCKER_GID}
    container_name: agent1
    environment:
      JENKINS_AGENT_SSH_PUBKEY: ${JENKINS_AGENT_SSH_PUBKEY}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - jenkins_network

  sonarqube:
    image: sonarqube:community
    container_name: sonarqube
    ports:
      - "9000:9000"
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_temp:/opt/sonarqube/temp
    networks:
      - jenkins_network

networks:
  jenkins_network:

volumes:
  jenkins_home:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  sonarqube_temp:

Create a .env for Compose:

DOCKER_GID=969
JENKINS_AGENT_SSH_PUBKEY=ssh-ed25519 AAAA...your-public-key...

Do not commit this file if it contains environment-specific values you do not want public.

Start everything:

docker compose up -d --build

Verify:

docker ps

You should have:

jenkins
agent1
sonarqube

4. Generate the Jenkins-to-agent SSH key

The jenkins/ssh-agent image can authorize a supplied SSH public key.

Generate a dedicated key:

ssh-keygen -t ed25519 -f ./jenkins-agent-key -C "jenkins-agent"

You get:

jenkins-agent-key
jenkins-agent-key.pub

Put the public key in:

JENKINS_AGENT_SSH_PUBKEY

Put the private key in Jenkins Credentials.

In Jenkins:

Manage Jenkins
→ Credentials
→ System
→ Global credentials
→ Add Credentials

Use:

Kind: SSH Username with private key
Username: jenkins
Private Key: Enter directly
ID: agent1-ssh

Paste the contents of jenkins-agent-key.

5. Register `agent1` in Jenkins

Go to:

Manage Jenkins
→ Nodes
→ New Node

Use something like:

Node name: agent1
Type: Permanent Agent
Remote root directory: /home/jenkins/agent
Labels: agent1
Usage: Use this node as much as possible
Launch method: Launch agents via SSH
Host: agent1
Credentials: agent1-ssh
Host key verification strategy: choose an appropriate strategy

Because the controller and agent are on the same Compose network, agent1 resolves by container name.

After saving, Jenkins should connect to it.

Verify from a Pipeline or agent shell:

node --version
npm --version
docker version
aws --version
terraform version
trivy --version
git --version

A useful Docker test:

docker ps

If this fails with permission errors, re-check the Docker socket GID.

6. Install the Jenkins plugins

Install these from:

Manage Jenkins
→ Plugins

Core plugins for this setup:

GitHub Branch Source
Checks API
GitHub Checks
Credentials Binding
AWS Credentials
SonarQube Scanner
Workspace Cleanup
Pipeline
Git

Why the Checks plugins matter:

Checks API exposes the generic Jenkins publishChecks Pipeline step.
GitHub Checks implements that API for GitHub.
GitHub Branch Source understands GitHub branches and pull requests and can use GitHub App credentials.

Without the GitHub Checks implementation, a publishChecks step does not magically create a GitHub Check Run.

7. Configure SonarQube

Open:

http://localhost:9000

Set up the SonarQube instance and create a project/token.

In Jenkins, store the token:

Manage Jenkins
→ Credentials
→ Add Credentials

Example:

Kind: Secret text
Secret: <SONAR_TOKEN>
ID: sonarqube-token

Then configure the server:

Manage Jenkins
→ System
→ SonarQube servers

Example:

Name: SonarQube
Server URL: http://sonarqube:9000
Server authentication token: sonarqube-token

The hostname is sonarqube, not localhost, because the Jenkins agent/controller communicates over the Docker network.

Then configure the scanner tool:

Manage Jenkins
→ Tools
→ SonarQube Scanner installations

Set:

Name: SonarScanner

This name must match the Pipeline:

def scannerHome = tool 'SonarScanner'

sonar-project.properties

For a TypeScript/Node project, a minimal starting point is:

sonar.projectKey=whispergate
sonar.projectName=WhisperGate
sonar.sources=src
sonar.sourceEncoding=UTF-8

Add test/coverage configuration according to your project.

A Jenkins stage can then be:

stage('SonarQube Analysis') {
    steps {
        script {
            def scannerHome = tool 'SonarScanner'

            withSonarQubeEnv('SonarQube') {
                sh "${scannerHome}/bin/sonar-scanner"
            }
        }

        archiveArtifacts(
            artifacts: '.scannerwork/report-task.txt',
            allowEmptyArchive: true
        )
    }
}

During development I had multiple SonarQube stages while testing report paths and API output. For a clean final pipeline, consolidate that into one analysis stage unless you intentionally need separate scans.

8. Configure Trivy

The custom agent image already installs Trivy.

You can scan the source tree:

trivy fs .

and/or the final container image:

trivy image your-image:tag

A report-producing Jenkins stage:

stage('Image Scan') {
    steps {
        sh '''
            TIMESTAMP=$(date -u +"%Y%m%dT%H%M%SZ")

            trivy image \
                --severity CRITICAL,HIGH,MEDIUM \
                --output "trivy-report-${TIMESTAMP}.txt" \
                "$ECR_IMAGE:$TAG"
        '''

        archiveArtifacts(
            artifacts: 'trivy-report-*.txt',
            allowEmptyArchive: true
        )
    }
}

When you first add scanning, I recommend getting the report generation working before making every finding fatal.

When you are ready to enforce a gate, use an exit code:

trivy image \
  --exit-code 1 \
  --severity CRITICAL,HIGH \
  "$IMAGE"

That turns security findings into a CI policy rather than just an artifact.

9. Create the Amazon ECR repository

The application image needs somewhere private to live.

For example:

ci-cd/jenkins

You can create the repository from the AWS console or CLI:

aws ecr create-repository \
  --repository-name ci-cd/jenkins \
  --region eu-north-1

A bootstrap detail that matters

In the pipeline we are going to push the image before the EC2 deployment.

That means the ECR repository must already exist.

You can absolutely create ECR with Terraform, but do it in a bootstrap stack or move ECR creation earlier than the image push. Do not write a pipeline that attempts:

docker push

to a repository Terraform has not created yet.

10. Create Jenkins AWS credentials

Create a dedicated IAM user/role for Jenkins.

For ECR push, AWS documents permissions similar to:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:CompleteLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:InitiateLayerUpload",
        "ecr:BatchCheckLayerAvailability",
        "ecr:PutImage",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:eu-north-1:<AWS_ACCOUNT_ID>:repository/ci-cd/jenkins"
    },
    {
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    }
  ]
}

That last statement is worth highlighting.

One very easy failure is:

AccessDeniedException: ecr:GetAuthorizationToken

ecr:GetAuthorizationToken needs:

"Resource": "*"

Repository-scoped image actions and registry authentication are not exactly the same thing.

Terraform also needs permissions to manage the EC2 resources in this tutorial. In a learning AWS account, you may start broader and then tighten the policy once you know which API calls your configuration makes. Do not use a broad production credential simply because it is convenient.

Add the AWS credential in Jenkins:

Manage Jenkins
→ Credentials
→ Global
→ Add Credentials

Use:

Kind: AWS Credentials
ID: jenkins-ecr
Access Key: ...
Secret Key: ...

The AWS Credentials Jenkins plugin exposes these inside:

withCredentials([[
    $class: 'AmazonWebServicesCredentialsBinding',
    credentialsId: 'jenkins-ecr'
]]) {
    // ...
}

11. Authenticate Docker to ECR

The standard ECR flow is:

aws ecr get-login-password --region eu-north-1 \
  | docker login \
      --username AWS \
      --password-stdin \
      <AWS_ACCOUNT_ID>.dkr.ecr.eu-north-1.amazonaws.com

Then tag and push:

docker tag \
  whispergate:$BUILD_NUMBER \
  <AWS_ACCOUNT_ID>.dkr.ecr.eu-north-1.amazonaws.com/ci-cd/jenkins:$BUILD_NUMBER

docker push \
  <AWS_ACCOUNT_ID>.dkr.ecr.eu-north-1.amazonaws.com/ci-cd/jenkins:$BUILD_NUMBER

A Jenkins version:

stage('Push to ECR') {
    steps {
        withCredentials([[
            $class: 'AmazonWebServicesCredentialsBinding',
            credentialsId: 'jenkins-ecr'
        ]]) {
            sh '''
                set -e

                aws sts get-caller-identity

                aws ecr get-login-password --region "$AWS_REGION" \
                  | docker login \
                      --username AWS \
                      --password-stdin "$ECR_REGISTRY"

                docker push "$ECR_IMAGE:$TAG"
            '''
        }
    }
}

I used aws sts get-caller-identity while building this because it quickly answers the question:

"Are the credentials broken, or is only ECR broken?"

That is a useful CI debugging habit.

12. Create the EC2 SSH credential Jenkins will use

Generate a dedicated EC2 key locally:

ssh-keygen -t ed25519 -f whispergate-preview-key -C "whispergate-preview"

Store the private key in Jenkins:

Kind: SSH Username with private key
ID: aws-ec2-ssh-key
Username: ubuntu
Private Key: whispergate-preview-key

Do not commit it.

Terraform will receive the public half dynamically from Jenkins:

ssh-keygen -y -f "$SSH_KEY_FILE"

That lets the private key stay entirely inside Jenkins Credentials.

13. Store the preview environment file in Jenkins

If the application needs runtime environment variables, do not bake them into the image.

Create a file such as:

NODE_ENV=preview
DATABASE_URL=...
APP_KEY=...

Store it in Jenkins as a Secret file:

ID: whispergate-preview-env

The Pipeline receives it temporarily as:

file(
    credentialsId: 'whispergate-preview-env',
    variable: 'PREVIEW_ENV_FILE'
)

The deployment later copies it to the EC2 host and sets restrictive permissions:

chmod 600 ~/.whispergate-preview.env

For a more mature production design, consider AWS Secrets Manager or SSM Parameter Store. A Jenkins Secret File is fine for understanding the mechanics and keeping secrets out of Git.

14. Terraform: provision the preview host

The Terraform in this section is a cleaned reference implementation of the architecture. It generalizes account-specific values and removes experimental details.

It assumes:

a default VPC exists
you want one EC2 preview host
Jenkins can reach the EC2 host over SSH
the host will expose temporary preview ports
the EC2 instance can pull ECR images using an IAM instance profile

terraform/versions.tf

terraform {
  required_version = ">= 1.6"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  # Optional but recommended:
  #
  # backend "s3" {
  #   bucket  = "<YOUR_TERRAFORM_STATE_BUCKET>"
  #   key     = "whispergate/preview/terraform.tfstate"
  #   region  = "eu-north-1"
  #   encrypt = true
  # }
}

If you use an S3 backend, bootstrap that bucket first. Terraform cannot depend on a backend bucket that does not exist yet.

Remote state matters here because you generally want repeated Jenkins runs to understand that the preview EC2 instance already exists instead of blindly creating a new host every time.

terraform/variables.tf

variable "aws_region" {
  type    = string
  default = "eu-north-1"
}

variable "instance_type" {
  type        = string
  description = "Choose an EC2 size appropriate for your account and workload."
  default     = "t3.micro"
}

variable "public_ssh_key" {
  type        = string
  description = "Public key corresponding to the private key stored in Jenkins."
}

variable "ssh_cidr" {
  type        = string
  description = "CIDR allowed to SSH into the preview host."
}

Do not blindly assume an instance type is free-tier eligible. AWS pricing and free-tier rules change. Check your account and region.

terraform/main.tf

provider "aws" {
  region = var.aws_region
}

data "aws_vpc" "default" {
  default = true
}

data "aws_ami" "ubuntu" {
  most_recent = true

  owners = ["099720109477"] # Canonical

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }
}

resource "aws_key_pair" "preview" {
  key_name   = "whispergate-preview"
  public_key = var.public_ssh_key
}

resource "aws_security_group" "preview" {
  name        = "whispergate-preview"
  description = "WhisperGate PR preview host"
  vpc_id      = data.aws_vpc.default.id

  ingress {
    description = "SSH from Jenkins/admin network"
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = [var.ssh_cidr]
  }

  # Demo architecture: preview containers are exposed directly by port.
  # Replace this with a reverse proxy/load balancer for a stronger design.
  ingress {
    description = "Temporary preview ports"
    from_port   = 3000
    to_port     = 3999
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

data "aws_iam_policy_document" "ec2_assume_role" {
  statement {
    effect = "Allow"

    principals {
      type        = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }

    actions = ["sts:AssumeRole"]
  }
}

resource "aws_iam_role" "preview" {
  name               = "whispergate-preview"
  assume_role_policy = data.aws_iam_policy_document.ec2_assume_role.json
}

resource "aws_iam_role_policy_attachment" "ecr_read" {
  role       = aws_iam_role.preview.name
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
}

resource "aws_iam_instance_profile" "preview" {
  name = "whispergate-preview"
  role = aws_iam_role.preview.name
}

resource "aws_instance" "app_server" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = var.instance_type
  key_name                    = aws_key_pair.preview.key_name
  vpc_security_group_ids      = [aws_security_group.preview.id]
  iam_instance_profile        = aws_iam_instance_profile.preview.name
  associate_public_ip_address = true

  user_data = <<-EOF
    #!/bin/bash
    set -eux

    apt-get update -y
    apt-get install -y docker.io awscli

    systemctl enable docker
    systemctl start docker

    usermod -aG docker ubuntu
  EOF

  tags = {
    Name = "whispergate-preview"
  }
}

The IAM instance profile is an important design decision.

The EC2 server needs to run:

aws ecr get-login-password

so it can pull the private image.

Do not solve this by copying the Jenkins AWS access key onto EC2.

Give the instance an IAM role instead.

terraform/outputs.tf

output "EC2_url" {
  description = "Public DNS name of the preview host."
  value       = aws_instance.app_server.public_dns
}

Jenkins can consume that output with:

terraform output -raw EC2_url

This is one of my favorite parts of the design: Terraform creates the infrastructure, then exposes exactly the machine-readable value the deployment stage needs.

15. Terraform stages in Jenkins

Initialization and validation:

stage('Terraform Init & Validate') {
    steps {
        withCredentials([[
            $class: 'AmazonWebServicesCredentialsBinding',
            credentialsId: 'jenkins-ecr'
        ]]) {
            dir('terraform') {
                sh 'terraform init -input=false'
                sh 'terraform validate'
            }
        }
    }
}

Plan:

stage('Terraform Plan') {
    steps {
        withCredentials([
            [
                $class: 'AmazonWebServicesCredentialsBinding',
                credentialsId: 'jenkins-ecr'
            ],
            sshUserPrivateKey(
                credentialsId: 'aws-ec2-ssh-key',
                keyFileVariable: 'SSH_KEY_FILE'
            )
        ]) {
            dir('terraform') {
                sh '''
                    terraform plan \
                      -var "public_ssh_key=$(ssh-keygen -y -f "$SSH_KEY_FILE")" \
                      -var "ssh_cidr=<YOUR_JENKINS_PUBLIC_IP>/32" \
                      -out=tfplan
                '''
            }
        }
    }
}

Apply the same saved plan:

stage('Terraform Apply') {
    steps {
        withCredentials([[
            $class: 'AmazonWebServicesCredentialsBinding',
            credentialsId: 'jenkins-ecr'
        ]]) {
            dir('terraform') {
                sh 'terraform apply -auto-approve tfplan'
            }
        }
    }
}

For production infrastructure, an approval gate can be appropriate:

stage('Approval Gate') {
    steps {
        input(
            message: 'Apply this infrastructure change?',
            ok: 'Deploy'
        )
    }
}

For an automated disposable PR-preview workflow, a manual gate on every preview would defeat much of the point, so decide based on the environment you are provisioning.

16. Why `terraform apply` finishing does not mean EC2 is ready

This was one of the subtler problems.

Terraform can report that the EC2 instance exists while cloud-init is still:

updating packages
installing Docker
installing/configuring AWS CLI
starting services

If Jenkins immediately SSHes in and runs Docker commands, the deployment can fail even though Terraform itself succeeded.

So the deployment stage waits for:

/var/lib/cloud/instance/boot-finished

and also verifies:

aws
docker
Docker service

A readiness loop:

attempt=0

while [ "$attempt" -le 3 ]; do
    if ssh -o StrictHostKeyChecking=no \
        -i "$SSH_KEY_FILE" \
        "$SSH_USER@$EC2_HOST" \
        'test -f /var/lib/cloud/instance/boot-finished &&
         command -v aws >/dev/null &&
         command -v docker >/dev/null &&
         sudo systemctl is-active --quiet docker'
    then
        echo "EC2 host is ready for deployment."
        break
    fi

    if [ "$attempt" -eq 3 ]; then
        echo "EC2 did not finish cloud-init in time."

        ssh -o StrictHostKeyChecking=no \
            -i "$SSH_KEY_FILE" \
            "$SSH_USER@$EC2_HOST" \
            'sudo tail -n 100 /var/log/cloud-init-output.log || true'

        exit 1
    fi

    sleep 100
    attempt=$((attempt + 1))
done

The cloud-init-output.log fallback is extremely useful. It turns "SSH deployment failed" into actual evidence.

For a hardened setup, replace StrictHostKeyChecking=no with proper known-host management.

17. Create `deploy-preview.sh`

The exact deployment script will depend on your app. This is a cleaned version of the pattern used in this system.

The app listens on container port:

Each Jenkins build receives a host port:

3000 + BUILD_NUMBER

So:

Build 1   → host port 3001
Build 2   → host port 3002
Build 23  → host port 3023

Create deploy-preview.sh:

#!/usr/bin/env bash
set -euo pipefail

BUILD_ID="${1:?build id required}"
ENV_FILE="${2:?environment file required}"

AWS_REGION="eu-north-1"
AWS_ACCOUNT_ID="<AWS_ACCOUNT_ID>"
ECR_REPOSITORY="ci-cd/jenkins"

REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
IMAGE="${REGISTRY}/${ECR_REPOSITORY}:${BUILD_ID}"

CONTAINER_NAME="whispergate-preview-${BUILD_ID}"
HOST_PORT=$((3000 + BUILD_ID))
CONTAINER_PORT=3001

# Six-hour temporary preview
EXPIRES_AT="$(date -u -d '+6 hours' '+%Y-%m-%dT%H:%M:%SZ')"

echo "Deploying ${IMAGE}"
echo "Container: ${CONTAINER_NAME}"
echo "Host port: ${HOST_PORT}"
echo "Expires at: ${EXPIRES_AT}"

# Replace the same build's container if this script is re-run.
docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true

docker pull "${IMAGE}"

docker run -d \
  --name "${CONTAINER_NAME}" \
  --env-file "${ENV_FILE}" \
  -p "${HOST_PORT}:${CONTAINER_PORT}" \
  --label "preview=true" \
  --label "expires-at=${EXPIRES_AT}" \
  "${IMAGE}"

echo "${CONTAINER_NAME}"

The labels are important:

preview=true
expires-at=<UTC timestamp>

They give the cleanup job a machine-readable way to identify preview containers without maintaining another database.

18. Create `delete-cron.sh`

A lightweight preview system needs lifecycle management.

Otherwise every PR/build leaves a container running forever.

Create:

#!/usr/bin/env bash
set -euo pipefail

NOW_EPOCH="$(date -u +%s)"

docker ps -aq --filter "label=preview=true" | while read -r CONTAINER_ID; do
    [ -z "$CONTAINER_ID" ] && continue

    EXPIRES_AT="$(
        docker inspect \
          --format '{{ index .Config.Labels "expires-at" }}' \
          "$CONTAINER_ID"
    )"

    [ -z "$EXPIRES_AT" ] && continue

    EXPIRES_EPOCH="$(date -u -d "$EXPIRES_AT" +%s 2>/dev/null || echo 0)"

    if [ "$EXPIRES_EPOCH" -gt 0 ] && [ "$EXPIRES_EPOCH" -le "$NOW_EPOCH" ]; then
        NAME="$(docker inspect --format '{{.Name}}' "$CONTAINER_ID" | sed 's#^/##')"

        echo "Removing expired preview: $NAME ($EXPIRES_AT)"
        docker rm -f "$CONTAINER_ID"
    fi
done

Install it in cron from the Jenkins deployment:

(crontab -l 2>/dev/null | grep -v delete-cron; \
 echo "*/15 * * * * bash /home/ubuntu/delete-cron.sh") | crontab -

This checks every 15 minutes.

The design is intentionally simple:

Container labels = state
Cron = garbage collector

For a larger platform, you would likely move this responsibility into a proper preview-environment controller or lifecycle service.

19. Deploy the preview from Jenkins

The deployment stage needs:

AWS credentials for Terraform/API operations
the EC2 SSH private key
the application secret environment file

Example:

stage('Deploy Preview to AWS') {
    when {
        changeRequest()
    }

    steps {
        withCredentials([
            [
                $class: 'AmazonWebServicesCredentialsBinding',
                credentialsId: 'jenkins-ecr'
            ],
            sshUserPrivateKey(
                credentialsId: 'aws-ec2-ssh-key',
                keyFileVariable: 'SSH_KEY_FILE',
                usernameVariable: 'SSH_USER'
            ),
            file(
                credentialsId: 'whispergate-preview-env',
                variable: 'PREVIEW_ENV_FILE'
            )
        ]) {
            dir('terraform') {
                sh '''
                    set -e

                    EC2_HOST=$(terraform output -raw EC2_url)

                    if [ -z "$EC2_HOST" ]; then
                        echo "Terraform did not return an EC2 hostname."
                        exit 1
                    fi

                    PORT=$((3000 + BUILD_NUMBER))

                    attempt=0

                    while [ "$attempt" -le 3 ]; do
                        if ssh -o StrictHostKeyChecking=no \
                            -i "$SSH_KEY_FILE" \
                            "$SSH_USER@$EC2_HOST" \
                            'test -f /var/lib/cloud/instance/boot-finished &&
                             command -v aws >/dev/null &&
                             command -v docker >/dev/null &&
                             sudo systemctl is-active --quiet docker'
                        then
                            echo "EC2 host is ready for deployment."
                            break
                        fi

                        if [ "$attempt" -eq 3 ]; then
                            echo "EC2 did not finish cloud-init in time."

                            ssh -o StrictHostKeyChecking=no \
                                -i "$SSH_KEY_FILE" \
                                "$SSH_USER@$EC2_HOST" \
                                'sudo tail -n 100 /var/log/cloud-init-output.log || true'

                            exit 1
                        fi

                        echo "Waiting for EC2 cloud-init..."
                        sleep 100
                        attempt=$((attempt + 1))
                    done

                    scp -o StrictHostKeyChecking=no \
                        -i "$SSH_KEY_FILE" \
                        ../deploy-preview.sh \
                        ../delete-cron.sh \
                        "$PREVIEW_ENV_FILE" \
                        "$SSH_USER@$EC2_HOST:~/"

                    ENV_BASENAME=$(basename "$PREVIEW_ENV_FILE")

                    ssh -o StrictHostKeyChecking=no \
                        -i "$SSH_KEY_FILE" \
                        "$SSH_USER@$EC2_HOST" bash -s <<REMOTE
                        set -e

                        mv ~/${ENV_BASENAME} ~/.whispergate-preview.env
                        chmod 600 ~/.whispergate-preview.env

                        aws ecr get-login-password --region eu-north-1 \
                          | docker login \
                              --username AWS \
                              --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.eu-north-1.amazonaws.com

                        bash ~/deploy-preview.sh \
                          $BUILD_NUMBER \
                          ~/.whispergate-preview.env

                        (crontab -l 2>/dev/null | grep -v delete-cron; \
                         echo "*/15 * * * * bash /home/$SSH_USER/delete-cron.sh") \
                         | crontab -
REMOTE

                    attempt=1

                    while [ "$attempt" -le 10 ]; do
                        if curl -sf "http://$EC2_HOST:$PORT/health" > /dev/null; then
                            printf "http://%s:%s\\n" \
                                "$EC2_HOST" \
                                "$PORT" \
                                > ../preview-url.txt

                            echo "Preview live at http://$EC2_HOST:$PORT"
                            exit 0
                        fi

                        sleep 3
                        attempt=$((attempt + 1))
                    done

                    echo "Preview failed health check."

                    ssh -o StrictHostKeyChecking=no \
                        -i "$SSH_KEY_FILE" \
                        "$SSH_USER@$EC2_HOST" \
                        "docker ps -a --filter name=whispergate-preview-$BUILD_NUMBER;
                         docker logs --tail 100 whispergate-preview-$BUILD_NUMBER || true"

                    exit 1
                '''
            }
        }
    }
}

20. Why the health check matters

Do not publish a preview URL merely because:

docker run

returned successfully.

A container can start and then immediately crash.

Instead, Jenkins polls:

/health

In this setup:

curl -sf "http://$EC2_HOST:$PORT/health"

runs up to 10 times, with three seconds between attempts.

Only after that succeeds do we create:

preview-url.txt

The file becomes the contract between:

deployment stage

and:

GitHub publishing stage

That keeps the check-publishing code independent from Terraform and SSH details.

21. The most important GitHub/Jenkins part: use a GitHub App

Initially it is tempting to connect Jenkins using a GitHub Personal Access Token.

A PAT can work for repository discovery and classic commit statuses.

But the goal here is a real GitHub Check Run with a custom Details URL.

For Jenkins' GitHub Checks integration, use a GitHub App with Checks: Read & write.

22. Create the GitHub App

On GitHub:

Profile
→ Settings
→ Developer settings
→ GitHub Apps
→ New GitHub App

Use a name such as:

WhisperGate Jenkins

Set a homepage URL, for example your repository/project page.

Set the webhook URL to:

https://<YOUR-JENKINS-HOST>/github-webhook/

For event-driven builds, GitHub must be able to reach this endpoint.

If Jenkins is running only on your laptop, a public GitHub webhook cannot directly reach localhost. Use a securely exposed HTTPS endpoint/tunnel or host Jenkins somewhere reachable. Polling/scanning can be useful while experimenting, but webhooks are the better final event path.

GitHub App repository permissions

For GitHub Branch Source, Jenkins documents permissions including:

Commit statuses: Read & write
Contents: Read-only
Metadata: Read-only
Pull requests: Read-only

The GitHub Checks plugin adds:

Checks: Read & write

So the useful set for this tutorial is:

Checks             Read & write
Commit statuses    Read & write
Contents           Read-only
Metadata           Read-only
Pull requests      Read-only

Use the minimum access your workflow needs.

For the simplest compatibility with GitHub Branch Source, Jenkins' GitHub App guide currently recommends enabling the needed webhook events; its guide says to enable all events. You can tighten event subscriptions later after validating your exact workflow.

Create the App.

23. Do not confuse the Client Secret with the private key

This caused some confusion during setup because the GitHub App page exposes OAuth-style values such as:

Client ID
Client secrets

Those are not the credential Jenkins GitHub Branch Source is asking for.

Scroll to:

Private keys

and click:

Generate a private key

GitHub downloads a .pem file.

You need:

App ID
Private key (.pem)

not the OAuth client secret.

24. Convert the GitHub App private key for Jenkins

The Jenkins GitHub Branch Source guide shows converting the key to PKCS#8:

openssl pkcs8 \
  -topk8 \
  -inform PEM \
  -outform PEM \
  -in github-app.private-key.pem \
  -out converted-github-app.pem \
  -nocrypt

Inspect it:

cat converted-github-app.pem

It should look like:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

Keep this secret.

25. Install the GitHub App on the repository

On the GitHub App settings page:

Install App

For a private project, prefer:

Only select repositories

and choose the repository Jenkins needs.

This keeps the App's installation scope small.

26. Add the GitHub App credential to Jenkins

Go to:

Manage Jenkins
→ Credentials
→ Global credentials
→ Add Credentials

Use:

Kind: GitHub App
ID: github-app
Description: WhisperGate GitHub App
App ID: <NUMERIC_GITHUB_APP_ID>
Key: contents of converted-github-app.pem

Use the numeric App ID, not the Client ID.

After selecting a valid GitHub App credential in the GitHub Branch Source configuration, Jenkins should be able to verify the App.

27. Create/configure the Multibranch Pipeline

Create:

New Item
→ Multibranch Pipeline

Under:

Branch Sources
→ Add source
→ GitHub

Select:

Credentials: github-app
Repository: your repository

This is important:

The GitHub App belongs in the Multibranch GitHub source configuration.

You do not need to wrap publishChecks in a random PAT credential block.

28. Configure PR discovery

For:

Discover pull requests from origin

choose:

Merging the pull request with the current target branch revision

This tells Jenkins to test:

PR head + current target branch

instead of only testing the PR tip in isolation.

Conceptually:

feature commit
      │
      ├──────────┐
      │          │
      │       current dev/main
      │          │
      └──── merge test revision
                 │
                 ▼
              Jenkins

That is valuable because a PR can be individually valid but fail when combined with changes already present in the target branch.

29. Avoid duplicate PR builds

There are two separate ways duplicate-looking Jenkins activity can happen:

Cause A: PR discovery set to "Both"

If PR discovery is configured to build both:

Head
Merge

then Jenkins is intentionally building two different revisions.

For this tutorial, use:

Merge

only.

Cause B: branch discovery also builds the same source branch

If branch discovery is configured in a way that builds feature branches independently while the PR job also builds them, you can get:

branch job
PR merge job

For a PR-oriented flow, choose branch discovery rules that do not duplicate feature-branch PR builds. A common choice is:

Exclude branches that are also filed as PRs

Then keep normal builds for long-lived branches such as dev, staging or main as your workflow requires.

30. Do not manually checkout `dev` in the Jenkinsfile

This was one of the most important bugs in the pipeline.

A Multibranch Pipeline already performs a special checkout for the PR.

The log can look like:

PR head
   +
target branch
   ↓
synthetic merge commit
   ↓
Declarative: Checkout SCM

If you then add:

stage('Checkout') {
    steps {
        git branch: 'dev',
            credentialsId: 'github-pat',
            url: 'https://github.com/example/repo.git'
    }
}

you destroy the entire point of the PR merge checkout.

Jenkins successfully checks out the PR merge revision, then your custom stage replaces the workspace with dev.

The pipeline "works", but it is testing/deploying the wrong code.

Correct solution

Delete that manual stage.

With:

pipeline {
    agent { label 'agent1' }

    stages {
        stage('Build') {
            // ...
        }
    }
}

Declarative Pipeline performs its normal SCM checkout automatically.

If you intentionally disable the default checkout, use:

checkout scm

because scm represents the exact branch/PR revision chosen by the Multibranch job.

31. Configure GitHub Checks in the Branch Source

After installing Checks API and GitHub Checks, open:

Multibranch Pipeline
→ Configure
→ Branch Sources
→ GitHub
→ Behaviors
→ Add
→ Status Checks Properties

In the final setup I want:

Skip publishing status checks:
    unchecked

Status checks name:
    Jenkins

Skip GitHub Branch Source notifications:
    checked

Why?

GitHub Branch Source can publish old-style Status API entries such as:

continuous-integration/jenkins/branch
continuous-integration/jenkins/pr-merge

At the same time, the GitHub Checks plugin publishes the newer:

Jenkins

Check Run.

Without changing anything, your PR can suddenly show three Jenkins-looking checks.

The GitHub Checks plugin explicitly supports disabling the Branch Source status notifications.

Checking:

Skip GitHub Branch Source notifications

removes those legacy status notifications while keeping the new Checks API result.

Do not check:

Skip publishing status checks

because that would disable the new status-check behavior you actually want.

After making this change, trigger a new commit/build. Existing statuses on older commits do not disappear retroactively.

32. Publish the preview URL to GitHub

This is the payoff.

After deployment succeeds, Jenkins has:

preview-url.txt

containing something like:

http://ec2-xx-xx-xx-xx.eu-north-1.compute.amazonaws.com:3023

Now use:

publishChecks

with:

detailsURL: previewUrl

Example:

stage('Publish Preview URL') {
    when {
        allOf {
            changeRequest()
            expression { fileExists('preview-url.txt') }
        }
    }

    steps {
        script {
            def previewUrl = readFile('preview-url.txt').trim()

            currentBuild.description = "Preview: ${previewUrl}"

            echo "Preview URL: ${previewUrl}"

            publishChecks(
                name: 'WhisperGate Preview',
                title: 'Preview deployment ready',
                summary: 'Your PR preview is live.',
                text: "Preview: ${previewUrl}",
                detailsURL: previewUrl,
                conclusion: 'SUCCESS'
            )
        }
    }
}

The critical field is:

detailsURL: previewUrl

GitHub renders the check with a clickable Details destination.

The PR now has two useful checks with different responsibilities:

✓ Jenkins
    Overall CI/build status

✓ WhisperGate Preview
    Preview deployment ready
    Details → live application

This separation is cleaner than hijacking the normal Jenkins build link.

33. Full cleaned Jenkinsfile

The Jenkinsfile below is a consolidated reference version of the working design.

It intentionally removes experimental duplicate SonarQube stages and the earlier Docker Hub push because ECR is the registry used for deployment.

It also avoids the manual dev checkout that would overwrite the Multibranch PR merge revision.

pipeline {
    agent { label 'agent1' }

    environment {
        AWS_REGION     = 'eu-north-1'
        AWS_ACCOUNT_ID = '<AWS_ACCOUNT_ID>'

        ECR_REGISTRY   = "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
        ECR_REPOSITORY = 'ci-cd/jenkins'
        ECR_IMAGE      = "${ECR_REGISTRY}/${ECR_REPOSITORY}"

        TAG = "${env.BUILD_NUMBER}"
    }

    stages {

        /*
         * No manual Git checkout here.
         *
         * In a Multibranch Pipeline, Jenkins' automatic SCM checkout
         * preserves the PR/merge revision selected by GitHub Branch Source.
         */

        stage('Install & Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'

                sh '''
                    docker build \
                      -t "$ECR_IMAGE:$TAG" \
                      .
                '''
            }
        }

        stage('Test') {
            steps {
                sh 'npm test --if-present'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                script {
                    def scannerHome = tool 'SonarScanner'

                    withSonarQubeEnv('SonarQube') {
                        sh "${scannerHome}/bin/sonar-scanner"
                    }
                }

                archiveArtifacts(
                    artifacts: '.scannerwork/report-task.txt',
                    allowEmptyArchive: true
                )
            }
        }

        stage('Trivy Image Scan') {
            steps {
                sh '''
                    TIMESTAMP=$(date -u +"%Y%m%dT%H%M%SZ")

                    trivy image \
                      --severity CRITICAL,HIGH,MEDIUM \
                      --output "trivy-report-${TIMESTAMP}.txt" \
                      "$ECR_IMAGE:$TAG"
                '''

                archiveArtifacts(
                    artifacts: 'trivy-report-*.txt',
                    allowEmptyArchive: true
                )
            }
        }

        stage('Push to ECR') {
            steps {
                withCredentials([[
                    $class: 'AmazonWebServicesCredentialsBinding',
                    credentialsId: 'jenkins-ecr'
                ]]) {
                    sh '''
                        set -e

                        export AWS_DEFAULT_REGION="$AWS_REGION"

                        echo "Testing AWS identity..."
                        aws sts get-caller-identity

                        echo "Logging Docker into ECR..."
                        aws ecr get-login-password \
                            --region "$AWS_REGION" \
                          | docker login \
                                --username AWS \
                                --password-stdin "$ECR_REGISTRY"

                        docker push "$ECR_IMAGE:$TAG"
                    '''
                }
            }
        }

        stage('Terraform Init & Validate') {
            when {
                changeRequest()
            }

            steps {
                withCredentials([[
                    $class: 'AmazonWebServicesCredentialsBinding',
                    credentialsId: 'jenkins-ecr'
                ]]) {
                    dir('terraform') {
                        sh 'terraform init -input=false'
                        sh 'terraform validate'
                    }
                }
            }
        }

        stage('Terraform Plan') {
            when {
                changeRequest()
            }

            steps {
                withCredentials([
                    [
                        $class: 'AmazonWebServicesCredentialsBinding',
                        credentialsId: 'jenkins-ecr'
                    ],
                    sshUserPrivateKey(
                        credentialsId: 'aws-ec2-ssh-key',
                        keyFileVariable: 'SSH_KEY_FILE'
                    )
                ]) {
                    dir('terraform') {
                        sh '''
                            terraform plan \
                              -var "public_ssh_key=$(ssh-keygen -y -f "$SSH_KEY_FILE")" \
                              -var "ssh_cidr=<YOUR_JENKINS_PUBLIC_IP>/32" \
                              -out=tfplan
                        '''
                    }
                }
            }
        }

        stage('Terraform Apply') {
            when {
                changeRequest()
            }

            steps {
                withCredentials([[
                    $class: 'AmazonWebServicesCredentialsBinding',
                    credentialsId: 'jenkins-ecr'
                ]]) {
                    dir('terraform') {
                        sh 'terraform apply -auto-approve tfplan'
                    }
                }
            }
        }

        stage('Deploy Preview to AWS') {
            when {
                changeRequest()
            }

            steps {
                withCredentials([
                    [
                        $class: 'AmazonWebServicesCredentialsBinding',
                        credentialsId: 'jenkins-ecr'
                    ],
                    sshUserPrivateKey(
                        credentialsId: 'aws-ec2-ssh-key',
                        keyFileVariable: 'SSH_KEY_FILE',
                        usernameVariable: 'SSH_USER'
                    ),
                    file(
                        credentialsId: 'whispergate-preview-env',
                        variable: 'PREVIEW_ENV_FILE'
                    )
                ]) {
                    dir('terraform') {
                        sh '''
                            set -e

                            EC2_HOST=$(terraform output -raw EC2_url)

                            if [ -z "$EC2_HOST" ]; then
                                echo "Terraform did not return an EC2 hostname."
                                exit 1
                            fi

                            PORT=$((3000 + BUILD_NUMBER))

                            echo "Waiting for EC2 host: $EC2_HOST"

                            attempt=0

                            while [ "$attempt" -le 3 ]; do
                                if ssh \
                                    -o StrictHostKeyChecking=no \
                                    -i "$SSH_KEY_FILE" \
                                    "$SSH_USER@$EC2_HOST" \
                                    'test -f /var/lib/cloud/instance/boot-finished &&
                                     command -v aws >/dev/null &&
                                     command -v docker >/dev/null &&
                                     sudo systemctl is-active --quiet docker'
                                then
                                    echo "EC2 host is ready for deployment."
                                    break
                                fi

                                if [ "$attempt" -eq 3 ]; then
                                    echo "EC2 did not finish cloud-init in time."

                                    ssh \
                                        -o StrictHostKeyChecking=no \
                                        -i "$SSH_KEY_FILE" \
                                        "$SSH_USER@$EC2_HOST" \
                                        'sudo tail -n 100 /var/log/cloud-init-output.log || true'

                                    exit 1
                                fi

                                sleep 100
                                attempt=$((attempt + 1))
                            done

                            scp \
                                -o StrictHostKeyChecking=no \
                                -i "$SSH_KEY_FILE" \
                                ../deploy-preview.sh \
                                ../delete-cron.sh \
                                "$PREVIEW_ENV_FILE" \
                                "$SSH_USER@$EC2_HOST:~/"

                            ENV_BASENAME=$(basename "$PREVIEW_ENV_FILE")

                            ssh \
                                -o StrictHostKeyChecking=no \
                                -i "$SSH_KEY_FILE" \
                                "$SSH_USER@$EC2_HOST" bash -s <<REMOTE
                                set -e

                                mv ~/${ENV_BASENAME} ~/.whispergate-preview.env
                                chmod 600 ~/.whispergate-preview.env

                                aws ecr get-login-password \
                                    --region $AWS_REGION \
                                  | docker login \
                                        --username AWS \
                                        --password-stdin $ECR_REGISTRY

                                bash ~/deploy-preview.sh \
                                  $BUILD_NUMBER \
                                  ~/.whispergate-preview.env

                                (crontab -l 2>/dev/null | grep -v delete-cron; \
                                 echo "*/15 * * * * bash /home/$SSH_USER/delete-cron.sh") \
                                 | crontab -
REMOTE

                            attempt=1

                            while [ "$attempt" -le 10 ]; do
                                if curl -sf \
                                    "http://$EC2_HOST:$PORT/health" \
                                    > /dev/null
                                then
                                    printf "http://%s:%s\\n" \
                                        "$EC2_HOST" \
                                        "$PORT" \
                                        > ../preview-url.txt

                                    echo "Preview live at http://$EC2_HOST:$PORT"

                                    exit 0
                                fi

                                sleep 3
                                attempt=$((attempt + 1))
                            done

                            echo "Preview did not pass health check."

                            ssh \
                                -o StrictHostKeyChecking=no \
                                -i "$SSH_KEY_FILE" \
                                "$SSH_USER@$EC2_HOST" \
                                "docker ps -a --filter name=whispergate-preview-$BUILD_NUMBER;
                                 docker logs --tail 100 whispergate-preview-$BUILD_NUMBER || true"

                            exit 1
                        '''
                    }
                }
            }
        }

        stage('Publish Preview URL') {
            when {
                allOf {
                    changeRequest()
                    expression {
                        fileExists('preview-url.txt')
                    }
                }
            }

            steps {
                script {
                    def previewUrl = readFile('preview-url.txt').trim()

                    currentBuild.description = "Preview: ${previewUrl}"

                    echo "Preview URL: ${previewUrl}"

                    publishChecks(
                        name: 'WhisperGate Preview',
                        title: 'Preview deployment ready',
                        summary: 'Your PR preview is live.',
                        text: "Preview: ${previewUrl}",
                        detailsURL: previewUrl,
                        conclusion: 'SUCCESS'
                    )
                }
            }
        }
    }

    post {
        success {
            echo "Build #${env.BUILD_NUMBER} succeeded."
        }

        failure {
            echo "Build #${env.BUILD_NUMBER} failed."
        }

        always {
            echo "Build #${env.BUILD_NUMBER} finished."
            cleanWs()
        }
    }
}

34. A note about `BUILD_NUMBER` versus `CHANGE_ID`

The working preview design above uses:

BUILD_NUMBER

for:

image tags
preview container names
preview ports

That is easy to implement because every Jenkins run already has a unique number.

But it means a single PR can create:

PR #23
  build 101 → preview 101
  build 102 → preview 102
  build 103 → preview 103

A stronger Vercel-like design uses:

env.CHANGE_ID

for the preview identity:

PR #23 → whispergate-preview-23

Then each push replaces the same PR environment.

For example:

PR #23 opened
    ↓
preview-23

new commit pushed
    ↓
replace preview-23

PR #23 closed
    ↓
destroy preview-23

I would treat that as the next lifecycle improvement rather than mixing it into the first working version.

35. What the final GitHub PR should show

When everything is connected correctly, a PR build should eventually show something conceptually like:

All checks have passed

✓ Jenkins
  Build completed successfully

✓ WhisperGate Preview
  Preview deployment ready
  Details →

Clicking Details on WhisperGate Preview opens:

http://<EC2_PUBLIC_DNS>:<PREVIEW_PORT>

The GitHub UI is now the entry point for the developer.

They do not need to:

open Jenkins
inspect Terraform output
SSH into EC2
search a console log for a port

That is the developer-experience win.

36. Troubleshooting: `publishChecks` runs but GitHub shows no Check

Symptom:

[Pipeline] publishChecks

appears in Jenkins, but GitHub shows:

Checks 0

and only old statuses such as:

continuous-integration/jenkins/branch
continuous-integration/jenkins/pr-merge

Check:

Checks API plugin is installed.
GitHub Checks plugin is installed.
GitHub Branch Source is using a GitHub App, not only a PAT.
The GitHub App has:

   Checks: Read & write

The App is installed on the repository.
Jenkins is using the correct App ID/private key.
You generated the private key, not an OAuth client secret.
The GitHub App credential is selected in the Multibranch Branch Source.

37. Troubleshooting: three Jenkins checks appear

Symptom:

continuous-integration/jenkins/branch
continuous-integration/jenkins/pr-merge
Jenkins

This is not necessarily three different CI systems.

It is usually:

GitHub Branch Source old Status API
+
GitHub Checks new Checks API

Fix:

Multibranch
→ Configure
→ Branch Sources
→ GitHub
→ Behaviors
→ Add
→ Status Checks Properties

Check:

Skip GitHub Branch Source notifications

Leave:

Skip publishing status checks

unchecked.

Trigger a new commit afterward.

38. Troubleshooting: the PR pipeline deploys `dev` instead of the PR

Look at the checkout logs.

If you see Jenkins first do:

Merging target branch into PR head
Checking out Revision <synthetic-merge>

and then later see:

Checking out Revision <dev SHA>

your Jenkinsfile probably contains a manual checkout like:

git branch: 'dev', ...

Delete it.

In a Multibranch Pipeline, trust the scm selected by Jenkins.

This bug is especially dangerous because the pipeline may remain completely green while testing the wrong revision.

39. Troubleshooting: EC2 exists but deployment says Docker/AWS is missing

Terraform is finished; cloud-init is not.

Check:

sudo tail -n 100 /var/log/cloud-init-output.log

and:

test -f /var/lib/cloud/instance/boot-finished

Wait until the bootstrap script is actually complete.

Do not use an arbitrary sleep 10 and hope.

Use readiness conditions.

40. Troubleshooting: `ecr:GetAuthorizationToken` AccessDenied

Validate credentials:

aws sts get-caller-identity

If that succeeds but:

aws ecr get-login-password

fails, inspect IAM.

Remember:

{
  "Action": "ecr:GetAuthorizationToken",
  "Resource": "*"
}

must be allowed.

Then make sure the repository-specific push actions are also allowed.

41. Troubleshooting: Docker works on the host but not on the Jenkins agent

Check the mounted socket:

docker exec -it agent1 ls -l /var/run/docker.sock

Check the Jenkins user's groups:

docker exec -it agent1 id jenkins

Check the host socket GID:

stat -c '%g' /var/run/docker.sock

The group permissions inside the container need to match.

42. Troubleshooting: SonarQube is reachable from your browser but not Jenkins

From your browser:

http://localhost:9000

works because your browser is outside Docker.

From the Jenkins Docker network, Jenkins should use:

http://sonarqube:9000

not:

http://localhost:9000

Inside the Jenkins container, localhost means Jenkins itself.

43. Security improvements I would make before calling this production-grade

This architecture is a learning/preview platform, not the finished version of a production deployment system.

Here are the first things I would harden.

1. Stop exposing a range of raw ports publicly

The demo uses:

EC2_HOST:3001
EC2_HOST:3002
EC2_HOST:3003
...

A cleaner architecture is:

pr-23.preview.example.com
        ↓
wildcard DNS
        ↓
TLS
        ↓
reverse proxy / ALB / ingress layer
        ↓
container

That removes the need to expose 3000-3999 to the public internet.

2. Restrict SSH properly

For learning, it is common to temporarily allow broad SSH while debugging.

Do not leave:

0.0.0.0/0 → port 22

in a real environment.

Restrict it to the Jenkins egress IP, VPN, bastion or another trusted network.

3. Replace `StrictHostKeyChecking=no`

Manage host keys or known hosts instead.

StrictHostKeyChecking=no is convenient while iterating, but it removes a layer of SSH authenticity verification.

4. Avoid long-lived AWS user credentials where possible

A stronger Jenkins deployment would run in AWS with an IAM role, use OIDC/federation, or otherwise obtain short-lived AWS credentials.

The EC2 side already follows the better model by using an instance profile for ECR pull.

5. Treat Docker socket access as privileged

The Jenkins agent can control the host Docker daemon.

That means you should not treat arbitrary external fork PRs as safe workloads.

If you want to build untrusted code, isolate builds more aggressively.

6. Make security checks enforce policy

Once you trust the scans:

Critical vulnerability → fail build
Quality gate failed     → fail build
Tests failed            → fail build

Reporting is step one.

Enforcement is step two.

44. Where I would take the preview platform next

The first working version gets the developer experience right:

PR → CI → temporary deployment → clickable preview

The next improvements are mostly lifecycle and routing.

Stable PR identities

Use:

CHANGE_ID

instead of:

BUILD_NUMBER

for container/environment identity.

Destroy previews when PRs close

Time-based expiry works, but PR lifecycle is a better signal.

Eventually:

PR closed
    ↓
Jenkins/GitHub event
    ↓
remove preview immediately

Keep TTL cleanup as a safety net.

Wildcard domains

Move toward:

pr-23.preview.whispergate.example

instead of:

ec2-public-host:3023

HTTPS

Use an ALB, Caddy, Traefik, Nginx, Cloudflare or another edge/reverse-proxy approach to terminate TLS.

Reuse infrastructure

Provisioning the EC2 host should not necessarily happen from scratch for every PR.

Terraform state can keep the base host stable while Jenkins creates/removes preview containers on it.

At a larger scale, you might graduate to:

ECS
Kubernetes
Nomad
serverless container platforms

but building the simpler EC2 version first makes the underlying mechanics much easier to understand.

Better observability

Add:

centralized application logs
deployment duration metrics
preview inventory
container CPU/memory monitoring
alerting for failed preview cleanup
GitHub comments/check annotations for scan summaries

45. What I learned building this

The most interesting part of this project was not any individual tool.

It was the boundaries between them.

Terraform can say:

EC2 created

while cloud-init is still installing Docker.

Docker can say:

container started

while the application is about to crash.

Jenkins can say:

PR checkout successful

and then your own checkout stage can silently replace the PR with dev.

publishChecks can execute in Jenkins while your GitHub authentication is still incapable of publishing the kind of Check Run you expect.

GitHub can show three checks that all appear to be "Jenkins" but are actually two different GitHub reporting APIs.

AWS credentials can successfully call STS and still fail ECR because one specific permission is missing.

That is what made the project useful.

A CI/CD pipeline is not one system.

It is a chain of contracts:

GitHub
  → Jenkins SCM
  → workspace revision
  → build
  → scanner
  → image
  → registry
  → Terraform
  → EC2
  → cloud-init
  → Docker
  → application health
  → preview URL
  → GitHub Check

The pipeline is only as reliable as the weakest contract between two stages.

46. Final result

At the end, the workflow I wanted was finally there:

Developer opens PR
        ↓
Jenkins discovers it
        ↓
Jenkins tests merge revision
        ↓
Build Docker image
        ↓
SonarQube + Trivy
        ↓
Push to ECR
        ↓
Terraform provisions/reuses EC2
        ↓
SSH deploy temporary container
        ↓
Health check
        ↓
Write preview URL
        ↓
publishChecks(detailsURL: previewUrl)
        ↓
GitHub PR shows:

✓ Jenkins
✓ WhisperGate Preview
      Details → Live deployment

There is still a lot I would improve before calling it a production preview platform.

But that is exactly why I liked this project.

Something as simple as a Preview button turns out to be a very good excuse to learn CI/CD, cloud infrastructure, IAM, networking, containers, security scanning, Bash, SSH, Terraform state, GitHub integrations and deployment lifecycle management at the same time.

Reference documentation

The following official/project documentation is useful when reproducing this setup:

Jenkins GitHub Checks plugin: https://plugins.jenkins.io/github-checks/
Jenkins Checks API plugin: https://plugins.jenkins.io/checks-api/
Jenkins GitHub Branch Source — GitHub App authentication guide: https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc
GitHub Docs — registering a GitHub App: https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app
GitHub Docs — managing private keys for GitHub Apps: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps
Jenkins AWS Credentials plugin: https://plugins.jenkins.io/aws-credentials/
AWS — pushing images to ECR: https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html
AWS — IAM permissions for ECR image push: https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-push-iam.html
HashiCorp — Terraform output values: https://developer.hashicorp.com/terraform/language/values/outputs
HashiCorp — terraform output: https://developer.hashicorp.com/terraform/cli/commands/output
Trivy installation: https://www.trivy.dev/docs/latest/getting-started/installation/
Jenkins SonarQube Scanner plugin: https://plugins.jenkins.io/sonar/
Jenkins Workspace Cleanup plugin: https://plugins.jenkins.io/ws-cleanup/

A final note about the code in this article

The snippets here are a cleaned and generalized version of a real working learning pipeline.

I intentionally:

replaced AWS account-specific identifiers with placeholders
removed secrets
consolidated experimental duplicate stages
removed the manual branch checkout that interfered with Multibranch PR merge builds
removed an unnecessary duplicate Docker Hub push from the final reference flow
added explicit PR-only guards to the infrastructure/deployment stages
kept the raw EC2 hostname/port model because that was the milestone being demonstrated

That makes the tutorial safer to publish and easier for someone else to reproduce without copying environment-specific mistakes.

DEV Community: Caleb Ajibade

Deploying a Next.js and Spring Boot Monorepo to One EC2 Instance

1. Containerise both applications

2. Run both containers behind Nginx

3. Use two private ECR repositories

4. Build and deploy through GitHub Actions

5. Verification and next steps

How to Set Up AdGuard Home as Network-Wide DNS and DHCP on an Airtel Router

What We Are Building

Before You Start

Step 1: Create the AdGuard Home Docker Compose Project

Step 2: Why We Use Host Networking

Step 3: Complete the Initial AdGuard Setup

Step 4: Give the Fedora Computer a Static IP

Step 5: Reserve the Fedora Address on the Airtel Router

Step 6: Configure AdGuard's DNS Listeners

Step 7: Do Not Disable systemd-resolved

Step 8: Test AdGuard Locally

Step 9: Open DNS in Fedora's Firewall

Step 10: Test AdGuard from Another Device

Step 11: Allow DHCP Through Fedora's Firewall

Step 12: Configure AdGuard's DHCP Server

Step 13: Disable DHCP on the Airtel Router

Step 14: Reconnect a Client

Step 15: Verify DNS Filtering

Step 16: Add Blocklists Carefully

Step 17: Configure Per-Device Policies

Step 18: Understand the Query Log

Step 19: Observe DHCP with Wireshark

Step 20: Remember That Fedora Is Now Infrastructure

Emergency Recovery

Full Rollback

Final Architecture

Tracing a Complete HTTP Request with Wireshark: From DNS to TCP to HTTP

What Is Wireshark?

What Happens When We Make an HTTP Request?

Step 1: Start Wireshark

Step 2: Generate an HTTP Request

Step 3: Find the HTTP Request

Step 4: Find the TCP Connection

Step 5: Find the TCP Three-Way Handshake

Step 6: Look at the Ports

Step 7: Inspect the HTTP GET Request

Step 8: Inspect the HTTP Response

Step 9: What Happened Before TCP? DNS

Step 10: Visualize Everything with Wireshark's Flow Graph

Building a Clean Flow Graph

The Complete Journey

What I Learned

Setting Up a Local DNS Resolver with Custom Domains on Fedora Using Unbound

What Is DNS?

What Is a DNS Resolver?

Why Run My Own DNS Resolver?

What We're Building

1. What DNS Am I Already Using?

2. Install Unbound

3. Is Unbound Actually Listening for DNS Requests?

4. Query Unbound Directly

5. Configure Unbound

6. Validate Before Restarting

7. Creating Our Own Domains

8. Test the Custom Domains

9. What Does the A Mean?

10. Local Domains vs Internet Domains

11. Why Didn't I Change Fedora's DNS?

12. Starting and Stopping the Resolver

What I Learned

Building Vercel-Style Pull Request Preview Deployments with Jenkins, GitHub Checks, Terraform, AWS EC2, Trivy and SonarQube

What we are building

1. Prerequisites

2. Repository structure

3. Run Jenkins, the build agent and SonarQube

Dockerfile.agent

Why the Docker GID matters

docker-compose.yml

4. Generate the Jenkins-to-agent SSH key

5. Register agent1 in Jenkins

6. Install the Jenkins plugins

7. Configure SonarQube

sonar-project.properties

9. What Does the `A` Mean?

5. Register `agent1` in Jenkins

16. Why `terraform apply` finishing does not mean EC2 is ready

17. Create `deploy-preview.sh`

18. Create `delete-cron.sh`

30. Do not manually checkout `dev` in the Jenkinsfile

34. A note about `BUILD_NUMBER` versus `CHANGE_ID`

36. Troubleshooting: `publishChecks` runs but GitHub shows no Check

38. Troubleshooting: the PR pipeline deploys `dev` instead of the PR

40. Troubleshooting: `ecr:GetAuthorizationToken` AccessDenied

3. Replace `StrictHostKeyChecking=no`