Initial commit

Author: mikesir87

…hub/workflows/publish-labspace.yaml.temp .github/workflows/publish-labspace.yaml.github/workflows/publish-labspace.yaml.temp renamed to .github/workflows/publish-labspace.yaml .github/workflows/publish-labspace.yaml.temp renamed to .github/workflows/publish-labspace.yaml

@@ -1,48 +1,52 @@
-# Labspace starter
+# Labspace - Compose Quickstart
 
-This repository is intended to server as a template to help bootstrap a new Labspace.
+An interactive lab that teaches Docker Compose fundamentals by building a multi-container Python Flask and Redis application from scratch. Learners progress from a bare `compose.yaml` through health checks, live development with watch mode, data persistence with volumes, and multi-file Compose configurations.
 
-## Instructions
+## Learning objectives
 
-1. Create a new repository using this repo as the template ([docs here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)).
+This Labspace will teach you the following:
 
-    **NOTE:** After creating the repo, a GHA workflow will run to do some additional bootstrapping. The bootstrapping workflow file will be removed during bootstrapping.
+- Define a multi-service app in a `compose.yaml` file
+- Control startup order with health checks and `depends_on`
+- Iterate on code quickly using watch mode
+- Persist data across container restarts with named volumes
+- Compose multi-file configurations with the `include` directive
+- Use core debugging commands (`config`, `logs`, `exec`)
 
-2. Clone your newly created repo to your local machine
+## Launch the Labspace
 
-3. Start the local development mode:
+To launch the Labspace, run the following command:
 
-    ```bash
-    # On Mac/Linux
-    CONTENT_PATH=$PWD docker compose up --watch
+```bash
+docker compose -f oci://dockersamples/labspace-compose-quickstart up -d
+```
 
-    # On Windows with PowerShell
-    $Env:CONTENT_PATH = (Get-Location).Path; docker compose up --watch
-    ```
-
-4. Update the `labspace/labspace.yaml` with your Labspace's title and description
+And then open your browser to http://localhost:3030.
 
-5. Write your Labspace! Being in dev mode, your changes should be visible in the interface without a restart. Feel free to edit either on your host machine or in the Labspace itself!
+### Using the Docker Desktop extension
 
