Sam Nesler

Introduction to Docker

import DockerfilePlayground from '@posts/docker/DockerfilePlayground.tsx'; import ImageContainerDemo from '@posts/docker/ImageContainerDemo.tsx'; import DockerTerminal from '@posts/docker/DockerTerminal.tsx'; import ComposeConverter from '@posts/docker/ComposeConverter.tsx';

Introduction

This workshop is a group project created for the course COMP SCI 502, Theory and Practice of Computer Science Education, at the University of Wisconsin-Madison.

In this workshop, you will learn to run programs inside containers using a platform called Docker. Docker allows developers to package applications and their dependencies into lightweight, portable containers. Think of a container as a standardized unit that includes everything needed to run a piece of software: the code, runtime, system tools, libraries, and settings.

The main benefit of Docker is that it solves the classic "it works on my machine" problem by effectively shipping the machine alongside the program. A containerized application will run the same way whether it's on your laptop, a friend’s computer, or a production server, because the container includes the entire environment the application needs. While they have a lot in common with virtual machines, Docker containers are different: VMs include an entire operating system, but containers share a kernel with the host system. This makes containers much more lightweight and faster to start up, and you can run many containers on a single machine without the overhead of multiple full operating systems.

Developers use Docker for various purposes: ensuring consistency across development and production environments, simplifying deployment, making it easier to scale applications, and isolating different applications from each other. It's become a foundational technology in modern software development, particularly in microservices architectures and cloud computing.

The basic workflow involves writing a Dockerfile (which specifies how to build your container), building an image from that file, and then running containers from that image. Images can be shared through Docker Hub or other container registries, making it easy to distribute applications.

Why should I use Docker?

Pros

Reproducibility (same image ⇒ same environment)
An image freezes your userspace: OS base, packages, config, and entrypoint. If everyone runs docker run myteam/app:1.3, you all get identical behavior.
Fast startup & low overhead (share the host kernel)
Containers don’t boot a full OS; the process starts almost immediately, so iteration is quick. Compared to VMs, you use less RAM/CPU and can run many containers side-by-side.
Strong isolation with easy reset (safe to break things)
If you break a container (even rm -rf / inside it), you can remove and recreate it in seconds from the image. This makes experimentation low-risk for execution.
Infrastructure-as-code with Dockerfiles.
A Dockerfile documents setup steps (FROM, RUN, COPY, CMD) so your environment is auditable and diff-able in Git. Builds are deterministic, and you can refactor layers for speed.
Composable with Linux tooling you already know
Because it's just a process, you can use the standard docker command to manage it, and because the docker command is composable, you can inspect with ps, manage with signals (docker kill → KILL), watch I/O/CPU with time/htop, storage with df -h/du -sh, and listeners with ss -tulpn. Or pipe (|) its text output to other Linux tools like grep to easily filter, automate, and script anything you need.

Cons

Kernel dependency (Linux containers need a Linux kernel)
On Windows/macOS, Docker runs a lightweight VM to provide a Linux kernel. That layer can introduce file-sharing inconsistencies and path differences.
Networking & ports can be confusing at first
Processes inside containers listen on container IPs; you must publish ports to reach them. When something "isn't reachable," check docker logs, docker exec -it <ctr> ss -tulpn, and confirm the app bound to 0.0.0.0 not 127.0.0.1
Excessive disk usage from layers, caches, and container
Builds and pulls accumulate layers, exited containers and dangling images silently consume GBs.
Your responsibility for managing container resources
A single runaway container can exhaust CPU/RAM. Use --cpus, --memory, and docker stats to cap usage, and prefer streaming/pipelines to reduce memory pressure. Remember: your VM may be over-booked.

Deploying your first container

Install docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER  # Add yourself to docker group
# Log out and back in for group changes to take effect

Write your first Dockerfile

FROM python:3.12-slim  # Base image (your starting point)
WORKDIR /app           # Set working directory inside container
COPY app.py .
RUN pip install flask  # Execute commands during build (installs dependencies)
CMD ["python", "app.py"]  # Default command when container starts

Build and run

docker build -t my-first-app .
docker run -p 8080:5000 my-first-app

Boom

Now let's see you give it a try yourself!

What’s the difference between an image and a container?

A Docker image is like a blueprint or template. It's a read-only package that contains everything needed to run an application: the code, runtime, libraries, environment variables, and configuration files. Think of it as a snapshot of a filesystem at a specific point in time. Images are built from Dockerfiles and stored either locally or in registries like Docker Hub.

