Series: Docker → Kubernetes → DevSecOps
Level: Complete Beginner — every click and every command is shown
Repo: reza-plan-docker
Stack: React 19 + Vite · Express 5 · Node 20 Alpine · GitHub Codespaces · GitHub Actions

Table of Contents

1. The Big Picture — What We’re Building
2. What is Docker?
3. Install Docker on Your Machine
4. Clone the Project
5. Understand the Project Files
6. Step 1 — Create the .dockerignore File
7. Step 2 — Create the Dockerfile
8. Step 3 — Build the Docker Image
9. Step 4 — Run the Container Manually
10. Step 5 — Test the Running App
11. Step 6 — Debug When Things Go Wrong
12. Step 7 — Create the docker-compose.yml File
13. Step 8 — Push Your Image to a Registry
14. Understanding Multi-Stage Builds
15. Step 9 — Run in the Cloud with GitHub Codespaces
16. Step 10 — Automate with GitHub Actions
17. Docker Best Practices Checklist
18. Lessons Learned
19. What’s Next

1. The Big Picture — What We’re Building

Most Docker tutorials stop at “the container runs on my laptop.” This post goes further. By the end you will have done all of this:

1. The reza-plan app (React + Express tracking app) packaged into a Docker container
2. That same container running in the cloud for free on GitHub Codespaces
3. A GitHub Actions workflow that automatically starts and stops the Codespace every day

Here is the full picture of what we are building:

┌──────────────────────────────────────────────────────────────────────────┐
│                          FULL SYSTEM MAP                                 │
│                                                                          │
│  GitHub Actions (runs on a schedule — like a cron job)                   │
│       │                                                                  │
│       │  starts at 08:17 UTC every weekday morning                       │
│       │  stops  at 13:17 UTC every weekday afternoon                     │
│       ▼                                                                  │
│  GitHub Codespace (free Linux cloud machine from GitHub)                 │
│  ┌───────────────────────────────────────────────────┐                   │
│  │  Docker Container                                 │                   │
│  │  ┌─────────────────────────────────────────────┐ │                   │
│  │  │  node:20-alpine (tiny Linux + Node.js)      │ │                   │
│  │  │  Express server listening on port 3000      │ │                   │
│  │  │  React app served as pre-built HTML/JS/CSS  │ │                   │
│  │  │  /app/data ←──── volume (your data on host) │ │                   │
│  │  └─────────────────────────────────────────────┘ │                   │
│  └───────────────────────────────────────────────────┘                   │
│       │                                                                  │
│       │  port 3000 forwarded → public HTTPS URL                          │
│       ▼                                                                  │
│  https://your-codespace-name-3000.app.github.dev                         │
│                                                                          │
│  Telegram bot notifies you when the codespace starts or stops            │
└──────────────────────────────────────────────────────────────────────────┘

This is real DevOps — not just a toy example. Everything here is what you would do professionally. Let’s build it step by step.

2. What is Docker?

Before touching any file, understand the two core ideas.

Image = the blueprint

A Docker image is a read-only package that contains everything your app needs to run: the operating system layer, your code, all libraries and dependencies, and the command to start it. Think of it like a ZIP file that you can hand to any computer in the world and it will run identically.

Container = the running instance

A Docker container is what you get when you actually run an image. One image can produce many containers — all identical, all isolated from each other and from your host machine.

┌───────────────────────────────────────────────────────────────────┐
│  Think of it like a recipe and a meal                             │
│                                                                   │
│  Image   = the recipe (read-only, reusable, shareable)            │
│  Container = the meal (running, can be stopped, can be deleted)   │
│                                                                   │
│  You can cook the same recipe on any stove in the world           │
│  and the meal will taste the same                                 │
│                                                                   │
│  Docker:                                                          │
│  You can run the same image on your laptop, on GitHub,            │
│  on AWS — and it behaves identically every time                   │
└───────────────────────────────────────────────────────────────────┘

Why does this matter for DevOps?

Without Docker: “It works on my machine” — and breaks everywhere else because dependencies, OS versions, and configs differ.

With Docker: the image is the environment. Same image everywhere = same behavior everywhere. This is the foundation of modern CI/CD, Kubernetes, and cloud deployments.

3. Install Docker on Your Machine

Ubuntu or Debian Linux

Open a terminal and run these commands one block at a time. Wait for each to finish before running the next.

Block 1 — Remove old Docker versions if any exist:

sudo apt-get remove docker docker-engine docker.io containerd runc

It is fine if this says “unable to locate package” — that just means nothing old was installed.

Block 2 — Install the tools Docker needs:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

Block 3 — Add Docker’s official security key:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Block 4 — Add the Docker software repository:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Block 5 — Install Docker:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Block 6 — Verify it installed correctly:

docker --version
docker compose version

You should see output like:

Docker version 26.1.0, build abc123
Docker Compose version v2.27.0

Block 7 — Run Docker without sudo every time (optional but recommended):

sudo usermod -aG docker $USER
newgrp docker

🔐 Security Note: Adding yourself to the docker group gives you the ability to run containers without typing sudo. Be aware this is effectively root-level power on the host machine. On a shared server, never do this for untrusted users.

Test that everything works:

docker run hello-world

You should see a message saying “Hello from Docker!” — your installation is working.

macOS or Windows

1. Go to https://www.docker.com/products/docker-desktop
2. Click Download Docker Desktop for your operating system
3. Open the downloaded file and follow the installer
4. Once installed, open Docker Desktop — wait for the whale icon in your taskbar to show “Docker is running”
5. Open a terminal (Terminal on Mac, PowerShell on Windows) and verify:

   docker --version
   docker compose version
   

4. Clone the Project

Open a terminal on your machine and run:

# Clone the repo
git clone https://github.com/mradelvand/reza-plan-docker.git

# Move into the project folder
cd reza-plan-docker

# Confirm you are in the right place
ls

You should see these files listed:

Dockerfile  docker-compose.yml  package.json  server.js  src/  public/  ...

All commands from this point forward are run inside the reza-plan-docker folder unless stated otherwise.

5. Understand the Project Files

Before creating any Docker files, understand what you are working with.