-    Add any supporting application files or resources directly into the Labspace. This repo will be cloned into the Labspace at startup.
+If you have the Labspace extension installed (`docker extension install dockersamples/labspace-extension` if not), you can also [click this link](https://open.docker.com/dashboard/extension-tab?extensionId=dockersamples/labspace-extension&location=dockersamples/labspace-compose-quickstart&title=Compose%20Quickstart) to launch the Labspace.
 
-    Be sure to check out the [docs](https://github.com/dockersamples/labspace-infra/tree/main/docs) for additional information and guidelines.
+## Contributing
 
+If you find something wrong or something that needs to be updated, feel free to submit a PR. If you want to make a larger change, feel free to fork the repo into your own repository.
 
+**Important note:** If you fork it, you will need to update the GHA workflow to point to your own Hub repo.
 
-### Setting up the deployment pipeline
+1. Clone this repo
 
-The template repo contains a workflow file to make it easy to publish your Labspace.
+2. Start the Labspace in content development mode:
 
-1. Add GitHub Action Secrets in your new repo for the following:
+    ```bash
+    # On Mac/Linux
+    CONTENT_PATH=$PWD docker compose up --watch
 
-    - `DOCKERHUB_USERNAME` - the username to authenticate to Docker Hub with
-    - `DOCKERHUB_TOKEN` - a personal or organization access token to use for authentication
+    # On Windows with PowerShell
+    $Env:CONTENT_PATH = (Get-Location).Path; docker compose up --watch
+    ```
 
-2. In the `.github/workflows/publish-labspace.yaml.temp` file, update the `DOCKERHUB_REPO` with the name of the Docker Hub repo you want to publish to.
+3. Open the Labspace at http://dockerlabs.xyz.
 
-3. Rename the workflow file to remove the `.temp` extension.
+4. Make the necessary changes and validate they appear as you expect in the Labspace
 
-    ```bash
-    mv .github/workflows/publish-labspace.yaml.temp .github/workflows/publish-labspace.yaml
-    ```
+    Be sure to check out the [docs](https://github.com/dockersamples/labspace-infra/tree/main/docs) for additional information and guidelines.

README.md

@@ -3,19 +3,5 @@ services:
     environment:
       PROJECT_CLONE_URL: https://github.com/dockersamples/labspace-compose-quickstart
 
-  # workspace:
-  #   # Override the default image if desired
-  #   # More details - https://github.com/dockersamples/labspace-infra/blob/main/docs/configuration.md#overriding-the-workspace-image
-  #   image: dockersamples/labspace-workspace-java
-
-  #   # Override the default ports to publish additional ports you may need
-  #   # More details - https://github.com/dockersamples/labspace-infra/blob/main/docs/configuration.md#overriding-the-workspace-ports
-  #   ports: !override
-  #     - "6274:6274" # Expose the MCP inspector users will launch from inside the Labspace
-  #     - "8080:8080" # The port used by the app
-
-  #   # Add other environment variables as needed
-  #   environment:
-  #     DANGEROUSLY_OMIT_AUTH: "true" # Skip auth for the MCP Inspector
-
-# Add other models or services your Labspace may need
+  workspace:
+    image: dockersamples/labspace-workspace-python

compose.override.yaml

@@ -1,21 +1,49 @@
-# Introduction
+# Welcome to Docker Compose Quickstart! 🐳
 
-👋 Welcome to the **Labspace starter** lab! During this lab, you will learn to do the following:
+Docker Compose is a tool for defining and running multi-container applications. Instead of managing each container by hand, you describe your entire application stack in a single `compose.yaml` file and bring everything up with one command.
 
-- Learning Objective 1
-- Learning Objective 2
-- Learning Objective 3
-- Learning Objective 4
+In this lab, you'll build a **Python Flask web app** backed by **Redis** — a classic multi-container setup. Along the way, you'll learn how to:
 
+- Define services in a `compose.yaml` file
+- Control startup order with health checks
+- Iterate on code quickly with watch mode
+- Persist data across container restarts
 
-## 🙋 What is a Labspace again?
+## Verify your environment
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis lacinia nisi sit amet auctor accumsan. Maecenas suscipit, libero quis ullamcorper pulvinar, dolor nisl vehicula orci, vel egestas arcu nibh eget enim. 
+Before diving in, confirm that Docker and Compose are available:
 
-Suspendisse potenti. Pellentesque eleifend eget ante eu egestas. 
+```bash
+docker version
+```
 
-Nunc sit amet dapibus erat. Aliquam diam arcu, fringilla hendrerit metus sed, pellentesque fringilla lacus. 
+```bash
+docker compose version
+```
 
-Nulla ornare nulla risus. Curabitur ut ipsum euismod, accumsan lorem eu, pretium lorem. Fusce imperdiet fermentum hendrerit.
+You should see version information for both. If either command fails, the environment may need a moment to initialize — try again in a few seconds.
 
+## Tour the starter files
 
+The project already contains everything needed to build and run the app. Take a look:
+
+```bash
+ls -la
+```
+
+| File | Purpose |
+|------|---------|
+| `app.py` | The Flask web application |
+| `requirements.txt` | Python dependencies |
+| `Dockerfile` | Instructions to build the container image |
+| `.env` | Default environment variable values |
+| `.dockerignore` | Files to exclude from the build context |
+
+Open :fileLink[app.py]{path="app.py"} to see the application code. It's a simple hit counter that increments a value in Redis each time someone visits the page, and reports the total back to the browser.
+
+Open :fileLink[Dockerfile]{path="Dockerfile"} to see how the image is built. It starts from the official `python:3.12-alpine` base, installs dependencies, copies the source code, and runs Flask.
+
+> [!NOTE]
+> Notice that `.env` is listed in `.dockerignore`. This prevents the `.env` file from being copied into the container image during `docker build` — a good security practice, since `.env` files often contain secrets.
+
+In the next section, you'll connect these pieces together using Docker Compose.

labspace/01-introduction.md

@@ -0,0 +1,81 @@
+# Defining Services with Compose
+
+A `compose.yaml` file is where you declare every service that makes up your application, along with its configuration: which image to use, which ports to expose, environment variables, and more.
+
+## Creating your Compose stack
+
+Your app needs two services:
+
+- **web** — the Flask app, built from your local `Dockerfile`
+- **redis** — the official Redis image for storing the hit count
+
+```mermaid
+flowchart LR
+  web["Flask app<br>(web)"] --> redis["Redis<br>(redis)"]
+```
+
+&nbsp;
+
+1. Create a `compose.yaml` file with the following contents:
+
+    ```yaml save-as=compose.yaml
+    services:
+      web:
+        build: .
+        ports:
+          - "${APP_PORT:-8000}:5000"
+        environment:
+          - REDIS_HOST=${REDIS_HOST:-redis}
+          - REDIS_PORT=${REDIS_PORT:-6379}
+
+      redis:
+        image: redis:alpine
+    ```
+
+    > [!TIP]
+    > Compose automatically loads variables from your `.env` file. The `${VAR:-default}` syntax uses the value from `.env` if present, otherwise falls back to the hardcoded default. This lets you override settings without modifying the Compose file.
+
+2. Start the stack using the `docker compose up` command:
+
+    ```bash
+    docker compose up --build -d
+    ```
+
+    The `--build` flag ensures the `web` image is (re)built from your `Dockerfile` before starting. The `-d` flag runs everything in the background (detached mode).
+
+3. Check that both services are running:
+
+    ```bash
+    docker compose ps
+    ```
+
+    You should see output similar to the following:
+
+    ```console no-copy-button no-run-button
+    NAME              IMAGE          COMMAND                  SERVICE   CREATED         STATUS         PORTS
+    project-redis-1   redis:alpine   "docker-entrypoint.s…"   redis     5 seconds ago   Up 4 seconds   6379/tcp
+    project-web-1     project-web    "flask run --host=0.…"   web       5 seconds ago   Up 4 seconds   0.0.0.0:8000->5000/tcp, [::]:8000->5000/tcp
+    ```
+
+4. View the app by opening your browser to :tabLink[http://localhost:8000]{href="http://localhost:8000" title="Flask App" id="app"}
+
+5. Refresh the page a few times — the counter increments with every visit!
+
+## Explore some Compose commands
+
+Check the logs from the web service:
+
+```bash
+docker compose logs web
+```
+
+Stop and remove the containers (and the default network Compose created):
+
+```bash
+docker compose down
+```
+
+Run `docker compose ps` again — the containers are gone. The image you built is still cached, so the next startup will be faster.
+
+> [!IMPORTANT]
+> Notice that the hit counter resets to 1 when you bring the app back up. Redis stores data inside the container's writable layer, and that layer disappears when the container is removed. You'll fix this with named volumes in a later section.

labspace/02-defining-services.md

@@ -0,0 +1,63 @@
+# Health Checks & Startup Order
+
+Right now, your `web` service starts at roughly the same time as `redis`. But what if Redis isn't ready to accept connections when Flask first tries to connect? The `web` container crashes before it can serve a single request.
+
+This is a **startup race condition**, and it's a common issue in multi-container applications.
+
+## The solution: healthcheck + depends_on
+
+Docker Compose can wait for one service to become *healthy* before starting another. You need two things:
+
+1. A **healthcheck** on `redis` that actively tests whether it's ready to accept connections
+2. A `depends_on` condition on `web` that waits until `redis` is healthy
+
+Update your Compose file to add both the `depends_on` and `healthcheck` configurations:
+
+```yaml save-as=compose.yaml highlight=9-11,15-19
+services:
+  web:
+    build: .
+    ports:
+      - "${APP_PORT:-8000}:5000"
+    environment:
+      - REDIS_HOST=${REDIS_HOST:-redis}
+      - REDIS_PORT=${REDIS_PORT:-6379}
+    depends_on:
+      redis:
+        condition: service_healthy
+
+  redis:
+    image: redis:alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+```
+
+The healthcheck runs `redis-cli ping` every 5 seconds. Once Redis responds with `PONG`, it's considered healthy — and only then will `web` start.
+
+## See it in action
+
+1. Start the application:
+
+    ```bash
+    docker compose up --build -d
+    ```
+
+2. Watch the startup sequence:
+
+    ```bash
+    docker compose ps
+    ```
+
+    The `redis` service will show `(healthy)` in its status before `web` finishes starting. This guarantees correct startup order every time, regardless of machine speed.
+
+3. Visit the app to confirm everything is working by going to :tabLink[http://localhost:8000]{href="http://localhost:8000" title="Flask App" id="app"}
+
+> [!TIP]
+> The `depends_on` field supports three conditions:
+>
+> - `service_started` — the container has been created (the default)
+> - `service_healthy` — the container's healthcheck is passing
+> - `service_completed_successfully` — the container exited with code 0 (useful for database migration init containers)