A container, on the other hand, is a running instance of an image. It's what you get when you execute docker run on an image. While the image is static and immutable, a container is dynamic. The container has its own writable layer on top of the image where changes can be made during runtime. You can create multiple containers from the same image, and each will run independently with its own state. Unless you commit it to create a new image or use volumes, any changes made to the container's filesystem will be lost when the container is removed. The writable layer exists as long as the container exists (even when stopped), but once you run docker rm to remove the container, all those changes disappear.

[!warning] Containers don't persist data! For databases and other stateful applications in Docker, always use volumes to persist data beyond the container's lifecycle!

The core idea is:
An image is a read-only, versioned template (the recipe), it’s stateless.
A container is a running (or stopped) instance created from an image (the meal), it has state.

[!question]- If I edit files inside a running container, does that change the image? No. The image stays read-only; your edits live in the container’s writable layer and won't be transferred to a new container made from the same image. If you edit files in an attached volume or bind mount, your changes will be persisted after the container is deleted.

<figure><figcaption>Image credit: https://decal.ocf.berkeley.edu/</figcaption></figure>

Here's a small interactive demo to visualize images and containers. You can "create an image" by building it, then "run containers" from that image or delete the image. All of these operations correspond to real Docker commands you would run in your terminal, which you'll learn about in the Commands to use and manage Docker section below.

Understanding Image Layers

A Docker image is actually made up of many layers stacked on top of each other. Each instruction in a Dockerfile creates a new layer in the final image. This layered architecture is one of Docker's key innovations that makes it efficient.
When Docker builds an image, it executes each Dockerfile instruction in sequence:

Each RUN, COPY, ADD instruction creates a new layer
Layers are read-only and cached
If you rebuild an image and a layer hasn't changed, Docker reuses the cached version

For example, consider this Dockerfile:

FROM ubuntu:latest               # Layer 1: Base image
WORKDIR /workspace               # Layer 2: Change work directory
RUN apt-get update && apt install …  # Layer 3: Install environment
COPY . .                         # Layer 4: Copy local files
RUN make -j                      # Layer 5: Build command
CMD ["make", "run"]           # Layer 6: Run the program, metadata (no size)

If you only change your application code, Docker can reuse the cached layers 1-3 and only rebuild from layer 4 onward. This makes builds much faster! However, if you switch Layer 3 and Layer 4, because your code base has changed, starting from the changed layer, everything has to be built again. That’s why people would move layers that won’t change too often to the top of the Dockerfile.

[!tip]- Optimizing Dockerfile order Order your Dockerfile instructions from least to most frequently changed. Put dependency installation before copying source code, since code changes more often than dependencies.

Also, you can inspect how an image was built using docker history <image>. However, do note that if you commit a layer, you won't see how that layer is built… So, try not to use the commit command too often, especially for production.

Commands to use and manage Docker

[!information] Docker group and debugging notes You shouldn't need sudo if your user is in the docker group. You can add yourself to this group (on Debian or Ubuntu) by running sudo usermod -aG docker $USER

If a run "does nothing," you likely forgot to supply a command (e.g., bash) or the program exits immediately. To see more information, use -it or check docker logs.

Pull images

What it does: Downloads a snapshot of installed software (an image) from a registry (e.g., Docker Hub) onto your VM. Why first: You run containers from images. No image → nothing to run. Core commands

docker pull ubuntu:24.04  # fetch a specific tag/version
docker images  # list images you have
docker tag ubuntu:24.04 my-ubuntu:lts  # add a convenient name for the same image

[!info]- Docker pull auto-retrieval If docker run references an image you don't have, Docker will try to pull it automatically. Failures like "repository does not exist or may require 'docker login'" are usually a typo in the image name, not an auth problem.

Build images

What it does: Creates your own image by executing scripted install steps inside a temporary build container, then snapshotting the result. Why: Reproducibility. Everyone else can build/get the identical environment instead of "works on my machine." Minimal Dockerfile

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3-pip
RUN pip3 install pandas
CMD ["bash"]  # default program when a container starts

Build it

# build in the current directory (where Dockerfile lives)
docker build -t pandas .

Quick check

docker images | grep pandas

Run containers (from images)

What it does: Starts an isolated Linux sandbox where your processes run Interactive shell

docker run -it ubuntu:25.10 bash

Quick check

