Creating a Reusable Lab Repository with Documentation and Checklists

Hello—welcome to the first week of the lab. This course is designed to turn DevOps knowledge into repeatable operational habits: you will build, run, break, repair, and document a small application environment many times. The first habit is deceptively important: make the work easy to restart without relying on memory.

In this lesson, you will create the repository that will hold the entire four-week project. It will contain three operational aids:

• a README that tells a future engineer what this lab is and how to begin;
• a command log that records meaningful actions and observations;
• setup and teardown checklists that externalize the steps needed to start and safely clean up a lab session.

Treat these files as part of the system, not as paperwork added afterwards. In real operations, clear documentation reduces recovery time and makes changes safer.

---

The operating principle: make the repository remember for you

Working memory is a poor place to store operational procedure. Even experienced engineers forget a one-off environment variable, the exact cleanup command, or the reason a workaround was used. Under time pressure, those small omissions compound.

Your repository will become an external memory system:

Artifact	Question it answers	When you update it
README.md	“What is this project, and how do I use it?”	When the stable workflow changes
docs/command-log.md	“What did I actually run, observe, and decide?”	During or immediately after a work session
checklists/setup.md	“What must be true before I begin?”	When setup gains a new required step
checklists/teardown.md	“How do I leave this lab safely?”	When you create a resource that needs cleanup

A useful distinction:

• A README describes the normal, current workflow.
• A checklist is followed during an operation and checked off only after verification.
• A command log records evidence from a particular session: commands, results, failures, and decisions.

The task-list interface shown below is how GitHub renders Markdown checkboxes. The same Markdown files also work locally in VS Code and other editors.

For this course, a checklist is not a vague to-do list such as “set up Docker.” A useful checklist item names an action and, where possible, a verification condition: “Run docker version and confirm both Client and Server information are displayed.”

---

Build the repository skeleton

Use a Bash-compatible terminal for the commands below: macOS Terminal, Linux shell, Git Bash, or WSL are all suitable. If you use Windows PowerShell instead, create the same folders and files through VS Code’s Explorer; the layout matters more than the exact creation command.

Choose a parent directory where you keep practice projects, then create the lab:

mkdir devops-practice-lab
cd devops-practice-lab

git init

mkdir -p app checklists docs infra k8s scripts .github/workflows

touch README.md .gitignore
touch docs/command-log.md
touch checklists/setup.md checklists/teardown.md
touch app/.gitkeep scripts/.gitkeep infra/.gitkeep k8s/.gitkeep
touch .github/workflows/.gitkeep

git status --short

The .gitkeep files are intentional placeholders. Git tracks files, not empty directories; these placeholders preserve the planned layout until later lessons add application, Terraform, Kubernetes, script, and CI files.

Your layout should now be:

devops-practice-lab/
├── .github/
│   └── workflows/
├── app/
├── checklists/
│   ├── setup.md
│   └── teardown.md
├── docs/
│   └── command-log.md
├── infra/
├── k8s/
├── scripts/
├── .gitignore
└── README.md

This is deliberately a little larger than today’s needs. The value is predictability: each later tool has an obvious home, rather than creating ad hoc folders while you are troubleshooting.

Add this initial .gitignore content:

# Local environment values and secrets
.env
.env.*
!.env.example

# Machine-generated files
.DS_Store
*.log

Do not add docs/command-log.md to .gitignore. The command log is deliberately versioned because it is part of the lab’s operational record. Never place passwords, API tokens, private keys, full .env file contents, or sensitive production-like data in it.

---

Write a README that enables a clean start

A README’s real job is to lower the cost of joining or returning to a repository. That includes future-you after a distracting week, not only a new teammate.

The application does not exist yet, so resist the temptation to write imaginary commands. Good documentation is honest about the repository’s current state and becomes more specific as the lab grows.

Open README.md and add this starting version. Replace <your-repository-url> only after you create a remote repository; it is fine to leave it as a placeholder today.

# DevOps Practice Lab

## Overview

A repeatable local DevOps lab for practising container workflows,
infrastructure as code, Kubernetes deployment, CI/CD, and incident recovery.

This repository is designed to be rebuilt from a clean clone using its own
documentation and checklists.

## Built with

- Git
- Markdown
- A Bash-compatible shell
- Docker, Terraform, kind, Kubernetes, and GitHub Actions will be added during the lab