reza-plan-docker/
│
├── src/                  ← React source code (what gets compiled)
│   ├── App.jsx           ← sidebar, navigation, all panels
│   ├── AgentPanel.jsx    ← daily log form, AI feedback, stats
│   ├── data.js           ← course sections, weekly schedules
│   ├── storage.js        ← functions that call the Express API
│   ├── index.css         ← all styles
│   └── main.jsx          ← React entry point
│
├── public/               ← static files (favicon, icons)
├── data/                 ← WHERE YOUR PROGRESS DATA LIVES
│                           (progress.json is created here at runtime)
│
├── server.js             ← Express backend server
│                           serves the API AND the compiled React app
│
├── package.json          ← project dependencies and scripts
├── vite.config.js        ← Vite dev server settings
│
│   ── YOU WILL CREATE THESE ──
├── .dockerignore         ← tells Docker what files to ignore
├── Dockerfile            ← recipe to build the image
└── docker-compose.yml    ← easier way to run the container

The most important thing to understand before we continue:

In development (without Docker), you run npm start. This starts two servers at the same time:

• Vite dev server on port 5173 — serves the React frontend with hot-reload
• Express server on port 3001 — serves the API

In production (inside Docker), there is no Vite, no hot-reload. Instead:

• Express runs on port 3000 and does both jobs — serves the API and serves the pre-compiled React app as static files from the dist/ folder

This is why we need a build step in the Dockerfile — to compile the React source code into static files that Express can serve.

6. Step 1 — Create the .dockerignore File

What is .dockerignore?

When you tell Docker to build an image, it first collects all the files in your project folder and sends them to the Docker engine. This is called the build context. The .dockerignore file tells Docker which files to leave out of that collection.

Without .dockerignore, Docker would try to send your entire project — including node_modules (which can be 200MB+) and data/progress.json (which contains your personal data). This is slow and potentially dangerous.

Where to create it

The .dockerignore file must be in the root of your project folder — the same folder that contains your Dockerfile and package.json.

reza-plan-docker/          ← you are here
├── .dockerignore          ← create it RIGHT HERE, at this level
├── package.json
├── server.js
└── src/

How to create it

Option A — using the terminal:

# Make sure you are in the project root
pwd
# Should show: /path/to/reza-plan-docker

# Create the file
cat > .dockerignore << 'EOF'
node_modules
dist
data
.git
*.md
SETUP.md
HOW_TO_MODIFY.md
EOF

Option B — using VS Code:

1. Open VS Code in the project folder: code .
2. In the file explorer on the left, click the New File icon (the page with a plus sign)
3. Type exactly: .dockerignore (with the dot at the start) and press Enter
4. Paste this content into the file:

node_modules
dist
data
.git
*.md
SETUP.md
HOW_TO_MODIFY.md

1. Save with Ctrl+S (Windows/Linux) or Cmd+S (Mac)

Verify it was created

ls -la | grep dockerignore
# Should show: .dockerignore

Why each line is there

🔐 Security Note: The data directory being excluded is critical. If you ever create a .env file in this project (for API keys, passwords, etc.), add .env to .dockerignore immediately. A leaked secret baked into a Docker image pushed to a public registry is a serious incident. Always ask yourself before building: “is there anything in my project folder I would not want public?”

7. Step 2 — Create the Dockerfile

What is a Dockerfile?

A Dockerfile is a text file that contains step-by-step instructions for building your Docker image. Docker reads it top to bottom, like a recipe, and each instruction creates a new layer in the image.

Where to create it

The Dockerfile also goes in the root of your project folder, next to package.json:

reza-plan-docker/          ← you are here
├── .dockerignore          ← just created this
├── Dockerfile             ← create it RIGHT HERE
├── package.json
├── server.js
└── src/

How to create it

Option A — using the terminal:

# Make sure you are in the project root
pwd
# Should show: /path/to/reza-plan-docker

# Create the Dockerfile (note: no file extension)
touch Dockerfile

Then open it with your text editor and paste the content below.

Option B — using VS Code:

1. In the file explorer, click the New File icon
2. Type exactly: Dockerfile (capital D, no extension) and press Enter
3. Paste the full content below
4. Save with Ctrl+S or Cmd+S

The complete Dockerfile

# =============================================================================
# Stage 1 — BUILD
# This stage installs everything and compiles the React app.
# It will be thrown away after building — nothing from here
# except the compiled output reaches the final image.
# =============================================================================
FROM node:20-alpine AS builder

# Set the working directory inside this stage's container.
# All commands from here run inside /app.
WORKDIR /app

# --- Layer caching trick ---
# Copy ONLY the package files first, before the source code.
# Docker caches each layer. If package.json hasn't changed,
# Docker skips the npm install step on the next build.
# This saves minutes on every build after the first.
COPY package*.json ./

# Install ALL dependencies (dev + production).
# We need dev tools like Vite to compile the React app.
RUN npm install

# Now copy the rest of the source code.
# This is copied AFTER npm install so editing a React file
# does not invalidate the npm install cache.
COPY . .

# Compile the React app with Vite.
# Output goes to /app/dist as static HTML, CSS, and JS files.
RUN npm run build


# =============================================================================
# Stage 2 — PRODUCTION
# This is the image that actually ships and runs.
# It starts completely fresh — none of Stage 1's files are here
# except what we explicitly copy over.
# =============================================================================
FROM node:20-alpine

WORKDIR /app

# Install ONLY production dependencies.
# No Vite, no ESLint, no dev tools — keeps the image small and safe.
COPY package*.json ./
RUN npm install --omit=dev

# Copy the compiled React app from Stage 1.
# The build tools that produced it are left behind and discarded.
COPY --from=builder /app/dist ./dist

# Copy the Express server — this is what actually runs.
COPY server.js ./

# Create the data directory.
# The real data (progress.json) is stored on the HOST machine
# and mounted into this directory at runtime via a Docker volume.
# This mkdir just ensures the mount point exists in the image.
RUN mkdir -p /app/data

# Document which port the app listens on.
# This does NOT publish the port — that happens at runtime.
EXPOSE 3000

# The command that runs when the container starts.
# Using array format (exec form) is important — it means Node.js
# receives shutdown signals directly so it can save data gracefully.
CMD ["node", "server.js"]