docker run ubuntu:25.10 echo "hello"

Inspect and troubleshoot

docker ps                 # running containers
docker ps -a              # include exited
docker logs mybox         # show logs (add -f to follow)
docker exec -it mybox bash # jump into a running container
docker stop mybox         # graceful (SIGTERM then SIGKILL)
docker kill mybox         # force (SIGKILL)
docker rm mybox           # remove stopped container

[!info]- Image as class pattern Think "class → objects": image is the class; each docker run makes a new object (container). Use -it for interactive programs; -d for background jobs. Clean up exited containers periodically (docker rm $(docker ps -aq)), especially when disk fills up.

Compose

What it does: Defines and runs multi-container apps (e.g., web + db) via a single YAML file. Read more in the Docker Compose section below.

services:
  app:
    image: python:3.12
    command: python -m http.server 8000
    ports: ['8000:8000']

Quick Check

docker compose up -d    # start
docker compose ps       # status
docker compose logs -f  # follow logs
docker compose down     # stop & remove

Here's a playground terminal for you to try out Docker commands:

Docker Compose

Docker Compose is a tool for defining and running multi-container applications in a declarative way. Instead of memorizing and typing out long docker run commands with all their flags and options, you write a single YAML file that describes your entire container setup, and Compose handles spinning everything up for you. You describe what you want, and Compose figures out how to make it happen. Even better, it handles things like creating networks automatically, ensuring services can find each other by name, and managing the startup order when services depend on each other.

Try it yourself! This interactive converter lets you switch between Docker Compose and docker run formats. Type in either editor to see the conversion in real-time:

[!question] Wait, not everything in my Compose file is translated into Docker commands! Some directives like build: ./api or depends_on: in the advanced example are Compose-specific and don't have direct docker run equivalents. Compose handles build context, networks, and dependencies for you behind the scenes!

If you wanted to replicate those manually, you'd need to run docker build separately for the build context, and wait to start dependent containers until their dependencies are healthy.

Services can reference each other by their service name. Inside the api container, you can connect to database:5432 rather than having to figure out IP addresses or worry about what network they're on. Compose creates a dedicated network for this application automatically.

Here are some useful Compose commands:

You can bring everything up with docker compose up -d, which starts all services in the background. The -d flag means detached mode, like with regular Docker.
To see what's running, use docker compose ps. This shows you all the services in your application and their status. You can get the logs from all containers with docker compose logs -f, or just one service from docker compose logs -f api
When you need to rebuild your images after code changes, docker compose up --build will rebuild and restart any services that have changed. And when you're done, docker compose down stops and removes all containers, networks, and optionally volumes with the -v flag.

Docker Compose isn't meant for production orchestration at scale (that's where Kubernetes or Docker Swarm come in), but for development, testing, and simple deployments on a single host, it's an incredibly practical tool that eliminates a huge amount of manual coordination and makes your infrastructure reproducible and shareable.

Integrating with Developer Tools

This is my favorite topic to talk about, as these are the ways that I use Docker a lot.
Docker integrates seamlessly with modern development workflows, making it easier to maintain consistent environments across your entire team and CI/CD pipeline.
The key advantage of integrating with developer tools is that they eliminate the "works on my machine" problem. Whether you're coding locally, pushing to CI, or deploying to production, the same Docker image ensures consistency across all environments.

Let’s look at some examples.

VS Code Integration

If you’re sick of typing the docker command, we recommend you to install two VS Code extensions: Container Tools and Docker DX.

Container Tools (by Microsoft) adds a visual interface to manage containers, images, and volumes directly from VS Code. You can pull images, run containers, view logs, attach a terminal, and even attach VS Code (so that you don’t have to forward some ports to ssh into the container). It’s perfect for managing and debugging containers.

Docker DX (by Docker) focuses on authoring. It provides smart IntelliSense, syntax highlighting, and best-practice hints for Dockerfiles, Compose, and Bake files. It can even surface build warnings and vulnerabilities inline while you write.

[!question] Well, what's the Docker Extension Pack then? As of publishing, it's an extension pack that contains a single extension, making it effectively another way to download Container Tools. So, for the best experience, it’s recommended to install Container Tools and Docker DX separately.

Dev Container (and Codespaces)

If you’ve ever cloned a project, spent half an hour setting up dependencies, and then discovered “it works on my machine but not yours,” Dev Containers are here to save you.