## Repository layout

| Path | Purpose |
|---|---|
| `app/` | Sample application source and Dockerfile |
| `checklists/` | Repeatable setup and teardown procedures |
| `docs/` | Command log and operational notes |
| `infra/` | Terraform configuration |
| `k8s/` | Kubernetes manifests |
| `scripts/` | Automation and preflight scripts |
| `.github/workflows/` | GitHub Actions workflows |

## Getting started

### Prerequisites for the current stage

- Git
- A Bash-compatible terminal
- A text editor, such as VS Code

### Start a lab session

1. Clone the repository:

   ```bash
   git clone <your-repository-url> devops-practice-lab
   cd devops-practice-lab

2. Read checklists/setup.md and complete the applicable items.
3. Record meaningful commands and observations in docs/command-log.md.
4. Before ending the session, complete checklists/teardown.md.

Usage

The repository currently contains the documentation framework for the lab.
Later lessons will add a containerized application, Terraform configuration,
Kubernetes manifests, and CI/CD workflows.

Working rules

• Make one small, verifiable change at a time.
• Record commands that change state, diagnose failures, or reveal useful evidence.
• Never commit secrets or machine-specific credentials.
• Update a checklist when a new recurring setup or cleanup step is discovered.

Contributing

Use Git branches for tracked changes and verify the documented workflow after
meaningful changes. The branching and recovery workflow will be introduced in
the next lesson.

A few design choices matter here:

1. **The purpose is explicit.** The README says this is a repeatable practice lab, not merely “a Docker project.”
2. **The repository map prevents searching.** When you return later, you will know where a Terraform file or Kubernetes manifest belongs.
3. **Prerequisites are scoped to today.** Docker is mentioned as upcoming, but not falsely required before it is used.
4. **The workflow points to checklists and logs.** Documentation should direct action, not merely describe intent.

```video
resource_id="bf3e8"
sections="1"
---
Watch “How To Write a USEFUL README On Github” by Learn Fast Make Things for a compact walkthrough of README structure and the difference between information for users and contributors.
---
Watch <ts start="00:04:01" end="00:08:27">the README structure</ts>. Compare its installation and contribution sections with your lab README. For this repository, prioritize clear setup and recovery over promotional material, badges, or screenshots.

---

Create a command log that captures evidence, not noise

A terminal history is useful but unreliable as a record: it is machine-specific, may disappear, and rarely explains why a command was run. Your command log should be brief enough to maintain, but specific enough to help you reproduce a successful run or investigate a failure.

Add the following to docs/command-log.md:

# Command Log

This file records meaningful lab commands, observations, failures, and recovery
steps. It is not a complete terminal transcript.

## Logging rules

- Record commands that create, change, inspect, or remove resources.
- Record the result or evidence that matters.
- Record failures and the eventual fix.
- Redact secrets, tokens, passwords, and private URLs.
- Use a new session heading each time you work.

## Session template

### YYYY-MM-DD — short session goal

**Goal:** State one concrete outcome.

| Time | Command or action | Result / evidence | Notes |
|---|---|---|---|
| HH:MM | `command here` | What happened | Decision, failure, or follow-up |

**End state:** What is working, what remains, and the next safe action.

## YYYY-MM-DD — Initialize repository documentation

**Goal:** Create the reusable lab repository structure and operational documents.

| Time | Command or action | Result / evidence | Notes |
|---|---|---|---|
| HH:MM | `git init` | Git repository initialized | Baseline repository created |
| HH:MM | Created README, checklists, and command log | Required documentation files exist | First operational documentation version |
| HH:MM | `git status --short` | Review before first commit | No secrets should be staged |

**End state:** Repository documentation framework is ready for the next lesson.

Replace the date and times with your real session date and approximate times. You do not need to log every ls, typo, or editor action. Log the events that another person would need to understand the state of the lab.

For example, these are worth recording later:

• docker build with the resulting image tag;
• a failed container startup and the relevant error from docker logs;
• terraform plan and whether its planned changes matched your prediction;
• a kubectl rollout undo performed during recovery;
• the exact command that removed a project resource during teardown.

A log entry such as “Docker failed” has little diagnostic value. Prefer evidence:

docker logs devops-lab-app showed PORT must be set; container was recreated with -e PORT=8080.

That style preserves the symptom, the evidence, and the remediation.

---

Turn setup and teardown into safe procedures