Verify it was created

ls -la | grep Dockerfile
# Should show: Dockerfile

How Docker reads this file — the flow

┌──────────────────────────────────────────────────────────────────────┐
│  STAGE 1 (builder) — runs and then is completely thrown away         │
│                                                                      │
│  FROM node:20-alpine AS builder                                      │
│    Start with a minimal Linux + Node.js 20 image                    │
│                    ↓                                                 │
│  WORKDIR /app                                                        │
│    All commands now run inside /app                                  │
│                    ↓                                                 │
│  COPY package*.json ./                                               │
│    Copy package.json + package-lock.json into /app                  │
│                    ↓                                                 │
│  RUN npm install                                                     │
│    Install all packages (including Vite, ESLint, etc.)               │
│                    ↓                                                 │
│  COPY . .                                                            │
│    Copy all source code (src/, public/, vite.config.js, etc.)       │
│                    ↓                                                 │
│  RUN npm run build                                                   │
│    Vite compiles React → /app/dist/index.html + assets/             │
│                                                                      │
│  ── ENTIRE STAGE 1 IS DISCARDED ──────────────────────────────────  │
│                                                                      │
│  STAGE 2 (production) — this is the actual image that ships          │
│                                                                      │
│  FROM node:20-alpine    ← brand new, empty image                    │
│                    ↓                                                 │
│  npm install --omit=dev ← only express, cors, react, react-dom      │
│                    ↓                                                 │
│  COPY --from=builder /app/dist ./dist  ← grab compiled React        │
│                    ↓                                                 │
│  COPY server.js ./  ← add the Express server                        │
│                    ↓                                                 │
│  RUN mkdir -p /app/data  ← create the volume mount point            │
│                    ↓                                                 │
│  CMD ["node", "server.js"]  ← this runs when container starts       │
└──────────────────────────────────────────────────────────────────────┘

8. Step 3 — Build the Docker Image

Now you have both files created. Let’s build the image.

Run the build command

Make sure you are in the project root (where the Dockerfile is), then run:

docker build -t reza-plan:1.0 .

Let’s break down this command:

docker build          ← the build command
-t reza-plan:1.0      ← tag (name) the image: name=reza-plan, version=1.0
.                     ← the dot means "use the current folder as context"
                        Docker will look for Dockerfile here
                        and collect files (minus .dockerignore) from here

What you will see while it builds

[+] Building 65.3s
 => [builder 1/6] FROM node:20-alpine              ← downloading base image
 => [builder 2/6] WORKDIR /app                     ← setting work directory
 => [builder 3/6] COPY package*.json ./            ← copying package files
 => [builder 4/6] RUN npm install                  ← installing packages (~40s)
 => [builder 5/6] COPY . .                         ← copying source code
 => [builder 6/6] RUN npm run build                ← compiling React
 => [stage-1 2/6] COPY package*.json ./
 => [stage-1 3/6] RUN npm install --omit=dev       ← prod-only packages
 => [stage-1 4/6] COPY --from=builder /app/dist    ← grabbing compiled React
 => [stage-1 5/6] COPY server.js ./
 => [stage-1 6/6] RUN mkdir -p /app/data
 => exporting to image
 => naming to reza-plan:1.0

The first build takes a few minutes because it downloads the base image and installs all packages. Subsequent builds are much faster because Docker caches the layers.

Verify the image was created

docker images

You should see something like:

REPOSITORY   TAG    IMAGE ID       CREATED          SIZE
reza-plan    1.0    a3f9bc12d4e1   2 minutes ago    185MB

The image is about 185MB. If you had not used a multi-stage build, it would be over 600MB.

Understanding tags

# You can build the same image with multiple tags
docker build -t reza-plan:1.0 .           # version number
docker build -t reza-plan:latest .        # latest (for local use)
docker build -t reza-plan:dev .           # for development testing

# When you are ready to push to Docker Hub or GHCR:
docker build -t yourusername/reza-plan:1.0 .

🔐 Security Note: Before shipping any image, scan it for known security vulnerabilities. Install Trivy and run:

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

# Scan your image
trivy image reza-plan:1.0

The node:20-alpine base image is chosen specifically because Alpine Linux has fewer installed packages, which means fewer potential vulnerabilities compared to a full Ubuntu or Debian base.

9. Step 4 — Run the Container Manually

Create the data directory first

The app needs a data/ folder to store progress.json. Create it on your host machine:

mkdir -p data

This folder on your machine will be connected to the container via a volume mount. Your data lives here — not inside the container.

Run the container

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  --name reza-plan \
  reza-plan:1.0

Breaking down every part of this command:

docker run            ← start a container from an image
-d                    ← detached mode: runs in the background
                        (without this, the terminal would be locked)

-p 3000:3000          ← port mapping
                        left side  (3000) = port on YOUR machine
                        right side (3000) = port inside the container
                        format is always: host_port:container_port

-v $(pwd)/data:/app/data  ← volume mount (connects a folder)
                            $(pwd) = your current directory (auto-filled)
                            left side  = folder on YOUR machine: ./data
                            right side = folder inside container: /app/data
                            they are linked — changes on either side
                            are instantly visible on the other side

--name reza-plan      ← give the container a memorable name
                        without this, Docker invents a random name

reza-plan:1.0         ← which image to run (name:tag from the build step)

What the volume mount means

Your machine (host)                 Container
────────────────────                ─────────────────────
./data/progress.json   ←──────────► /app/data/progress.json
                          linked     (same file, two views)

When the app writes progress data → it appears on your machine
When you delete the container    → your data is still safe
When you rebuild the image       → your data is still safe

10. Step 5 — Test the Running App

Check the container is running

docker ps

You should see:

CONTAINER ID   IMAGE          COMMAND            STATUS        PORTS
a3f9bc12d4e1   reza-plan:1.0  "node server.js"   Up 30 sec     0.0.0.0:3000->3000/tcp

If docker ps shows nothing at all — the container started and immediately crashed. This is exactly what happened when we first ran this project. Here is what we saw and how we fixed it.

🐛 Real Bug We Hit — Container Exits Immediately

When we ran docker ps, the output was empty:

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

We ran docker ps -a (which shows stopped containers too):