A Dev Container is basically a Docker-powered development environment defined by a simple config file (.devcontainer/devcontainer.json). It tells VS Code what image to use, which extensions to install, and how to set up the workspace.

You just open the folder in VS Code, and it automatically builds and launches the containerized environment. From your perspective, it feels like you’re coding on your local machine, but in fact, everything runs inside the container. That means your dependencies, compilers, and runtimes are all isolated and reproducible.

Codespaces takes this one step further. It’s the same idea as Dev Containers, but hosted in the cloud by GitHub. Instead of building locally, Codespaces spins up your container on a remote VM, preloaded with your code and environment. You can connect to it from VS Code or even use it straight in the browser. This is perfect for quick edits, demos, or when your laptop fan sounds like it’s about to take off.

Here is an example of devcontainer.json:

{
  "name": "Example Dev Container",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "forwardPorts": [3000, 5000, 5173],
  "postCreateCommand": "npm --version && node --version",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
      "settings": {
        "editor.rulers": [120],
        "editor.formatOnSave": true,
        "editor.tabSize": 4
      }
    }
  }
}

Approach 1:

docker network create myapp-network
# Start database
docker run -d \
  --name db \
  --network myapp-network \
  postgres:15

# Start web app
docker run -d \
  --name web \
  --network myapp-network \
  -p 8080:8080 \
  -e DATABASE_URL=postgresql://db:5432/mydb \
  My-web-app # Then communicate use container name as host name

Approach 2: Docker Compose

Create docker-compose.yaml file:

services:
  database:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret

  web:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgresql://database:5432/mydb
    depends_on:
      - database

docker compose up -d

Then each container can communicate with another using host name and docker will automatically resolve it to the correct IP address

Build Your Own Portfolio Website For Free

Introduction

This guide is a written and extended version of the workshop I wrote for WebLabs, a student organization run by some of my friends at the University of Wisconsin-Madison.

Have you ever wanted your own website, but been put off by the limited customization options (and monthly prices) of Carrd, Wix, or Squarespace? Or maybe you've tried to set up a blog using WordPress, but found it too complicated? It's one thing to learn basic HTML/CSS, but another thing entirely to actually deploy your work somewhere where people can see it. This workshop will help you build your own portfolio (and blog) using Astro, GitHub, and Markdown, assuming that you've only worked with bare HTML/CSS and a bit of JS so far. You won't need anything besides a GitHub account and a browser to get started.

This guide is meant to be a starting point for you to build your own portfolio website and host it for free. By "your own portfolio," I mean a site that you can customize and make your own. You can add your own images, change the layout and colors, and add any pages you like. The goal is to give you the tools and knowledge to create a website that reflects your personal style and interests.

Why Even Bother?

Whether you're trying to land your first internship, link out from your socials, or just improve your skills, having a personal website that you own is incredibly valuable when everyone else is on centralized social platforms. Things like Carrd are fine, but they're limited and cost money if you want to customize them. Beyond practical considerations, you learn a lot more by shipping stuff, rather than just reading about it or using it for homework. This guide will take you through a handful of free programs and websites that are used every day by developers in the real world, and will be invaluable for your growth as a developer. You can throw it on LinkedIn, your resume, your email signature, your cat's collar...

What You'll Need

A GitHub account
A browser
~1 hour (less if you type fast)

Outline

First, we'll develop the basic website design with CodePen.
Next, we'll set up the GitHub repository to host our portfolio.
Then, we'll port the CodePen code to Astro and add images.
After that, we'll deploy the site to GitHub Pages, which is free and easy to use.
Then we'll drop into GitHub Codespaces to add a blog to our portfolio using Astro's content collections.
Finally, I'll suggest some ways to improve your portfolio and blog, and give you some resources to learn more about Astro and web development in general.

Step 1: Mess Around on CodePen

go.weblabs.club/portfolio-js

Get a feel for how your portfolio might look:

Don't worry about images yet.
In the HTML panel, fill in your name, bio, links, skills, projects.
Use the CSS variables to change colors and fonts, if you like.
Once you're happy with it, we'll move onto the next step.

Step 2: Clone the GitHub Template

go.weblabs.club/portfolio-github

This template repository is essentially what you get by running npm create astro@latest and selecting the basic template, but I ripped out the parts that are unnecessary for this workshop. It doesn't include anything besides the bare minimum configuration, we'll be adding everything else as we go.

Sign in to GitHub.
Use the template to make a repo named ${your-username}.github.io.