Checklists should be specific, bounded, and updated by experience. They should not silently contain global destructive actions such as docker system prune -a, because that can remove unrelated work on your machine.

Start with a small setup checklist in checklists/setup.md:

# Setup Checklist

Use this checklist at the beginning of each lab session. Mark an item complete
only after you have performed and verified it.

## Repository

- [ ] Open the repository root in a terminal.
- [ ] Run `git status` and review uncommitted changes before starting work.
- [ ] Read the current "Getting started" section in `README.md`.
- [ ] Review the most recent entry in `docs/command-log.md`.
- [ ] State one session goal in a new command-log heading.

## Current-stage verification

- [ ] Confirm the required documentation files exist:
  `README.md`, `docs/command-log.md`, `checklists/setup.md`, and
  `checklists/teardown.md`.
- [ ] Confirm no secrets or local `.env` files are staged with `git status`.

## Ready to work

- [ ] Record any missing setup step discovered during this session in this checklist.

Then create checklists/teardown.md:

# Teardown Checklist

Use this checklist before ending a lab session. Mark an item complete only after
you have performed and verified it.

## Preserve evidence

- [ ] Add meaningful commands, results, failures, and decisions to
  `docs/command-log.md`.
- [ ] Record the session end state and the next safe action in the command log.
- [ ] Run `git status` and review all changed or untracked files.
- [ ] Confirm that no secrets, credentials, or local `.env` files are staged.

## Clean up project resources

- [ ] Review the project resource ledger below.
- [ ] Run only the cleanup commands listed for resources created by this lab.
- [ ] Verify that each removed resource is no longer present.
- [ ] Record cleanup evidence in the command log.

## Resource ledger

| Resource | Created in lesson | Cleanup command | Verification |
|---|---|---|---|
| No runtime resources yet | — | Not applicable | Not applicable |

## Leave a recoverable workspace

- [ ] Save documentation updates.
- [ ] Commit or deliberately preserve work according to the current task.
- [ ] Note any incomplete work and its safe restart point.

The resource ledger is empty today. In later lessons, you will add project-scoped resources and their exact cleanup commands. For example, when you create a container, the ledger might identify its fixed name, such as devops-lab-app, rather than giving a broad instruction to remove every container on your machine.

Use a short execution rhythm during lab sessions:

1. Open setup.md and the command log before opening lots of terminals.
2. Choose one concrete outcome for the session.
3. Complete one small operation.
4. Record evidence immediately if the operation changed state, failed, or taught you something.
5. End with the teardown checklist even if the session was incomplete.

This reduces context switching. It also creates a reliable restart point when attention is interrupted.

---

Validate and save your baseline

Before committing, inspect the repository and verify the documentation is internally consistent:

git status --short
git diff --check
find checklists docs app infra k8s scripts .github -type f | sort

git diff --check looks for whitespace problems that can make Markdown and configuration changes unnecessarily messy. The find command confirms that the intended files exist; it is not a substitute for reading them.

Now perform a clean-read test:

1. Read the README from the top without referring to this lesson.
2. Locate the setup checklist from the README.
3. Find where you would record a failed command.
4. Locate the teardown procedure.
5. Confirm the README does not claim that an application, Docker image, or Kubernetes cluster already exists.

If you can answer all five quickly, the repository is navigable.

When satisfied, create the baseline commit:

git add README.md .gitignore docs checklists app scripts infra k8s .github
git status
git commit -m "chore: initialize repeatable lab"

If Git reports that your name or email is not configured, configure your Git identity according to your normal account and rerun the commit. Verify the commit exists:

git log --oneline -1
git status

A clean working tree is a useful ending signal: you have preserved the current known-good state.

---

Key takeaways

You now have the first version of a reusable DevOps lab repository:

• README.md provides a truthful map, prerequisites, workflow, and working rules.
• docs/command-log.md records operational evidence rather than an unfiltered terminal transcript.
• Setup and teardown checklists turn recurring procedure into verifiable actions.
• The teardown checklist is deliberately project-scoped, protecting unrelated local resources.
• The initial commit gives later work a known baseline to return to.

In the next lesson, you will make a tracked change using a Git branch, focused commits, a merge, and a safe revert. That workflow will use the documentation structure you created today: the README will state the rule, the command log will preserve evidence, and the checklists will help you leave the repository in a recoverable state.