Choose where you will work

Start with My Laptop if you can. No school machine is required or supplied. Both routes do the same labs and have the same maximum grade. Hades is an optional reference to watch, never a student login.

Open TD0 · Return to the Lab Portal

My Laptop — recommended

Open a terminal on your own computer. Docker runs locally, and your browser reaches http://127.0.0.1:8080 when the lab starts its web container.

In your chosen terminal, check one command at a time:

git --version
python3 --version
docker version
docker compose version
docker buildx version

Docker must show both Client and Server. A Client-only result means the engine is not reachable. On Desktop, check the app is running; on Linux, ask for help with the service and account permissions. Do not make the Docker socket world-writable.

My Own Cloud — optional

Your laptop connects to your own Ubuntu server by SSH; Docker runs on that server. You own the account, access and bill. Use Ubuntu 24.04 x86_64 with at least 2 vCPU, 4 GiB RAM and 40 GiB disk; 80 GiB disk is more comfortable. This is a planning baseline, not a tested guarantee for every provider.

1. Choose a compatible VPS, create your own login and SSH key, and verify its fingerprint using the provider's trusted console.
2. Use the Ubuntu setup checklist to install Docker on the server. The provider comparison is optional background, not another assignment.
3. SSH into the server and keep your project folder there. Run the same lab commands in that SSH terminal.
4. When a lab starts its web service, leave a second laptop terminal open with an SSH tunnel. Enter your own values when asked:

read -r -p 'Your server address: ' LAB_HOST
read -r -p 'Your server login: ' LAB_USER
ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:8080:127.0.0.1:8080 "$LAB_USER@$LAB_HOST"

Use your configured SSH key, adding -i with its path if necessary. Open http://127.0.0.1:8080 in the laptop browser. The tunnel forwards to server loopback; it does not start the application. Close it with Ctrl+C after the exercise.

Keep application and database ports private. Do not open 8080 or 5432 publicly to work around a tunnel error. Restrict inbound SSH in the provider firewall where practical. Stopping a VM does not necessarily end its charges.

Command-line tools used in the labs

On Ubuntu 24.04 (local, WSL, or your own server), install missing utilities once:

sudo apt update
sudo apt install -y git python3 python3-venv curl jq gh coreutils util-linux

On macOS, after installing Homebrew, use its Bash and GNU utilities for the same commands. The deployment scripts use flock and GNU file utilities; the built-in macOS Bash is too old for some shell expansions.

brew install bash python@3.12 git jq gh coreutils flock
export PATH="$(brew --prefix coreutils)/libexec/gnubin:$(brew --prefix python@3.12)/libexec/bin:$(brew --prefix)/bin:$PATH"
"$(brew --prefix)/bin/bash"

Keep this Bash terminal for the lab. Check bash --version, python3 --version, jq --version, sha256sum --version, and command -v flock. The application lock is for Python 3.12. Before TD6, run gh auth login in your own terminal and verify with gh auth status; do not record its authentication material. GHCR authentication is a separate boundary explained in TD2.

Homebrew coreutils · Homebrew flock · GitHub CLI authentication. These installation instructions do not constitute a completed macOS/WSL runtime replay.

Confirm the Docker host before any lab

Run this in the terminal where you will type Docker commands: your laptop terminal for My Laptop, or your SSH terminal for My Own Cloud. The course expects the daemon on that machine. Docker Desktop’s local Linux VM is valid; an SSH/TCP Docker endpoint is not this course’s route.

(
  set -eu
  if [ -n "${DOCKER_HOST:-}" ] || [ -n "${DOCKER_CONTEXT:-}" ]; then
    echo 'STOP: a Docker environment override is active. Ask for help before continuing.'
    exit 1
  fi
  course_context="$(docker context show)"
  course_endpoint="$(docker context inspect "$course_context" --format '{{.Endpoints.docker.Host}}')"
  printf 'Context: %s\nEndpoint: %s\n' "$course_context" "$course_endpoint"
  case "$course_endpoint" in
    unix://*) ;;
    *) echo 'STOP: select the local Linux engine or Docker Desktop Linux engine context.'; exit 1 ;;
  esac
  docker info --format 'Server: {{.Name}} / {{.OSType}}'
  test "$(docker info --format '{{.OSType}}')" = linux
)

Continue only if this finishes successfully and names the engine you intended. Desktop may show desktop-linux or default through WSL integration, both with a local Unix socket. Linux usually shows default; a rootless local Unix socket is also valid. If the endpoint or server is unexpected, stop before creating or removing anything. Do not change context or overrides blindly: ask on Discord remotely, or Badr on campus. Repeat this check when you change terminals or Docker settings.

Start your own project

Download the project starter. Extract it into a folder you own, outside the course ZIP viewer. Open project_starter in VS Code and Bash. The supplied app and tests are ready; the Dockerfile, Compose and workflow contain marked tasks for you to complete across the labs. An incomplete task is not a pass.

For My Laptop, work in this local folder. For Remote / Cloud, copy the starter to your own server using SFTP, SSH there and open its project folder. Do not copy credentials or an existing secret file into the course distribution.

pwd
test -f Dockerfile && test -f scripts/course-env.sh
. scripts/course-env.sh
git init -b coursework
read -r -p 'Your commit name: ' COMMIT_NAME
read -r -p 'Your commit email: ' COMMIT_EMAIL
git config user.name "$COMMIT_NAME"
git config user.email "$COMMIT_EMAIL"
git status --short

If this folder already has a Git history, retain it and skip git init. Inspect .gitignore before your first commit. Add the supplied source and scaffold files, not credentials, .env, backups or evidence containing private data. Then commit your starting point. TD1 needs no GitHub invitation or registry access.

Before TD2, create a private empty GitHub repository, copy its SSH or HTTPS clone URL, and use git remote add origin YOUR_REPOSITORY_URL then git push -u origin HEAD. If origin exists, inspect it with git remote -v first. Never put a token in a URL. Share your repository with Badr and your partner. GitHub Classroom is optional.

Continue to TD1. Use the task steps and collect your own observations.

If your laptop cannot run Docker

Ask on Discord remotely or Badr on campus. Codespaces can be a secondary fallback, but it is not another assignment or an additional environment button. Its dev container must provide a working Docker daemon and Compose; its private port forwarding and volume persistence differ from a normal VPS. See the secondary reference before consuming an allowance. Full Desktop/ARM/Codespaces runtime acceptance has not been established by a documentation check.

Ready

Start TD0 — make Docker work. If something fails, send only the exact command, exact error, and My Laptop / My Own Cloud (plus your operating system when useful). Never send a password, token or private key.