This is where your site will live. Beyond storing code, GitHub offers several other useful services like GitHub Pages, GitHub Actions, and GitHub Codespaces. In this case, GitHub Pages will host your site at that URL later.

Step 3: CodePen, meet Astro

Astro is static site builder with zero JS by default, unless you opt in. It's perfect for beginners that want a little extra sauce out of their HTML. You'll get components (like React) but no runtime overhead, and you can do cool things like Markdown-based blogs without needing a CMS.

Porting to Astro

Your HTML/CSS from CodePen drops in almost unchanged.

Open src/pages/index.astro on GitHub and select the pencil (edit) button.
Paste your CodePen HTML between the <Layout> tags.
Paste your CSS in a <style is:global> block after the HTML.

---
import Layout from '../layouts/Layout.astro';
---

<!-- Example -->
<Layout>
  <!-- Your HTML here -->
</Layout>

<style is:global>
  /* Your CSS here */
</style>

[!question]- What's the deal with is:global? The is:global attribute tells Astro that this CSS should be applied globally, rather than scoped to the component. This is useful for styles that you want to apply to the entire page, like your main layout or global styles. In this case, you might later decide to break apart the page into components, and using is:global simplifies that process a bit since you don't have to disentangle which styles need to be copied over to the component.

Now for deployment:

On GitHub, go to the Actions tab.
Search for “Astro”, click to enable the action.
Then go to Settings > Pages and choose the GitHub Action as your source.
Wait a few seconds, then go to https://your-username.github.io.

It's live, and it's that simple.

[!question]- Why do the icons still work? Okay, you got me. I cheated a bit, this template does include the same FontAwesome stylesheet that the CodePen template does. You can see it hiding in src/layouts/Layout.astro in the <head> section. Layout.astro is a component that wraps around your HTML, and it includes the <head> section for you. You can also add your own stylesheets or other scripts in there, if you want.

[!question]- What is GitHub Actions? GitHub Actions is a way to automate tasks in your GitHub repository, like running tests, building your code, or deploying your site. It essentially lets you briefly borrow a completely clean computer to run your code, and then throw it away when you're done. In this case, we're using it to build our Astro site (which needs to run code to build) and deploy it to GitHub Pages. You can think of it as a way to run your code in the cloud, without needing to set up a server or anything like that.

[!question]- How can GitHub pages be free? GitHub Pages only works for static files (so just HTML, CSS, JS and images). This means that you can't run any server-side code (like PHP or Node.js) on GitHub Pages, because GitHub doesn't run a server for you. Instead, your GitHub action will produce a handful of those HTML/CSS files, which GitHub stores up on a CDN, and your visitor's browsers do the work of rendering them. Serving static files is cheap enough that GitHub can afford to do it for free.

Also, it's technically only free for public repositories, which means that anyone can see your code. GitHub does this partially because they want to encourage open-source development and collaboration, and partially because they're owned by Microsoft and can eat the cost.

CloudFlare is another company that does free static hosting, and in their case they serve something like 20% of all websites through their CDN. In their case, the marginal cost of storing a couple megabytes of data on the CDN that other people are already paying for is negligible, so they can afford to give it away for free.

Step 4: Add Images

Let's add some photos while we're here. You can do this from the GitHub web interface as well.

Upload your image files to /public.
Refer to them like:
```
<img src="/myimage.png" />
```
No public/ prefix, just the slash.

[!question]- Why no public/? The public folder is a special folder in Astro, and most JS frontend frameworks. Anything in there isn't processed, and instead placed at the root of your final site, so /public/myimage.png will become just /myimage.png after building. This is different from other frameworks like React, where you have to use public/ in the path.

Step 5: Add Blog with Content Collections

This part would have been a live demo in the in-person workshop, so it's a little more informal, and there unfortunately are no template repos for you to copy. Now that we've got a wonderful portfolio site with all our projects and images, let's add a blog to it. This is a great way to show off your skills and share resources (like this workshop) with the world.

Astro's content collections allow you to create a blog with Markdown files. You can write your posts in (effectively) plain text, and Astro will take care of the rest. We'll also be using something called "frontmatter" to add metadata to your posts, like the title, date, and image.

[!QUESTION]- What is Markdown? Markdown is a lightweight markup language that allows you to write formatted text in plain text files. Markdown files are typically saved with a .md extension and can be easily converted to HTML. As a result, they're widely used for writing content on the web. Some places you might've seen Markdown are GitHub READMEs, Discord, Reddit, Notion, or Obsidian. It's a great way to write content without spending lots of time fussing with HTML tags.