CONTAINER ID   IMAGE           COMMAND                  CREATED         STATUS                     PORTS   NAMES
41a415636af4   reza-plan:1.0   "docker-entrypoint.s…"   1 minute ago    Exited (1) 1 minute ago             reza-plan

Exited (1) means the process crashed with an error. The next step is always the same: read the logs.

docker logs reza-plan

The output was:

/app/node_modules/path-to-regexp/dist/index.js:108
                    throw new PathError(`Missing parameter name at index ${index}`, str);
                          ^
PathError [TypeError]: Missing parameter name at index 1: *; visit https://git.new/pathToRegexpError for info
    at consumeUntil (/app/node_modules/path-to-regexp/dist/index.js:108:27)
    ...
    at app.<computed> [as get] (/app/node_modules/express/lib/application.js:478:22) {
  originalPath: '*'
}
Node.js v20.20.2

Diagnosing the error

The key phrase is: PathError: Missing parameter name at index 1: * and originalPath: '*'

This is an Express 5 breaking change. In Express 4, you could write:

app.get('*', handler)   // works in Express 4

In Express 5, the wildcard * must be named. The old syntax throws a PathError at startup, which crashes the process immediately — before the server even starts listening.

This project uses Express 5 ("express": "^5.2.1" in package.json). The server.js file has this line near the bottom:

// ❌ This crashes Express 5
app.get('*', (req, res) => {
  ...
});

The fix — update server.js

Open server.js in your editor. Find the catch-all route near the bottom — it looks like this:

// ── Catch-all: serve React app for any non-API route ─────────────────────────
app.get('*', (req, res) => {
  const index = path.join(DIST, 'index.html');
  if (fs.existsSync(index)) {
    res.sendFile(index);
  } else {
    res.status(404).send('App not built. Run: npm run build');
  }
});

Change '*' to '/{*path}':

// ── Catch-all: serve React app for any non-API route ─────────────────────────
// Express 5 requires named wildcards — '*' is no longer valid syntax
app.get('/{*path}', (req, res) => {
  const index = path.join(DIST, 'index.html');
  if (fs.existsSync(index)) {
    res.sendFile(index);
  } else {
    res.status(404).send('App not built. Run: npm run build');
  }
});

Save the file.

Why this fix works

/{*path} is Express 5’s named wildcard syntax. It means: “match any path, and call that captured segment path.” It does exactly the same job as * did in Express 4 — catch every request that didn’t match an earlier route and serve index.html so React can handle client-side navigation.

Express 4:   app.get('*', handler)         ← unnamed wildcard, now invalid
Express 5:   app.get('/{*path}', handler)  ← named wildcard, correct syntax

Rebuild and rerun after the fix

Any time you change source code, you must rebuild the image. The container is running your old image, not your edited file.

# Remove the crashed container
docker rm reza-plan

# Rebuild the image with the fix
docker build -t reza-plan:1.0 .

# Run again
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  --name reza-plan \
  reza-plan:1.0

# Verify it is running now
docker ps

You should now see:

CONTAINER ID   IMAGE          COMMAND            STATUS        PORTS
a3f9bc12d4e1   reza-plan:1.0  "node server.js"   Up 10 sec     0.0.0.0:3000->3000/tcp

What this debugging experience teaches you

┌─────────────────────────────────────────────────────────────────────┐
│  The Docker debugging loop — memorize this:                         │
│                                                                     │
│  1. docker ps          → is it running?                             │
│  2. docker ps -a       → did it crash? (look for Exited status)     │
│  3. docker logs <name> → what went wrong? (always read the logs)    │
│  4. fix the code       → edit the source file                       │
│  5. docker rm <name>   → remove the dead container                  │
│  6. docker build       → rebuild the image with the fix             │
│  7. docker run         → try again                                  │
│                                                                     │
│  The logs almost always contain the answer.                         │
│  Read them before searching the internet.                           │
└─────────────────────────────────────────────────────────────────────┘

Check the logs after the fix

docker logs reza-plan

You should now see the startup message from server.js:

✓ Reza's Plan running at http://localhost:3000
  Data file : /app/data/progress.json
  Export    : http://localhost:3000/api/export

Open the app in your browser

Go to: http://localhost:3000

The full Reza Plan app should load — the sidebar, the progress coach panel, all of it.

Test the API endpoints directly

The app has three API endpoints defined in server.js. Test them with curl:

# Get all progress entries (empty array on first run)
curl http://localhost:3000/api/entries

# Add a test entry
curl -X POST http://localhost:3000/api/entries \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-05-17",
    "duration": 60,
    "tasks": ["Docker — videos or hands-on lab"],
    "mood": "Good",
    "notes": "Learned Docker multi-stage builds today — and fixed an Express 5 bug"
  }'

# You should see: {"ok":true,"total":1}

# Get the weekly export summary (plain text, for pasting to Claude)
curl http://localhost:3000/api/export

Verify data persistence

After adding an entry, check that the file appeared on your host machine:

cat data/progress.json

You should see your entry stored as JSON. Now test that the data survives container destruction:

# Stop and remove the container
docker stop reza-plan
docker rm reza-plan

# Start a fresh container
docker run -d -p 3000:3000 -v $(pwd)/data:/app/data --name reza-plan reza-plan:1.0

# Check the data is still there
curl http://localhost:3000/api/entries

Your entry is still there. The container was destroyed and recreated, but the data lived on your machine the whole time.

11. Step 6 — Debug When Things Go Wrong

These are the debugging steps to run when something is not working.

The container is not in docker ps

# Look for stopped containers too
docker ps -a

# If you see your container with STATUS "Exited":
docker logs reza-plan

The logs almost always tell you exactly what went wrong.

Common errors and fixes

Error: “port is already in use”

# Something else is using port 3000
# Either stop the other process, or use a different host port:
docker run -d -p 8080:3000 -v $(pwd)/data:/app/data --name reza-plan reza-plan:1.0
# Then open http://localhost:8080

Error: “no such file or directory” for dist/

# The React build step failed in Stage 1
# Rebuild with no cache to see the full error output
docker build --no-cache -t reza-plan:1.0 .

App loads but shows “App not built”

