SOLUTION_GUIDE
md22 kBSolution of Lab 6: CI/CD
CI/CD Part 1: solution guide
This lab automates the path from git push to a running app. On every push to main, a GitHub
Actions workflow runs the Playwright tests against the full Compose stack, then builds the frontend
and backend images and pushes them to a private Docker Hub repository. When that workflow ends
green, a GitHub webhook reaches a small deploy server on your machine through ngrok, which pulls
the new images and restarts the stack.
There is no starter.zip. You start from the finished lab 05 app: unzip
04_docker_containers/starter.zip, copy 05_docker_compose/solution/ over it, and delete
src/auth.js. Put that project in a new GitHub repository whose default branch is main.
solution/ holds only what this lab adds or changes: the workflow, two edited app files, a README,
and deploy/, which is the handout's auth-app-deploy/ folder (your machine's side, kept outside
the app repository).
1. The pipeline you will build
In the handout's diagram, the workflow is .github/workflows/cicd.yml and runs on GitHub. On your
machine, deploy/deploy_server.py (port 9000, reached through ngrok) runs pull and up -d on
deploy/docker-compose.deploy.yml. CI builds, Docker Hub stores, your machine only pulls.
2. Docker Hub
2.1 Account and private repository. Create one private repository named auth-app. The free
plan allows one private repository, so both images go into it, told apart by their tag:
<docker-id>/auth-app:frontend and <docker-id>/auth-app:backend.
2.2 Access tokens. Create two personal access tokens: github-actions with Read & Write (GitHub
pushes images) and local-deploy with Read-only (your machine pulls them). Copy each one when it
is shown: Docker never shows it again. Your machine only ever pulls, so it gets a token that cannot
overwrite your images if it leaks.
2.3 Log in on your machine. The images are private, so the machine that pulls them must be
logged in. Paste the local-deploy token as the password:
docker login --username <your-docker-id>The deploy server runs docker compose pull as your user, so it uses this login. Without it, the
pull fails and the server logs Deploy FAILED (see the output above).
3. GitHub Actions
3.1 Store the credentials in GitHub
In the repository, Settings → Secrets and variables → Actions: a variable DOCKERHUB_USERNAME
(your Docker ID) and a secret DOCKERHUB_TOKEN (the github-actions token). The solution's
README.md records these settings in a table. The username is not secret (it is part of the image
name), the token is: GitHub encrypts it and masks it in logs. Set both before your first push,
otherwise the image name becomes /auth-app and the login fails.
3.2 How a GitHub workflow works
The solution's workflow has two jobs. Each runs on a fresh ubuntu-latest machine, so the second
job checks out the code again. needs: test makes the second job wait for the first and skip if it
failed: that one line keeps a broken commit off Docker Hub.
3.3 Authenticating to Docker Hub
The handout's login step is used unchanged, in the build-and-push job. The test job never logs
in: it builds and runs everything on the runner.
3.4 The workflow
The top of .github/workflows/cicd.yml:
File: .github/workflows/cicd.yml
name: CI/CD
on:
push:
branches: [main]
# Two quick pushes: the older run is cancelled, so an old image can't overwrite a newer one.
concurrency:
group: cicd-${{ github.ref }}
cancel-in-progress: true
env:
IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/auth-appname: CI/CD must be exact: the deploy server compares the run's name with it. concurrency is
an addition to the handout: without it, two runs can push at once and the older one can finish
last. A cancelled run ends with conclusion cancelled, which the deploy server ignores.
Job test. It sets POSTGRES_PASSWORD: ci-only-password as a job-level env:, checks out the
code, sets up Node 24 with the npm cache, runs npm ci and
npx playwright install --with-deps chromium, then:
- name: Start db, backend and frontend
run: docker compose up -d --build --wait
- name: Wait until the API answers through nginx
run: curl --fail --silent --show-error --retry 30 --retry-delay 1 --retry-all-errors http://localhost:5173/api/health
# playwright.config.js has reuseExistingServer: true, so it tests the stack on :5173
# instead of starting the Vite dev server.
- name: Run the Playwright tests
run: npx playwright test
- name: Show container logs
if: failure()
run: docker compose logs
- name: Keep the HTML report
if: always()
uses: actions/upload-artifact@v7
with:
name: playwright-report
path: playwright-report/
retention-days: 7.envis git-ignored since lab 05, so it is not on the runner, anddocker-compose.ymlrefuses to start withoutPOSTGRES_PASSWORD. Compose also reads variables from the shell, so the job'senv:is enough. That database dies with the runner, so a fixed password is fine there and nowhere else.--waitreturns once the containers run anddbis healthy. The backend has no healthcheck, so "running" does not yet mean "listening". Thecurlloop covers that:/api/healthgoes through nginx to the backend, which runsSELECT 1on Postgres, so a 200 means all three services work.playwright.config.jsis unchanged from lab 05. ItswebServerhasreuseExistingServer: true, and nginx already answers onhttp://localhost:5173, so Playwright tests the real stack instead of startingnpm run dev. Only Chromium is installed because the config has a singlechromiumproject.if: failure()prints container logs only when something broke.if: always()keeps the HTML report even when tests fail, which is when you need it. It appears as theplaywright-reportartifact on the run's page for 7 days.
Job build-and-push. It has needs: test, checks out the code, runs
docker/setup-qemu-action@v4 and docker/setup-buildx-action@v4, logs in with the handout's step,
then builds one image per step. The backend step is the same as this one with
context: ./backend, tag :backend and scope=backend:
- name: Build and push the frontend
uses: docker/build-push-action@v7
with:
context: .
file: Dockerfile.multistage
platforms: linux/amd64,linux/arm64
push: true
tags: ${{ env.IMAGE }}:frontend
cache-from: type=gha,scope=frontend
cache-to: type=gha,mode=max,scope=frontend- The runners are
linux/amd64, while lab 05 was measured on an Apple silicon Mac (linux/arm64). Building both platforms puts one image per CPU under each tag, and your machine pulls the one that runs natively. QEMU emulates arm64 on the runner, Buildx drives the build. - The contexts and Dockerfiles are the ones
docker-compose.ymluses, so CI pushes what it tested. - The
ghacache keeps BuildKit layers between runs, so a push that only changessrc/main.jsreuses thenpm cilayers.mode=maxalso caches the builder stage, andscopekeeps the two images' caches apart.
The multi-platform build is why Dockerfile.multistage changes. Only the first FROM is edited:
File: Dockerfile.multistage
# $BUILDPLATFORM = the machine doing the build. The output is plain HTML/CSS/JS, the same
# for every CPU, so this stage runs natively once, even when building an arm64 image on
# an amd64 CI runner.
FROM --platform=$BUILDPLATFORM node:26-alpine AS builderIn lab 05 it was FROM node:26-alpine AS builder. Without --platform=$BUILDPLATFORM, Buildx would
run npm ci and vite build a second time under slow QEMU emulation, only to produce the same
files. Stage 2 (nginx:stable-alpine) has no --platform, so each platform still gets its own
nginx. The backend needs no such change: its npm ci --omit=dev installs only express and pg,
plain JavaScript, so emulating it is cheap.
Also delete the single-stage Dockerfile (lab 04's Vite dev-server image). Nothing uses it any
more: Compose and CI both build the frontend from Dockerfile.multistage.
The handout's five requirements:
| Requirement | Met by |
|---|---|
1. Named exactly CI/CD |
name: CI/CD |
2. Pushes to main only |
on: push: branches: [main] |
| 3. Tests the full stack, nothing pushed if a test fails | docker compose up then npx playwright test; needs: test |
4. Pushes :frontend and :backend |
the two docker/build-push-action steps |
| 5. Green only if everything succeeded | any failed step fails its job, and a failed or skipped job fails the run |
Checkpoint. Push to main. In the solution's own repository this was the first commit,
feat: add CI/CD pipeline for node-auth-app, which added the lab 05 project and the pipeline
together. The Actions tab shows a CI/CD run with two jobs, "Playwright tests (full stack)" then
"Build and push images", both green, and the test step lists the three tests of
tests/auth.spec.js as passed. On Docker Hub, auth-app shows the tags frontend and backend
with a recent "last pushed" time, each for linux/amd64 and linux/arm64.
4. Run the app from Docker Hub
Create the deploy folder outside the project (auth-app-deploy/ in the handout, deploy/ in
solution/). deploy/docker-compose.deploy.yml starts with name: auth-app-deploy. Its db
service is lab 05's, plus restart: unless-stopped. The two app services lose their build::
File: deploy/docker-compose.deploy.yml
backend:
image: ${DOCKERHUB_USERNAME:?set DOCKERHUB_USERNAME in .env}/auth-app:backend
environment:
DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/auth
PORT: 3000
depends_on:
db:
condition: service_healthy
restart: unless-stopped
frontend:
image: ${DOCKERHUB_USERNAME}/auth-app:frontend
ports:
- "5173:80"
depends_on:
- backend
restart: unless-stoppedimage:instead ofbuild:: this file only runs what CI pushed.restart: unless-stoppedbrings the stack back after Docker Desktop restarts.- The service names must stay
db,backendandfrontend: the frontend image containsnginx.conf, which forwards/api/tohttp://backend:3000, and the backend connects todb:5432. - The named volume
db-datakeeps users across everypullandup -d. Because the project name differs, it isauth-app-deploy_db-data, not lab 05'snode-auth-app_db-data: the deployed app starts with an empty database, so register a new user the first time. - Your Docker ID and the database password come from a
.envnext to the file, so the compose file holds no account name or password.deploy/.gitignoreexcludes.envand.webhook-secret.
File: deploy/.env.example
# Copy to .env and fill in. .env is not committed.
DOCKERHUB_USERNAME=your-docker-id
POSTGRES_PASSWORD=change-meCheckpoint. Stop the lab 05 stack first (docker compose down in the project folder): both
stacks publish port 5173. Then, from the deploy folder:
cp .env.example .env # then fill in your Docker ID and a password
docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -dpull downloads your two private images (this is where the login from 2.3 matters) and
postgres:18-alpine. Open http://localhost:5173, register and log in: the app works as in lab
05, but nothing was built on your machine.
5. The deploy server (provided)
Save the handout's deploy_server.py in the deploy folder; the solution's copy is unchanged. It
accepts only requests whose X-Hub-Signature-256 matches an HMAC-SHA256 of the body made with the
shared secret (anyone can find your ngrok URL, only GitHub knows the secret), and compares with
hmac.compare_digest, which takes the same time whatever the input. Then it decides:
File: deploy/deploy_server.py
def reason_to_ignore(payload):
"""Return why this workflow_run event should NOT trigger a deploy, or None."""
run_info = payload.get("workflow_run", {})
if payload.get("action") != "completed":
return f"action is '{payload.get('action')}', waiting for 'completed'"
if run_info.get("name") != WORKFLOW_NAME:
return f"workflow '{run_info.get('name')}' is not '{WORKFLOW_NAME}'"
if run_info.get("head_branch") != BRANCH:
return f"branch '{run_info.get('head_branch')}' is not '{BRANCH}'"
if run_info.get("conclusion") != "success":
return f"workflow conclusion is '{run_info.get('conclusion')}'"
return NoneOnly a completed, successful CI/CD run on main deploys. The deploy (pull then up -d) runs
in a background thread because GitHub expects an answer within 10 seconds, and a lock allows one
deploy at a time. The server listens on 127.0.0.1 only: ngrok runs on the same machine, so
nothing else on your network can reach port 9000.
Generate the shared secret. The solution keeps it in a git-ignored file next to the server:
python3 -c "import secrets; print(secrets.token_hex(32))" > .webhook-secretInstead of the handout's two export lines, the solution adds a start script:
File: deploy/start-deploy-server.sh
cd "$(dirname "$0")"
export WEBHOOK_SECRET="$(cat .webhook-secret)"
export COMPOSE_FILE="$PWD/docker-compose.deploy.yml"
exec python3 deploy_server.pyIt moves into its own folder (so .env and .webhook-secret are found wherever you start it),
sets the handout's two variables, and replaces itself with Python so Ctrl+C stops the server. It is
for macOS and Linux; on Windows, use the handout's PowerShell commands.
Run ./start-deploy-server.sh and leave it running. It prints, in this format:
[hh:mm:ss] Deploy server listening on http://localhost:9000 (GitHub calls POST /deploy)
[hh:mm:ss] Deploys successful 'CI/CD' runs on 'main' using /path/to/deploy/docker-compose.deploy.ymlhttp://localhost:9000 in a browser shows Deploy server is running.
6. ngrok: a public address for your machine
GitHub cannot reach localhost, so ngrok gives your machine a public HTTPS URL that forwards to
port 9000. Sign up at https://dashboard.ngrok.com/signup, install it (brew install ngrok on
macOS), then:
ngrok config add-authtoken <your-authtoken> # once per machine
ngrok http 9000ngrok prints a line like Forwarding https://your-name.ngrok-free.dev -> http://localhost:9000.
The free dev domain is fixed, so you configure the webhook only once. http://127.0.0.1:4040 shows
every request through the tunnel with the server's answer: the fastest way to debug the webhook.
7. The GitHub webhook
Settings → Webhooks → Add webhook: Payload URL https://<ngrok-domain>/deploy, content type
application/json, Secret the contents of .webhook-secret, events "Workflow runs" only (untick
Pushes), Active ticked.
GitHub sends a ping right away: the server logs Ping from GitHub: the webhook is connected and
Recent Deliveries shows a green tick.
Why Workflow runs and not Pushes: a push event fires before the images exist. A workflow_run
event fires when the run changes state, and the server deploys only on completed with
success. GitHub also sends deliveries when a run is requested and in progress; the server
answers 202 and logs lines like Ignored: action is 'requested', waiting for 'completed'. That
is expected.
When a delivery misbehaves, the server's answer says why:
| Answer | Cause |
|---|---|
401 Invalid signature |
the webhook secret and .webhook-secret differ |
400 Body is not JSON ... |
content type is not application/json |
404 Not found |
the Payload URL is missing /deploy |
202 Ignored event 'push' |
Pushes is still ticked |
202 Deploy started, then Deploy FAILED in the terminal |
Docker is not running, or the login (2.3) or deploy/.env is missing |
8. Run the whole pipeline
Three things must be running: Docker Desktop, the deploy server (step 5) and ngrok http 9000
(step 6). The solution's repository history follows the handout's script, one commit per stage:
| Commit | Message | What it shows |
|---|---|---|
0983696 |
feat: add CI/CD pipeline for node-auth-app |
the 3.4 checkpoint |
c61e61c |
feat: say the app was deployed by CI/CD |
a visible change, deployed end to end |
67e6098 |
test: break a test on purpose |
a red run: nothing pushed, nothing deployed |
d793784 |
Revert "test: break a test on purpose" |
back to green |
A visible change
The handout suggests the Welcome heading. The solution changes the line under it instead:
File: src/main.js
- <p>You are logged in.</p>
+ <p>You are logged in. Deployed automatically by CI/CD.</p>
The tests find the heading Welcome, <name>! by role and name and never read this paragraph, so
the run stays green. If you change the heading and it no longer contains Welcome, <name>!, the
happy-path test fails: update tests/auth.spec.js in the same commit.
Commit, push to main, and watch:
- Actions: the CI/CD run starts, both jobs turn green.
- Docker Hub: both tags show a new "last pushed" time.
- Webhook → Recent Deliveries:
workflow_rundeliveries answered202, thecompletedone withDeploy started. - The deploy server terminal, in this format, with Docker's pull and up output in between:
[hh:mm:ss] Deploying commit <sha>...
[hh:mm:ss] Running: docker compose -f /path/to/deploy/docker-compose.deploy.yml pull
[hh:mm:ss] Running: docker compose -f /path/to/deploy/docker-compose.deploy.yml up -d
[hh:mm:ss] Deploy finished: commit <sha> is live on http://localhost:5173http://localhost:5173: log in. The welcome page now says "You are logged in. Deployed automatically by CI/CD." Earlier users are still there:up -drecreated the app containers but kept thedb-datavolume.
Break a test on purpose
The solution changes the expected error message of the sad-path test, so it no longer matches what the app shows:
File: tests/auth.spec.js
- await expect(page.getByRole("alert")).toHaveText("Invalid username or password");
+ await expect(page.getByRole("alert")).toHaveText("Wrong password");
Push it. What you should see:
login with invalid credentials shows an errorfails; the other two tests pass. "Show container logs" runs (if: failure()) and the report is still uploaded (if: always()).- "Build and push images" is skipped (
needs: test) and the run is red. - Docker Hub: the "last pushed" times do not move.
- The deploy server logs
Ignored: workflow conclusion is 'failure', andhttp://localhost:5173keeps running the last good version.
Let the red run finish before pushing the fix: with cancel-in-progress: true, a new push to
main cancels a running run, and you would see cancelled instead of failure. Then
git revert the broken commit and push: an ordinary green push, so the whole chain runs again.
9. Deliverable
A Loom video (https://www.loom.com) of the whole process, from the push to the containers running
locally: the push, the green Actions run, the new "last pushed" time on Docker Hub, the webhook
delivery, the server's Deploy finished line, and the change live on http://localhost:5173. The
red run and its Ignored: workflow conclusion is 'failure' line are worth showing too.
Files in solution/
| File | New or changed | What it does |
|---|---|---|
.github/workflows/cicd.yml |
New | The CI/CD workflow: tests the full stack, then builds and pushes both images for amd64 and arm64 |
Dockerfile.multistage |
Changed | Builder stage runs on $BUILDPLATFORM, so the static files are built once, natively |
src/main.js |
Changed | Welcome page says "Deployed automatically by CI/CD." (the step 8 change) |
README.md |
New | What the pipeline does, the repository settings, and how to run the stack and tests locally before pushing |
deploy/docker-compose.deploy.yml |
New | Runs db, backend and frontend from the Docker Hub images, nothing built |
deploy/deploy_server.py |
New (provided) | The handout's webhook receiver, unchanged |
deploy/start-deploy-server.sh |
New | Reads .webhook-secret, sets COMPOSE_FILE, starts the server |
deploy/.env.example |
New | Template for deploy/.env (Docker ID, database password) |
deploy/.gitignore |
New | Keeps .env and .webhook-secret out of Git |
Delete from the starting point: Dockerfile, the single-stage Vite image from lab 04.
Create yourself and never commit: deploy/.env (from deploy/.env.example),
deploy/.webhook-secret (step 5), and, for local runs only, the app's .env from lab 05.
To get the finished project:
unzip 04_docker_containers/starter.zip # gives node-auth-app/
cp -R 05_docker_compose/solution/. node-auth-app/
rm node-auth-app/src/auth.js # end of lab 05
cp -R 06_cicd/solution/. node-auth-app/
rm node-auth-app/Dockerfile
mv node-auth-app/deploy auth-app-deploy # your machine's side, outside the repoPush node-auth-app to a new GitHub repository on main, then do steps 2 to 7 by hand: accounts,
tokens, secret, tunnel and webhook are settings no file can carry.