Astro's markdown support uses specifically GitHub-flavored Markdown, which is a superset of the original Markdown spec.

This blog post is written in Markdown, and you can see how it looks in the source code! You'll notice the extension is .mdx, which is a special version of Markdown that allows you to use React components inside your Markdown files. This post doesn't use that feature, but Astro supports MDX too.

1. Open up GitHub Codespaces

We've been getting by on GitHub's web interface so far, but now we need to do some more complicated things. GitHub Codespaces is a way to run a full VSCode instance in your browser, and you get a certain number of hours for free. It's plenty for this use-case, but you can also use VSCode locally if you prefer.

You can open a GitHub Codespace by clicking the "Code" tab at the top of your repo, then clicking the green "Code" button above your files, then the "Codespaces" tab within the popup that appears. Finally, select "Create Codespace on main". This will create a new Codespace for you, which is a full VSCode instance running in your browser. It'll also download your repo dependencies, so all you need to do is wait a minute or so for it to load, then type npm run dev in the terminal to see a live preview of your site.

2. Define Your Blog Schema

Astro's content collections are a way to define the structure of your content. You can think of them sort of like creating a database for your blog posts. Each post will have a title, date, and other metadata that we'll use later to display your posts on the site.

Create src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.date(),
    excerpt: z.string(),
    image: z.string().optional()
  })
});

export const collections = {
  blog: blogCollection
};

3. Write Some Posts

Create at least one Markdown file in src/content/blog/.

src/content/blog/first-post.md:

---
title: 'First Blog Post'
date: 2025-04-16
excerpt: 'A quick dive into making your first blog post in Astro.'
---

Here's your actual blog content. Markdown works here!

[!question]- What is frontmatter? You'll notice that the Markdown file starts with a block of text between --- lines. This is called "frontmatter", and it's a way to add metadata to your Markdown files. The frontmatter is written in YAML, which is a human-readable data format. Think of it a bit like JSON. In this case, we're using it to define the title, date, and excerpt for our blog post. Astro will use this frontmatter to display the title, date, and excerpt elsewhere on the site. You can also use frontmatter to define other metadata, like tags, categories, and more.

4. Show Posts on the Main Site

Back in your src/pages/index.astro, import your blog collection at the top of the file (the frontmatter area that was YAML in Markdown files is JavaScript in Astro):

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
const sortedPosts = posts.sort((a, b) => b.data.date.getTime() - a.data.date.getTime()); // sorts by date, if you like
---

Then, replace the dummy blog section further down the file with this:

<section id="blog" class="blog">
  <div class="container">
    <h2>Blog</h2>
    <p>Thoughts, tutorials, and insights</p>
    <div class="blog-grid">
      {
        sortedPosts.map(post => (
          <div class="blog-card">
            <div class="blog-date">{post.data.date.toLocaleDateString('en-US')}</div>
            <h3>{post.data.title}</h3>
            <p>{post.data.excerpt}</p>
            <a href={`/blog/${post.slug}`}>
              Read More <i class="fa-solid fa-arrow-right" />
            </a>
          </div>
        ))
      }
    </div>
  </div>
</section>

You'll notice that, like React, Astro uses {} to interpolate JavaScript into your HTML. This is a great way to dynamically generate content based on your data. In this case, we're using it to loop through the blog posts and display them in a grid. Note that unlike React, this JavaScript will only run once at build-time, so you shouldn't try to make it interactive.

You'll also notice that we're linking to /blog/${post.slug}. Let's go create that page now!

5. Create a Template for Individual Posts

Make src/pages/blog/[...slug].astro:

---
import { getCollection } from 'astro:content';
import Layout from '../../layouts/Layout.astro';

// Generate paths for all blog posts
export async function getStaticPaths() {
  const blogEntries = await getCollection('blog');
  return blogEntries.map(entry => ({
    params: { slug: entry.slug },
    props: { entry }
  }));
}

// Get the blog post content
const { entry } = Astro.props;
// Markdown is text, so we need to "render" it to transform it into HTML
const { Content } = await entry.render();
---

<Layout>
  <article class="blog-post container">
    <h1>{entry.data.title}</h1>
    <time datetime={entry.data.date.toISOString()}>
      {
        entry.data.date.toLocaleDateString('en-US', {
          year: 'numeric',
          month: 'long',
          day: 'numeric'
        })
      }
    </time>
    <div class="blog-content">
      <Content />
    </div>
    <a href="/#blog">← Back to Blog</a>
  </article>