# The dist/ folder is empty or missing in the image
# Inspect what is actually inside the container:
docker exec -it reza-plan sh
ls /app/dist    # should show: index.html  assets/
exit

Open a shell inside the running container

This is the most powerful debugging tool. You can explore the container’s filesystem as if you were SSH’d into a server:

docker exec -it reza-plan sh

# Now you are inside the container:
ls /app                        # see what files are there
ls /app/dist                   # check the compiled React output
cat /app/data/progress.json    # see your data
node --version                 # confirm Node.js version
exit                           # leave the container shell

Debug a container that crashes on startup

If the container exits immediately before you can exec into it:

# Override the startup command — run a shell instead of node server.js
docker run -it --entrypoint sh reza-plan:1.0

# Now manually try to start the server:
node server.js
# Read the error message
exit

Rebuild after making changes

# Rebuild the image (faster than first time — uses cache for unchanged layers)
docker build -t reza-plan:1.1 .

# Remove the old container
docker stop reza-plan
docker rm reza-plan

# Run the new version (your data is safe in ./data)
docker run -d -p 3000:3000 -v $(pwd)/data:/app/data --name reza-plan reza-plan:1.1

Clean up unused Docker objects

docker container prune    # remove all stopped containers
docker image prune        # remove dangling (unnamed) images
docker system prune -a    # remove everything not currently in use
docker system df          # see how much disk Docker is using

12. Step 7 — Create the docker-compose.yml File

Running docker run -d -p 3000:3000 -v $(pwd)/data:/app/data --name reza-plan reza-plan:1.0 every time is tedious and easy to get wrong. Docker Compose lets you save all of that into one file that you commit to Git — anyone who clones the repo just runs docker compose up and everything works.

Where to create it

Same location as everything else — the project root:

reza-plan-docker/          ← you are here
├── .dockerignore          ← created in Step 1
├── Dockerfile             ← created in Step 2
├── docker-compose.yml     ← create it RIGHT HERE
├── package.json
└── server.js

How to create it

Option A — terminal:

touch docker-compose.yml

Then open and paste the content below.

Option B — VS Code:

1. Click the New File icon in the explorer
2. Type: docker-compose.yml and press Enter
3. Paste the content below and save

The complete docker-compose.yml

services:
  reza-plan:
    build: .
    container_name: reza-plan
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

What every line does

services:               ← start of the services block
  reza-plan:            ← the name of this service (you choose it)

    build: .            ← build the image from the Dockerfile
                          in the current directory (the dot)
                          use "docker compose up --build" to rebuild

    container_name: reza-plan
                        ← give the container a fixed name
                          without this Docker picks a random name

    ports:
      - "3000:3000"     ← host_port:container_port
                          same as -p 3000:3000 in docker run

    volumes:
      - ./data:/app/data  ← bind mount: links ./data on your machine
                            to /app/data inside the container
                            same as -v $(pwd)/data:/app/data in docker run
                            your progress.json lives here safely

    restart: unless-stopped
                        ← automatically restart if the container crashes
                          or if your computer reboots
                          but NOT if you manually run "docker compose stop"

Run the app with Compose

From now on, use these commands instead of docker run:

# Start in the background (builds image if not already built)
docker compose up -d

# Force a rebuild before starting (use after changing Dockerfile or code)
docker compose up --build -d

# See what is running
docker compose ps

# Read logs
docker compose logs -f

# Open a shell in the running container
docker compose exec reza-plan sh

# Stop the container (does not delete it)
docker compose stop

# Stop AND remove the container
docker compose down

# Stop, remove container, AND delete volumes (⚠️ this deletes your data)
docker compose down -v

🔐 Security Note — Bind Mount vs Named Volume:
The ./data:/app/data mount is called a bind mount — it links a specific folder on your machine directly into the container. This is appropriate here because you want easy access to progress.json. The container only sees the data/ folder — it cannot access your src/, your .env files, or anything else. For a production database with sensitive data, you would use a named volume (mydata:/var/lib/postgresql/data) instead, which Docker manages internally.

13. Step 8 — Push Your Image to a Registry

A registry is where Docker images are stored and shared. When you push an image to a registry, anyone with access can pull and run it — including GitHub Codespaces, cloud servers, and teammates.

Option A — Docker Hub (easiest)

Step 1: Create a free account at https://hub.docker.com

Step 2: Log in from your terminal. Use an Access Token, not your password:

• Go to hub.docker.com → click your profile → Account Settings
• Click Security → New Access Token
• Give it a name like “my-laptop”, select “Read & Write” permission
• Copy the token that appears (you only see it once)

docker login
# Enter your Docker Hub username
# For password: paste the Access Token you just created (not your account password)

Step 3: Tag your image with your username:

# Replace "yourusername" with your actual Docker Hub username
docker tag reza-plan:1.0 yourusername/reza-plan:1.0

Step 4: Push:

docker push yourusername/reza-plan:1.0

Step 5: Verify it uploaded. Go to hub.docker.com → your profile → Repositories. You should see reza-plan listed.

Now anyone can run your app with no Node.js installed:

mkdir -p data
docker run -d -p 3000:3000 -v $(pwd)/data:/app/data yourusername/reza-plan:1.0

Option B — GitHub Container Registry / GHCR (best for GitHub projects)

GHCR links your image directly to your GitHub account and repository.

Step 1: Create a Personal Access Token (PAT) on GitHub:

• Go to github.com → click your profile picture → Settings
• Scroll down the left sidebar → click Developer settings
• Click Personal access tokens → Tokens (classic)
• Click Generate new token (classic)
• Give it a name: ghcr-push
• Set expiration: 90 days (or custom)
• Check these scopes: write:packages, read:packages, delete:packages
• Click Generate token at the bottom
• Copy the token immediately — you will not see it again

Step 2: Save the token as an environment variable (so you don’t paste it in plain text):

export GITHUB_PAT=your_token_here

Step 3: Log in to GHCR:

echo $GITHUB_PAT | docker login ghcr.io -u yourgithubusername --password-stdin

Step 4: Tag your image:

# Replace "yourgithubusername" with your GitHub username
docker tag reza-plan:1.0 ghcr.io/yourgithubusername/reza-plan:1.0

Step 5: Push:

docker push ghcr.io/yourgithubusername/reza-plan:1.0

Step 6: Make the package public (so Codespaces can pull it without authentication):

• Go to github.com → your profile → click Packages
• Click reza-plan → Package settings
• Scroll to Danger Zone → click Change visibility → set to Public

🔐 Security Note — Tokens, Not Passwords:
Never paste your GitHub password or account password into terminal commands. Always use Personal Access Tokens with the minimum permissions needed for the task. Store tokens in environment variables, not hardcoded in scripts. If you ever accidentally paste a token into a public place (a GitHub issue, a Stack Overflow post, a commit), revoke it immediately in your GitHub/Docker settings.

14. Understanding Multi-Stage Builds

You have already used a multi-stage build — the Dockerfile has two FROM statements. This section explains why that matters.

What would happen without stages

If we wrote a simple single-stage Dockerfile:

# ❌ Single-stage — do not do this in production
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install        # installs EVERYTHING including Vite, ESLint, etc.
COPY . .
RUN npm run build      # compiles React
EXPOSE 3000
CMD ["node", "server.js"]

The final image would contain:

• Vite (the build tool) — not needed to run the app
• Rolldown / Babel (bundler and compiler) — not needed to run the app
• ESLint (code linter) — not needed to run the app
• All TypeScript type definitions — not needed to run the app
• The React source code in src/ — not needed to run the app (we only need the compiled output in dist/)

Result: ~600MB image, with dozens of extra tools that are security risks.

What the multi-stage build achieves

Stage 1 (builder)                     Stage 2 (production)
─────────────────────                  ─────────────────────
node:20-alpine                         node:20-alpine (fresh)
+ all 200+ npm packages                + express, cors, react, react-dom
+ Vite, Rolldown, Babel                + /app/dist (compiled output only)
+ ESLint, TypeScript tools             + server.js
+ source code in src/
→ compiles React → /app/dist
[THROWN AWAY]                          [THIS IS WHAT SHIPS]

The key Docker instruction that makes this work is:

COPY --from=builder /app/dist ./dist

This reaches into Stage 1 (which is named builder) and copies only the compiled output. Everything else in Stage 1 is permanently discarded.

15. Step 9 — Run in the Cloud with GitHub Codespaces

So far everything has run on your machine. Now let’s move the container to GitHub’s free cloud infrastructure.

Why Codespaces for Docker learners

┌─────────────────────────────────────────────────────────────────────┐
│  The traditional problem:                                           │
│  To share your app with the world, you need a server.               │
│  Servers cost money and require complex setup.                      │
│                                                                     │
│  GitHub Codespaces solves this for learners and small projects:     │
│                                                                     │
│  ✅ Free tier: 60 hours/month on a 2-core Linux machine             │
│  ✅ Docker is pre-installed — no setup                              │
│  ✅ Built-in port forwarding — your container gets a public URL     │
│  ✅ No firewall config, no SSH keys, no server maintenance          │
│  ✅ Deleted when you are done — zero ongoing cost                   │
└─────────────────────────────────────────────────────────────────────┘

Create the .devcontainer folder and config file

The .devcontainer/devcontainer.json file tells GitHub Codespaces how to set up your environment when you open a Codespace.

Step 1: Create the folder and file. In your project root:

mkdir -p .devcontainer
touch .devcontainer/devcontainer.json

Your project structure now looks like:

reza-plan-docker/
├── .devcontainer/
│   └── devcontainer.json    ← create this
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── package.json
└── server.js

Step 2: Open .devcontainer/devcontainer.json and paste this content:

{
  "name": "reza-plan",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "reza-plan",
  "workspaceFolder": "/app",
  "forwardPorts": [3000],
  "portsAttributes": {
    "3000": {
      "label": "Reza Plan App",
      "onAutoForward": "openBrowser"
    }
  },
  "postAttachCommand": {
    "keepalive": "while true; do sleep 240; echo 'alive'; done"
  },
  "hostRequirements": {
    "cpus": 2
  }
}

What each setting does:

"dockerComposeFile": "../docker-compose.yml"
  → use your existing docker-compose.yml to build and run the container
  → the ../ means "go up one folder from .devcontainer/ to find it"

"service": "reza-plan"
  → which service in docker-compose.yml to use
  → matches the name you gave the service in docker-compose.yml

"workspaceFolder": "/app"
  → when the Codespace opens, the terminal starts inside /app

"forwardPorts": [3000]
  → automatically forward port 3000 from the container to the browser

"portsAttributes"
  → when port 3000 is detected, label it and open the browser automatically

"postAttachCommand"
  → runs after the container starts
  → the keepalive loop pings every 4 minutes to prevent the Codespace
    from going to sleep due to inactivity

"hostRequirements": { "cpus": 2 }
  → request a 2-core machine (the free tier supports this)

Step 3: Commit and push all these new files to GitHub:

git add .dockerignore Dockerfile docker-compose.yml .devcontainer/
git commit -m "Add Docker setup and devcontainer config"
git push

Start your first Codespace

Step 1: Go to your GitHub repository in a browser.

Step 2: Click the green Code button (the same one you use to clone).

Step 3: Click the Codespaces tab.

Step 4: Click Create codespace on main.

Step 5: Wait. The first time takes 2–3 minutes. GitHub is:

• Provisioning a Linux machine for you
• Building your Docker container from docker-compose.yml
• Starting the container

Step 6: When it finishes, a VS Code editor opens in your browser with a terminal at the bottom. The terminal is running inside your container.

Step 7: Look at the Ports tab at the bottom of VS Code (next to Terminal). You should see port 3000 listed with a URL like https://your-codespace-name-3000.app.github.dev.

Step 8: Click that URL. Your app is live on the internet.

Make the port public

By default the port URL requires GitHub login to access. To make it truly public:

In the Ports tab, right-click on port 3000 → Port Visibility → Public.

Or using the terminal inside the Codespace:

gh codespace ports visibility 3000:public -c $CODESPACE_NAME

🔐 Security Note: A public port means anyone with the URL can access your app. The reza-plan app is a personal tracker — consider leaving it private (requires GitHub login) if you are storing real study data you do not want to share publicly.

Stop the Codespace when you are done

