Guided project: understand and prepare the MicroBank environment

Start with the system you will keep improving

MicroBank is the polyglot banking application using simulated data that connects these learning paths. This foundations project prepares you to explain its boundaries and investigate a small runtime before the full application implementation in DevOps Foundations.

Your deliverable is a MicroBank readiness record: a source-backed system map, Linux environment inventory, access/storage observations, a read-only diagnostic, and a tested local startup/recovery runbook. You will also serve a small evidence page to retain the original file-serving, request, and Git practice. The page is explicitly a learning fixture; it does not run Accounts, Ledger, or a banking operation.

Use one disposable Ubuntu learning machine and a regular user. Complete the module labs first. Check that Bash, BusyBox with the httpd applet, curl, iproute2 (ss), and Git are available through the lessons' reviewed package workflow. This checkpoint needs no Docker, cloud account, database, Java, or Python runtime.

1. Map the versioned MicroBank application

Read the MicroBank implementation introduction and its topology before running application commands. The teaching reference is MicroBank revision f75da680251eebeb38bf17bce3e49b2fea8385c0. Record that revision in your notes; record a different selected revision and inspect its differences before using newer code.

Draw the following route as a source-derived design, then identify what later execution evidence would establish:

Open the diagram at full size.

Accounts uses FastAPI/Python; Ledger uses Spring Boot/Java; each has a PostgreSQL database. The optional React browser frontend is another component. In the pinned teaching reference, Ledger processing can complete while Accounts remains pending, because the Accounts settlement consumer is absent. A page load, an Accounts health response, and a matching Ledger entry answer different questions.

Create an inventory with component, source path, runtime, incoming/outgoing connection, storage, and verification. Inspect the reference through the linked guide or read-only source browsing. Add observed local values only after you actually run the corresponding profile. Do not invent database sizes, service accounts, ports, successful requests, or production readiness.

2. Separate the public URL from local runtime endpoints

Use https://microbank.learnwithsk.dev/ as the intended public project URL. The hostname is microbank.learnwithsk.dev; / is an HTTP path, not part of a DNS record. Public DNS and the HTTPS endpoint may be unavailable while the project is being prepared. A completed foundations record can include that observed failure.

From a terminal with the tools installed, make bounded, read-only checks:

dig +time=3 +tries=1 microbank.learnwithsk.dev A
dig +time=3 +tries=1 microbank.learnwithsk.dev AAAA
curl --connect-timeout 5 --max-time 15 --max-redirs 3 \
  --location --silent --show-error --output /dev/null \
  --write-out 'status=%{http_code} ip=%{remote_ip} final=%{url_effective}\n' \
  https://microbank.learnwithsk.dev/
printf 'curl exit status: %s\n' "$?"

Record time, resolver, query type, DNS status/answers/TTL, curl status, and final URL. If resolution fails, there is no HTTP response to report; curl's 000 output is not an HTTP status returned by a server. If a page responds, describe the content actually served. A public landing page or edge response does not establish a connection to Accounts or a working transaction.

Public URL, loopback address, container service name, and database endpoint belong to different contexts. Keep them separate in the drawing. DNS records or Cloudflare settings do not need to change for this lab. If the public URL is unavailable, use the local fixture below for the executable HTTP checks.

3. Prepare a new Linux evidence directory

Use Linux home storage for the permission and service exercises. Inspect ls -ld ~/microbank-foundations; if that name exists, select another unused name consistently instead of replacing it. For a new directory:

mkdir -p ~/microbank-foundations/public ~/microbank-foundations/notes
cd ~/microbank-foundations
printf '# MicroBank foundations readiness\n' > README.md
cat > public/index.html <<'EOF'
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>MicroBank foundations evidence</title>
<h1>MicroBank foundations learning fixture</h1>
<p>Static evidence page. No bank API or transaction processing.</p>
<p>Project URL: https://microbank.learnwithsk.dev/</p>
</html>
EOF

Keep the following records under notes/, using results from completed module labs:

These filenames describe work to complete, not pre-existing evidence. Only the public/ directory is served; notes and Git metadata stay outside it. This practice directory is separate from the application and infrastructure checkouts.

4. Start, diagnose, and recover the local fixture

In Linux terminal A, inspect ss -lnt and confirm that loopback port 8765 is unused. If occupied, choose another unused port consistently throughout the fixture and diagnostic. Do not stop an unrelated listener. Then:

cd ~/microbank-foundations
busybox httpd -f -p 127.0.0.1:8765 -h "$PWD/public"

In Linux terminal B, inspect ss -lnt, request http://127.0.0.1:8765/ with bounded curl options, and verify the expected MicroBank foundations learning fixture marker. Request /missing and compare the HTTP error with a connection failure after stopping terminal A using Ctrl-C. Restart the same command and repeat the original successful check. Record actual statuses and observations.

Keep both terminals in the same machine: their loopback address refers to that Linux network context. Browser access from the Mac is optional and follows the OrbStack networking documentation↗. Do not change the bind to all interfaces just to make a browser result appear.