</Layout>

Now if you go to /blog/first-post (or whatever you named your markdown file), you should see your blog post!

[!question]- What is getStaticPaths? Astro does all its work at build time (inside your GitHub Action), so it needs to know what pages to generate ahead of time. getStaticPaths is a way to tell Astro which pages to generate based on your data. In this case, we're using it to generate a page for each blog post in our collection. You can think of it as a way to "pre-render" your pages at build time, rather than waiting for the user to request them, since we aren't allowed to run any server-side code on GitHub Pages.

6. Commit Your Hard Work

Let's commit your changes in Codespaces, and push them to GitHub, so your Action can run and your site will be live! You can do that by selecting the "Source Control" tab (looks like a few nodes connected by lines, and probably has a notification icon on it) on the left sidebar, then clicking the "+" icon next to each file you changed. Then, type a commit message (like "Added blog") and click the "Commit" button to commit your changes. Finally, click the "Sync Changes" button at the top of the sidebar to push your changes to GitHub.

Wait a minute, then refresh your site. You should see your blog posts on the homepage, and if you click on one, it should take you to the individual post page!

You're Done (But You Should Totally Keep Going)

This is a great start, but there's so much more you can do with Astro. Here are some ideas and links to get you started:

The blog post page is... lightly themed, to say the least. You could totally spruce it up a bit.
Maybe you don't want all your posts on the home page. You can add another page that just lists your blog posts!
Tailwind is a common way to add some styling to sites in a more terse form than straight CSS. You can add Tailwind to Astro in just a few minutes, and it makes it super easy to add responsive styles and custom themes.
If you want to add reactivity, you can add frontend frameworks like React and Svelte to Astro with just a few commands. Astro is designed to work with these frameworks, so you can use them to build interactive components without needing to set up a whole React or Svelte app. You can also use MDX to write your blog posts in Markdown and include React components inside them.
You could set up Giscus for a free commenting system on your blog posts. You can see an example of it on this very page! Giscus is a free, open-source commenting system that uses GitHub Discussions to store comments. It's a great way to add comments to your blog posts without needing to set up a whole backend or database. You can also use it to get feedback on your posts and engage with your readers.
Having the username.github.io URL is a bit lame. You can set up a custom domain, but you'll have to pay for one. They're usually less than $15/year, though, so it's worth it if you want to continue doing things on the web. tld-list.com is a good way to search for domains that aren't already registered!
If you use Discord, you might consider setting up my Discord GitHub Preview project :). It'll show your Discord activity in an SVG that you can place in an <img> tag. This is a great way to show off your activity and make your site more dynamic.
If you plan to post a lot on your blog, you might set up an RSS feed so people can subscribe to it. This is a great way to keep your readers updated on your latest posts, and it's a good way to learn about RSS feeds and XML. Astro also makes this dead simple.

Things I Use

Here's a list of the tools, software and many other things that I use on a daily basis. This page was inspired by Wes Bos and his project - uses.tech.

Web

Browser

It used to be Firefox with lots of extensions to make it look and feel like Arc, but then Zen came out and I switched to it.

Zen is an open-source Firefox fork with many of the same UI features as Arc, and it's still receiving support (unlike Arc, RIP). It also works better on my Windows desktop and laptop than Arc did.

Extensions

Augmented Steam - Enhances Steam with additional information
Bitwarden - Excellent password manager
Dark Reader - Auto dark mode for every website (helpful for battery life on my OLED laptop)
Imagus Mod - Image hover zoom (useful for Reddit)
uBlock Origin - One ad blocker to rule them all

Websites

Cobalt - YouTube video downloader that I don't personally use but would be remiss not to mention (see Vividl below!)
CyberChef - A web app for encoding, decoding, and analyzing text data in a variety of formats
DevDocs - A frontend for various language/library documentation sites with quick search.
Hoppscotch - A Postman alternative PWA, great for quick API testing
IsThereAnyDeal - Great for tracking game prices and bundles, with an excellent waitlist feature
LofiMusic - A music player PWA for lo-fi music YouTube livestreams
MyNoise - A fantastic noise generator that I use for focus and relaxation
Pocket Casts - My podcast app of choice (partially because I bought the web app before they went a subscription model)
Winstall - A WinGet command generator that makes it easy to install a bunch of apps at once, like Ninite on steroids
Wormhole - A dead simple, super fast way to send <10gb files between devices. Great for sharing things with friends, and it's been around for a while so I'm confident it won't disappear.