Always stop your Codespace when not using it to stay within the free tier limits.

Option A — from the browser:

• Go to github.com/codespaces
• Find your codespace → click the three dots ... → Stop codespace

Option B — from the terminal inside the Codespace:

gh codespace stop

16. Step 10 — Automate with GitHub Actions

Manually starting and stopping a Codespace every day gets old quickly. GitHub Actions can do this automatically on a schedule. It’s free, runs in the cloud, and sends you a Telegram notification each time.

How GitHub Actions works

┌─────────────────────────────────────────────────────────────────────┐
│  You write a YAML file with instructions                            │
│  You push it to the .github/workflows/ folder in your repo          │
│  GitHub reads it and runs it automatically on the schedule          │
│                                                                     │
│  It is like cron, but:                                              │
│  - hosted by GitHub (no server needed)                              │
│  - free for public repos and generous for private                   │
│  - has access to GitHub APIs built-in                               │
│  - can send notifications via Telegram, Slack, email, etc.          │
└─────────────────────────────────────────────────────────────────────┘

Create the workflows folder and files

Step 1: Create the folder structure:

mkdir -p .github/workflows

Your project now looks like:

reza-plan-docker/
├── .devcontainer/
│   └── devcontainer.json
├── .github/
│   └── workflows/
│       ├── start-codespace.yml    ← create this
│       └── stop-codespace.yml     ← create this
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
└── ...

Set up GitHub Secrets

The workflow files are stored in your repo and visible to anyone. You cannot put tokens and passwords directly in them. GitHub Secrets stores them encrypted.

Step 1: Get your Codespace name:

• Go to github.com/codespaces
• Look at the name under your repo name — it will be something like expert-bassoon-6vgxv6jv9pv7c49wq
• Copy that exact name — character for character

Step 2: Create a Personal Access Token for the workflows:

• Go to github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
• Click Generate new token (classic)
• Name: codespace-automation
• Expiration: 90 days
• Scopes: check codespace
• Click Generate token → copy immediately

Step 3 (optional but recommended) — Set up Telegram notifications:

• Open Telegram → search for @BotFather
• Send the message: /newbot
• Follow the prompts — give your bot a name and username
• BotFather gives you a TOKEN — copy it
• Start a conversation with your new bot (send it any message)
• Get your chat ID by going to this URL in a browser (replace YOUR_TOKEN): https://api.telegram.org/botYOUR_TOKEN/getUpdates
• Look in the response for "chat": {"id": 123456789} — that number is your chat ID

Step 4: Add all secrets to GitHub:

• Go to your GitHub repository
• Click Settings (top menu of the repo, not your account settings)
• In the left sidebar, click Secrets and variables → Actions
• Click New repository secret for each one:

🔐 Security Note: CODESPACE_NAME must be the full exact name of the codespace — not your repo name, not your username. A wrong value gives a silent 404 error from the API with no clear error message. Always verify by listing your codespaces first:

gh codespace list

Create the start workflow

Create the file .github/workflows/start-codespace.yml and paste this content:

name: Start Codespace

on:
  schedule:
    # Runs at 08:17 UTC every weekday (Mon-Fri)
    # Why 17 and not 0? The top of the hour (8:00) is congested —
    # thousands of scheduled jobs queue at once. Using :17 means
    # your job processes faster with shorter wait times.
    - cron: '17 8 * * 1-5'
  workflow_dispatch:
    # This line makes the workflow also triggerable manually.
    # Go to your repo → Actions → this workflow → Run workflow
    # Always test manually first before relying on the schedule.

jobs:
  start:
    runs-on: ubuntu-latest   # GitHub provides this runner machine for free

    steps:
      - name: Start Codespace via GitHub REST API
        # We use the REST API directly instead of the gh CLI
        # because gh CLI's "start" command broke in newer versions.
        # REST API endpoints are stable and version-independent.
        run: |
          curl -s -X POST \
          -H "Authorization: token $" \
          -H "Accept: application/vnd.github+json" \
          https://api.github.com/user/codespaces/$/start

      - name: Send Telegram notification — success
        # "if: success()" means this step only runs if the previous step worked.
        if: success()
        run: |
          curl -s -X POST \
          https://api.telegram.org/bot$/sendMessage \
          -d chat_id=$ \
          -d text="✅ reza-plan Codespace STARTED at $(date -u '+%H:%M UTC')"

      - name: Send Telegram notification — failure
        # "if: failure()" means this step only runs if something above failed.
        # Exactly ONE of the two notification steps runs per workflow execution.
        if: failure()
        run: |
          curl -s -X POST \
          https://api.telegram.org/bot$/sendMessage \
          -d chat_id=$ \
          -d text="❌ reza-plan START FAILED at $(date -u '+%H:%M UTC') — check GitHub Actions"

Create the stop workflow

Create the file .github/workflows/stop-codespace.yml and paste this content:

name: Stop Codespace

on:
  schedule:
    # Runs at 13:17 UTC every weekday (Mon-Fri)
    # 5 hours/day × 22 weekdays = 110 hours/month
    # Free tier limit is 120 core-hours/month — this stays within it.
    - cron: '17 13 * * 1-5'
  workflow_dispatch:

jobs:
  stop:
    runs-on: ubuntu-latest

    steps:
      - name: Stop Codespace via gh CLI
        # gh CLI works fine for stopping — only starting was broken.
        # This is a real-world lesson: use whatever is reliable.
        # You do not have to be consistent if one method does not work.
        run: |
          gh codespace stop --codespace $
        env:
          GH_TOKEN: $

      - name: Send Telegram notification — success
        if: success()
        run: |
          curl -s -X POST \
          https://api.telegram.org/bot$/sendMessage \
          -d chat_id=$ \
          -d text="🔴 reza-plan Codespace STOPPED at $(date -u '+%H:%M UTC')"

      - name: Send Telegram notification — failure
        if: failure()
        run: |
          curl -s -X POST \
          https://api.telegram.org/bot$/sendMessage \
          -d chat_id=$ \
          -d text="❌ reza-plan STOP FAILED at $(date -u '+%H:%M UTC') — check GitHub Actions"

Understanding the cron schedule