For the service-management extension, first confirm the resolved BusyBox path is /usr/bin/busybox and the user manager works. Stop the manual server, check that ~/.config/systemd/user/learnwithsk-microbank-evidence.service is unused, and create a new complete user unit there:

[Unit]
Description=MicroBank foundations static evidence fixture

[Service]
Type=exec
ExecStart=/usr/bin/busybox httpd -f -p 127.0.0.1:8765 -h %h/microbank-foundations/public
Restart=on-failure
RestartSec=5

If the executable, directory, or port differs, adapt the unit to the values you inspected. Use systemctl --user daemon-reload, start only learnwithsk-microbank-evidence.service, and inspect its status/journal. Then request the expected page. Stop/start the named unit and repeat that request. Boot enablement is optional and depends on the user-session lifecycle. This unit supervises the static fixture, not MicroBank application services.

5. Add a bounded, read-only diagnostic

Save this as check-foundations.sh in the new project directory. It checks the local fixture at the chosen port; if you selected another port, change the URL here consistently. It does not call the public hostname or submit a transaction.

#!/usr/bin/env bash
if [[ $# -ne 1 ]]; then
  printf 'Usage: %s PROJECT_DIRECTORY\n' "$0" >&2
  exit 2
fi
study_project=$1
if [[ ! -d "$study_project" ]]; then
  printf 'Missing project directory\n' >&2
  exit 1
fi
for study_tool in ls df du ss curl; do
  if ! command -v "$study_tool" >/dev/null 2>&1; then
    printf 'Missing tool: %s\n' "$study_tool" >&2
    exit 1
  fi
done
for study_file in README.md public/index.html notes/system-map.md \
  notes/environment.md notes/access-storage.md notes/network.md notes/runbook.md; do
  if [[ ! -f "$study_project/$study_file" || ! -r "$study_project/$study_file" ]]; then
    printf 'Missing or unreadable evidence: %s\n' "$study_file" >&2
    exit 1
  fi
done
ls -ld -- "$study_project" "$study_project/public" || exit 1
df -h -- "$study_project" || exit 1
du -sh -- "$study_project" || exit 1
ss -lnt || exit 1
if ! study_page=$(curl --noproxy '*' --fail --silent --show-error \
  --connect-timeout 2 --max-time 3 http://127.0.0.1:8765/); then
  printf 'Local evidence-page request failed\n' >&2
  exit 1
fi
if [[ "$study_page" != *'MicroBank foundations learning fixture'* ]]; then
  printf 'Expected fixture marker is missing\n' >&2
  exit 1
fi
printf 'Local foundations fixture checks passed; MicroBank transaction untested.\n'

Run bash -n check-foundations.sh, then bash check-foundations.sh "$HOME/microbank-foundations" and capture its status immediately. Run ShellCheck if available. Test missing arguments (2), a missing directory (1), a stopped fixture (1), a response with a missing marker (1), and the complete expected fixture (0). Use only this disposable page for the marker change and restore it afterwards. Record a deliberate regression and its repair as taught in the shell lab.

A 0 result confirms the required local files were readable and the fixed local URL returned its expected marker at that moment. It does not parse the notes for correctness, establish the identity of the responding process, inspect Accounts/Ledger, or prove a deposit succeeded. Pair the diagnostic with the listener/process observations and review the notes yourself.

6. Review one change and one recovery

After confirming this is the new practice directory, use the taught local-author setup and initialize a Git repository here. Inspect and stage only the intended sanitized evidence, page, and script. Make a baseline commit, review a small runbook improvement on a practice branch, and integrate it locally.

For recovery practice, commit a clearly labelled wrong statement in the disposable runbook, inspect that commit, and reverse it using the earlier git revert sequence. Check the corrected text and rerun the fixture diagnostic. A Git revert restores source content through a new commit; it does not undo database or infrastructure changes.

Repository ownership for later real work is explicit: MicroBank↗ owns application code and tests; Ship Boring Lab↗ owns IaC, Ansible configuration/bootstrap, GitOps, and Backstage configuration. LearnWithSK owns curriculum. Adopt relevant configuration into the owning repository deliberately; this foundations lab neither migrates state nor deploys a platform.

Connect every module to the readiness record

Checkpoint, cleanup, and next path

Show the system map, completed evidence records, local fixture page, diagnostic test results, reviewed Git change, and startup/recovery runbook. Include at least three short entries based on completed labs. State which items are observed, source-derived, proposed, or pending. Completion is self-reported; documentation review is not Linux execution verification.

Stop the manual server with Ctrl-C or stop the named user unit. If retiring the unit, remove only its course-owned file and reload user units. Retain the project evidence; clean up only the identified disposable fixtures. A personal blog or portfolio remains an optional place to publish sanitized learning entries.

Continue to Cloud Foundations to develop the operating design, then DevOps Foundations for the full local MicroBank implementation and transaction checks.

Sources

Pinned MicroBank source↗; versioned implementation guide; BusyBox HTTP server↗; curl↗; systemd service semantics↗; Git basics↗.