Windows

I have a desktop and laptop that I love dearly.

import Card from '@/components/cards/Card.astro';

<div class="grid gap-4 md:grid-cols-2"> <Card>Desktop OS: Windows 11 CPU: Intel Core i5-10600KF GPU: Nvidia RTX 4060 Ti 16gb</Card> <Card>Laptop OS: Windows 11 Model: ASUS Zenbook CPU: AMD Ryzen 7-7730U</Card> </div>

Windows Apps

Affinity Suite - Sometimes I want to do some vector graphics work or image editing, but I can't justify an Adobe subscription and I'm not going to admit to pirating it. Affinity is a great alternative! I've been with them for years now, since I initially bought Affinity Designer on sale for $25 (I was previously making YouTube thumbnails in Apple Keynote, of all things)
Microsoft Powertoys - A collection of utilities you'd be be a tool to miss.
Notion Calendar - Just a nice calendar app. Since the rebrand, it can also pull in assignments from my Notion database and display them on my calendar too.
Notion - Notion is great for organizing tasks in just the right way for me, and it can hold notes and my game backlog too. It has a decent enough API, so when combined with a self-hosted n8n instance, I can freely write my own little extensions to sync Canvas assignments, Todoist tasks, and game backlog data from outside sources. In theory, I could do much of the same things with Obsidian too, but the ease of syncing, sharing, and extending with Notion win out.
PlayNite - If you're anything like me, you've been accumulating free games for years from Amazon Prime, Epic Games, and other sources. Combine that with a habit of "buying games wherever they're cheapest" and owning console games, and you end up with a mess of launchers and libraries. PlayNite is a free, open-source app that lets you manage all your games in one place, no matter where they came from. It also has a great plugin system that lets you add features like game tracking, achievements, and more. I find it more robust and extensible than GOG Galaxy, though that's a great option too.
Raycast - My launcher of choice, recently in beta for Windows. I loved it back on my Mac, and I feel it beats PowerToys Run and even the new Windows Command Palette in terms of speed and stability. It already has a great library of extensions, and I'm excited for future development!
ShareX - Screenshotting and screen recording app.
Spark - As far as I know, Spark is the only 1) nice-looking 2) native Windows mail app that is 3) free and has 4) automatic categories.
Vividl - Great free YouTube video downloader. Functionally a frontend for yt-dlp, so it doesn't usually break.
Yasb - A highly configurable Windows status bar written in Python. Between this, Raycast, and Zen, I wonder if I should just go back to MacOS?

Homelab

This is how I got into programming in the first place. There's no magic quite like wiring up 6 Docker containers on a $150 Windows box and getting a website out of it, and I've continued that for about 8 years to my still-modest current setup.

<Card>Inkstation OS: OpenMediaVault CPU: Intel i5-2500S Uptime: too long</Card>

Homelab Services

A homelab is nothing without something for it to host. These ones are my favorites, either because they're the best of the alternatives I tried or they're just really cool:

Authelia - No-nonsense auth provider that makes securing other apps straightforward.
Authentik - ...that said, Authentik is harder to set up but way more flexible.
Bluemap - Serves 3D maps of Minecraft worlds over the web. Check out past worlds and maybe even my current server.
Caddy - A reverse proxy that's much simpler to set up than nginx or Traefik.
Caddy-Docker-Proxy - Wonderful Caddy extension that makes deploying new containers to a subdomain as easy as 2 labels on a container.
Calibre-web - Drop-in replacement for my Kobo e-reader's sync server, allowing me to get books to it from anywhere.
Croc - Super simple CLI file transfer tool that handles discovery for you. Nice for university computers.
n8n - Node-based automation platform. All the little things that Zapier would be helpful for, but free.
Plausible - Analytics that are super easy to just slot into any project
Plex - Media server extraordinaire. Music support is better than Jellyfin's equivalent, imo.
Pterodactyl - Host and manage many game servers, with less management work than running them bare.
Seafile - File storage with rock-solid sync, and direct-download share links
Tailscale - Allows me to access this server and my 3 VPSes without exposing them to the web. Taildrop is great for iOS and Windows file transfer, especially when the network doesn't allow LAN devices to talk to each other.