cron: '17 8 * * 1-5'
       │  │  │ │ │
       │  │  │ │ └── day of week: 1-5 = Monday to Friday only
       │  │  │ └──── month: * = every month
       │  │  └────── day of month: * = every day
       │  └───────── hour: 8 = 8am UTC
       └──────────── minute: 17 = at :17 past the hour

Result: runs at 8:17 AM UTC, Monday through Friday only

Free tier math:

5 hours/day (08:17 to 13:17 UTC) × 22 weekdays/month = 110 hours
Free limit: 120 core-hours/month on a 2-core machine
110 hours < 120 hours ✅ — stays within the free tier

Commit and push the workflows

git add .github/
git commit -m "Add GitHub Actions workflows for Codespace start/stop"
git push

Test the workflows manually before waiting for the schedule

Never wait for the cron schedule to discover that a workflow is broken. Test it manually first:

1. Go to your GitHub repository
2. Click the Actions tab in the top navigation
3. In the left sidebar, click Start Codespace
4. Click the Run workflow button on the right
5. Click the green Run workflow button in the dropdown
6. Watch the run — click on it to see each step’s output
7. If it succeeds, check github.com/codespaces to confirm the Codespace started
8. If Telegram is configured, you should receive a notification

Repeat for the stop workflow.

What the API call is actually doing

curl -s -X POST \
-H "Authorization: token GH_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/user/codespaces/CODESPACE_NAME/start

curl            → a command-line tool for making web requests (like a browser, but in the terminal)
-s              → silent mode: no progress bar, just the response
-X POST         → HTTP method POST: means "do something" (vs GET which means "read something")
-H              → add a header: extra information sent with the request
Authorization   → proves who you are: "I am the person who owns this token"
Accept          → tells GitHub: "send me the response as JSON format"
URL             → the exact action: start the codespace with THIS name

17. Docker Best Practices Checklist

Here is an audit of the repo we just built. Use this as a reference for any future Docker project.

✅ What this project does correctly

⚠️ Three improvements to make next

1. Add a non-root USER — most important security improvement

Right now the Express server runs as root inside the container. If a vulnerability in Express or any npm package is exploited, the attacker has root access.

Add these lines to Stage 2 of the Dockerfile, before CMD:

# Create a group and user with no login shell and no home directory
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

# Give the new user ownership of the data directory
RUN mkdir -p /app/data && chown -R appuser:appgroup /app/data

# Switch to the non-root user
USER appuser

🔐 Security Note: This is CIS Docker Benchmark item 4.1 — the most referenced Docker security requirement in DevSecOps job descriptions. A single USER instruction dramatically limits the blast radius of any attack.

2. Use npm ci instead of npm install in both stages

# Instead of: RUN npm install
RUN npm ci

# Instead of: RUN npm install --omit=dev  
RUN npm ci --omit=dev

npm ci is stricter — it uses package-lock.json exactly as written, fails if anything does not match, and does a clean install every time. This prevents “it worked yesterday but not today” situations caused by upstream package changes.

3. Add a HEALTHCHECK

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/entries || exit 1

Without this, Docker considers the container “healthy” as soon as it starts — even if Express crashed one second later. With a healthcheck, Docker actually pings the app every 30 seconds and marks it unhealthy if it stops responding. Kubernetes and load balancers also use this signal.

The improved Dockerfile with all three fixes applied

# Stage 1 — BUILD
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2 — PRODUCTION
FROM node:20-alpine

LABEL maintainer="mradelvand"
LABEL org.opencontainers.image.source="https://github.com/mradelvand/reza-plan-docker"

WORKDIR /app

# Create non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

COPY package*.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist
COPY server.js ./

# Create data dir and give ownership to the non-root user
RUN mkdir -p /app/data && chown -R appuser:appgroup /app/data

# Switch to non-root — everything after this runs as appuser
USER appuser

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/entries || exit 1

CMD ["node", "server.js"]

18. Lessons Learned

These are real problems encountered during this build, documented so you do not have to hit them blind.

Express 5 broke the wildcard route syntax — and the container crashed silently.
app.get('*', handler) is valid in Express 4. In Express 5, path-to-regexp requires named wildcards: app.get('/{*path}', handler). The container starts, throws a PathError before the server binds to any port, and exits with code 1. docker ps shows nothing. docker ps -a shows Exited (1). docker logs shows the exact error. The fix is one character change in server.js. The lesson: always run docker logs before anything else when a container exits immediately.

CLI tools break between versions — REST APIs stay stable.
The gh codespace start command broke in a newer version of the GitHub CLI. The REST API endpoint (POST /user/codespaces/{name}/start) never changed. When a CLI tool gives you trouble, call the API directly with curl. APIs are designed to be stable; CLI tools are convenience wrappers that change with each release.

Secrets must be exact — character for character.
CODESPACE_NAME must be the full random name (expert-bassoon-6vgxv6jv9pv7c49wq), not the repo name, not your username. A wrong value returns a silent 404 from the API with no helpful error message. Always verify with gh codespace list before storing the name as a secret.

The cron schedule is never exactly on time.
GitHub Actions scheduled workflows queue behind other jobs. Using the top of the hour (0 8 * * *) means your job competes with thousands of others that all scheduled for 8:00. Use odd minutes like 17 or 23 — your job runs faster because there is less competition.

Always test with workflow_dispatch before trusting the schedule.
Never write a workflow and then wait until 8 AM tomorrow to find out it is broken. The workflow_dispatch trigger lets you run it manually from the GitHub UI immediately. Fix all errors before the schedule takes over.

Calculate free tier usage before automating.
120 core-hours / month ÷ 2 cores = 60 hours of actual Codespace time. If you run 10 hours/day × 22 weekdays = 220 hours — you hit the limit in 6 days. Always do the math first and design your schedule to stay within the limit.

19. What’s Next

This is Part 1. Here is the full series roadmap:

Resources

• Docker Official Docs
• Node.js Docker Best Practices
• GitHub Codespaces Docs
• GitHub Actions Docs
• Trivy — Image Vulnerability Scanner
• Hadolint — Dockerfile Linter
• OWASP Docker Security Cheat Sheet
• CIS Docker Benchmark

Written by Reza Adelvand — follow the series on GitHub