ubuntu@web01:~$ whoami
ubuntu
ubuntu@web01:~$ pwd
/home/ubuntu

pwd                 # print working directory: where am I?
ls -la              # list everything here, including hidden files
cd /var/log         # change directory
cd ..               # go up one level
cd ~                # go home, from anywhere

ls /etc > /dev/null
echo $?          # 0  -> it worked

ls /nonexistent > /dev/null 2>&1
echo $?          # 2  -> it failed

man ls              # the full manual for 'ls' (press q to quit)
ls --help           # a quick summary
which python3       # where does this command live?
history             # everything you have typed

ls -l deploy.sh
-rwxr-xr-x 1 ubuntu ubuntu 412 Sep 20 19:19 deploy.sh
#│└┬┘└┬┘└┬┘
#│ │  │  └── others: r-x (read + execute)
#│ │  └───── group:  r-x
#│ └──────── owner:  rwx (read, write, execute)
#└────────── file type: - = file, d = directory, l = symlink

chmod +x deploy.sh      # add execute permission
./deploy.sh             # run it (./ means 'in this directory')

cp source.txt backup.txt        # copy
mv old.txt new.txt              # move OR rename
mkdir -p projects/autoclass      # create a directory (and parents)
rm file.txt                     # delete a file
rm -r directory/                # delete a directory and contents

git init                        # start tracking this folder
git status                      # what has changed?
git add deploy.sh               # stage one file
git add .                       # stage everything changed
git commit -m "Add deploy script"   # record the snapshot

git log --oneline               # one line per commit
git log --oneline -5            # the last five
git show HEAD                   # exactly what changed last time
git diff                        # what have I changed but not staged?

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git branch                      # list branches
git switch -c feature/new-tiles  # create AND switch to a new branch
git switch main                 # go back to the main line
git merge feature/new-tiles     # bring the branch's work into main
git branch -d feature/new-tiles  # delete it once merged

git switch main
git switch -c fix/map-tiles
git add app.js
git commit -m "Switch map tiles to a keyless provider"
git switch main
git merge fix/map-tiles

<<<<<<< HEAD
referrer-policy: no-referrer
=======
referrer-policy: strict-origin-when-cross-origin
>>>>>>> fix/map-tiles

git remote add origin git@github.com:you/project.git
git push -u origin main         # upload your commits
git pull                        # download others' commits
git clone <url>                 # copy an entire project down

ssh-keygen -t ed25519 -C "you@example.com"
cat ~/.ssh/id_ed25519.pub    # paste this into GitHub > Settings > SSH keys

git reflog
git switch -c recovered-work HEAD@{3}    # jump back to that state

git log --oneline
git status          # should say: nothing to commit, working tree clean
git branch          # your work is on main

cat /etc/hostname          # a config file
ls /var/log/               # log files
df -h                      # disk usage (reads filesystem stats)

# How many failed logins today?
grep "Failed password" /var/log/auth.log | wc -l

# Which processes use the most memory?
ps aux --sort=-%mem | head -5

# Which IPs hit us most in the last 1000 lines of the web log?
tail -1000 /var/log/nginx/access.log | awk '{print $1}' | sort | uniq -c | sort -rn | head

command > file      # send output to a file (overwrite)
command >> file     # append to a file
command 2> errors.log   # capture only errors
command > out.log 2>&1  # capture both output and errors

ps aux                  # every process, with user and resource use
top                     # live view (press q to quit)
pgrep -af python        # find python processes
kill 12345              # ask PID 12345 to stop
kill -9 12345           # force it (last resort)

systemctl status app-gateway      # is it running? recent logs?
systemctl restart app-gateway     # restart it
systemctl stop edge-tunnel    # stop it
systemctl start edge-tunnel   # start it
systemctl enable edge-tunnel  # start automatically at boot
systemctl is-active app-gateway   # just the state: active/inactive

[Unit]
Description=Edge tunnel connector
After=network-online.target

[Service]
ExecStart=/usr/bin/edge-tunnel run
Restart=always
User=ubuntu

[Install]
WantedBy=multi-user.target

systemctl --user status app-gateway
loginctl show-user ubuntu | grep Linger

journalctl -u app-gateway -n 50       # last 50 lines for a service
journalctl -u app-gateway --since "1 hour ago"
journalctl -u app-gateway -f          # follow live (Ctrl-C to stop)
journalctl -p err -n 30                  # only errors
tail -f /var/log/syslog                  # follow a file live

$ systemctl status app-gateway
● app-gateway.service - Application Gateway
     Active: failed (Result: exit-code)
    Process: 4123 ExecStart=/usr/bin/app-gateway (code=exited, status=1)

$ journalctl -u app-gateway -n 20
... ERROR config.yaml: invalid YAML at line 42: mapping values not allowed
... gateway exited with status 1

sudo systemctl restart nginx      # run one command as root
sudo -i                           # open a root shell (avoid casually)
whoami                            # confirm who you are now

chown ubuntu:ubuntu /var/www/site    # change owner and group
chmod 644 file.txt                   # owner writes, everyone reads
chmod 600 secret.key                 # owner only — for keys and secrets
chmod 755 script.sh                  # executable by all
chmod 700 private-dir/               # only owner may enter

ss -ltnp                    # what is listening, on which port
ss -ltnp | grep :443        # is anything serving HTTPS?
curl -s localhost:8080/health   # is that local service alive?

dig example.com +short              # what address does this name resolve to?
dig example.com CNAME +short        # is it an alias?
getent hosts example.com            # system resolver view
cat /etc/resolv.conf                # which DNS servers am I using?

curl -I https://example.com               # headers only
curl -s -o /dev/null -w "%{http_code}\n" https://example.com
curl -s https://api.example.com/data | head -c 300

#!/usr/bin/env bash
# backup-notes.sh - copy my notes somewhere safe
set -euo pipefail

SOURCE="/home/ubuntu/notes"
DEST="/home/ubuntu/backups"
STAMP=$(date +%Y%m%d-%H%M%S)

mkdir -p "$DEST"
tar -czf "$DEST/notes-$STAMP.tar.gz" "$SOURCE"
echo "Backup written: $DEST/notes-$STAMP.tar.gz"

#!/usr/bin/env bash
set -euo pipefail

TARGET="${1:?usage: $0 <directory>}"      # fail if no argument given

if [[ ! -d "$TARGET" ]]; then
  echo "Not a directory: $TARGET" >&2
  exit 1
fi

COUNT=0
for f in "$TARGET"/*; do
  [[ -e "$f" ]] || continue
  COUNT=$((COUNT + 1))
done

echo "$COUNT files in $TARGET"

grep "ERROR" app.log                  # lines containing ERROR
grep -i error app.log                 # case-insensitive
grep -c "Failed" auth.log             # count matches
grep -v "DEBUG" app.log               # lines NOT matching
grep -E "error|fail|critical" app.log # extended regex, several patterns

sed 's/old/new/' file.txt          # replace first occurrence per line
sed 's/old/new/g' file.txt         # replace all
sed -n '10,20p' file.txt           # print lines 10-20
sed -i.bak 's/localhost/127.0.0.1/' config.yaml   # edit in place, keep a backup

# Top 5 client IPs in an nginx log
awk '{print $1}' access.log | sort | uniq -c | sort -rn | head -5

# Sum a numeric column
awk '{sum += $5} END {print sum}' data.txt

curl -s https://api.example.com/items | jq '.'
curl -s https://api.example.com/items | jq '.[] | .name'
curl -s https://api.example.com/items | jq -r '.[] | select(.status=="active") | .id'
jq '.database.host' config.json
jq -r '.items[] | "\(.id) \(.name)"' data.json

┌── minute (0-59)
│ ┌── hour (0-23)
│ │ ┌── day of month (1-31)
│ │ │ ┌── month (1-12)
│ │ │ │ ┌── day of week (0-6, Sun=0)
│ │ │ │ │
0 7 * * *   /home/ubuntu/scripts/morning-report.sh
*/15 * * * * /home/ubuntu/scripts/health-check.sh
0 2 * * 0   /home/ubuntu/scripts/weekly-backup.sh

crontab -l          # list my scheduled jobs
crontab -e          # edit them

*/15 * * * * /usr/bin/flock -n /tmp/health.lock /home/ubuntu/scripts/health-check.sh >> /home/ubuntu/logs/health.log 2>&1

[Unit]
Description=Daily backup

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

#!/usr/bin/env bash
# nightly-backup.sh - archive a directory and record the result
set -euo pipefail

SOURCE="${1:?usage: nightly-backup.sh <directory>}"
DEST="/home/ubuntu/backups"
LOG="/home/ubuntu/logs/nightly-backup.log"
STAMP=$(date +%Y%m%d-%H%M%S)

log() { echo "$(date -Is) $*" | tee -a "$LOG"; }

if [[ ! -d "$SOURCE" ]]; then
  log "FAIL source not found: $SOURCE"; exit 1
fi

mkdir -p "$DEST" "$(dirname "$LOG")"
ARCHIVE="$DEST/$(basename "$SOURCE")-$STAMP.tar.gz"

log "START backing up $SOURCE"
if tar -czf "$ARCHIVE" "$SOURCE"; then
  SIZE=$(du -h "$ARCHIVE" | cut -f1)
  log "OK archive=$ARCHIVE size=$SIZE"
else
  log "FAIL tar exited $?"; exit 1
fi

# keep only the 7 most recent archives
ls -1t "$DEST"/*.tar.gz 2>/dev/null | tail -n +8 | xargs -r rm --
log "DONE retention applied, $(ls -1 "$DEST"/*.tar.gz 2>/dev/null | wc -l) archives kept"

0 2 * * * /usr/bin/flock -n /tmp/nightly-backup.lock /home/ubuntu/scripts/nightly-backup.sh /srv/www/demo-site >> /home/ubuntu/logs/nightly-backup-cron.log 2>&1

# Did it run last night?
tail -5 /home/ubuntu/logs/nightly-backup.log

# Is the archive real and complete?
tar -tzf /home/ubuntu/backups/demo-site-*.tar.gz | head

# Would I know if it stopped? (the monitor)
find /home/ubuntu/backups -name '*.tar.gz' -mtime +1 | wc -l   # should be 0

python3 --version
python3 -c "print('hello')"      # run a one-liner
python3 script.py                # run a file

service = "app-gateway"    # str
port = 8081                     # int
cpu_load = 0.42                 # float
is_healthy = True               # bool
hosts = ["web1", "web2"]        # list
config = {"host": "localhost", "port": 8081}   # dict

name = "gateway"
port = 8081
print(f"{name} is listening on port {port}")
print(f"load: {cpu_load:.0%}")      # format as a percentage

if port == 8081:
    print("gateway")
elif port == 443:
    print("https")
else:
    print("unknown port")

for host in hosts:
    print(f"checking {host}")

for i in range(3):
    print(f"attempt {i + 1}")

while not is_healthy:
    is_healthy = check_health()     # careful: needs an exit condition

def check_service(name, port, timeout=5):
    """Return True if a TCP port on localhost is accepting connections."""
    import socket
    with socket.socket() as s:
        s.settimeout(timeout)
        try:
            s.connect(("127.0.0.1", port))
            return True
        except OSError:
            return False

if check_service("gateway", 8081):
    print("gateway is up")
else:
    print("gateway is DOWN")

def classify(load):
    if load > 0.9:
        return "critical"
    if load > 0.7:
        return "warning"
    return "ok"          # the default case, last

# Bad: fetching, deciding and printing all mixed together
def check():
    r = requests.get(URL)
    if r.json()["status"] == "ok":
        print("API OK")

# Good: separate steps, each independently testable
def fetch(url): ...
def is_healthy(payload): ...
def report(result): ...

import json, sys

def load_config(path):
    try:
        with open(path) as f:
            return json.load(f)
    except FileNotFoundError:
        print(f"config missing: {path}", file=sys.stderr)
        return None
    except json.JSONDecodeError as e:
        print(f"config is not valid JSON: {e}", file=sys.stderr)
        return None

# BAD: an unparseable answer silently becomes 'keep everything'
keep = decide(item).get("keep", True)

# GOOD: if we cannot tell, say so and let the caller decide
result = decide(item)
if result.status == "unknown":
    log.warning("decision unknown for %s; escalating", item.id)
    raise DecisionUnknown(item.id)

lock = acquire_lock()
try:
    do_work()
finally:
    release_lock()        # runs whether or not do_work() raised

# Better, when the resource supports it:
with open("data.json") as f:
    data = json.load(f)   # file closes automatically, even on error

import json
from pathlib import Path

# read
data = json.loads(Path("state.json").read_text())

# write atomically: a crash mid-write must not corrupt the original
tmp = Path("state.json.tmp")
tmp.write_text(json.dumps(data, indent=2))
tmp.replace("state.json")

import os, requests

TOKEN = os.environ["CF_API_TOKEN"]      # never hard-code secrets
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

resp = requests.get(
    "https://api.cloudflare.com/client/v4/user/tokens/verify",
    headers=HEADERS,
    timeout=15,                          # ALWAYS set a timeout
)
resp.raise_for_status()                  # turn 4xx/5xx into an exception
payload = resp.json()
if not payload.get("success"):
    raise RuntimeError(f"API refused: {payload.get('errors')}")

import time

def get_with_retry(url, tries=3, **kw):
    for attempt in range(tries):
        try:
            r = requests.get(url, timeout=15, **kw)
            if r.status_code in (429, 500, 502, 503, 504):
                raise requests.HTTPError(f"transient {r.status_code}")
            r.raise_for_status()
            return r
        except requests.RequestException as e:
            if attempt == tries - 1:
                raise
            wait = 2 ** attempt            # 1, 2, 4 seconds
            log.warning("attempt %s failed (%s); retrying in %ss", attempt + 1, e, wait)
            time.sleep(wait)

python3 -m venv .venv             # create the environment
source .venv/bin/activate        # enter it (prompt changes)
pip install requests             # installs only here
pip freeze > requirements.txt    # record exact versions
deactivate                       # leave it

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt   # exact same versions, every time

import json                       # standard library: no install needed
from pathlib import Path          # standard library
import requests                   # third-party: from requirements.txt

from mymodule import my_function  # your own code, same folder

# requirements.txt — exact versions, so today's working build is tomorrow's working build
requests==2.32.3
PyYAML==6.0.2

# The old shape: three different meanings collapse into one
def should_alert(report):
    if "[SILENT]" in report:      # substring matching on free text!
        return False
    return True                   # a failed parse also lands here

from dataclasses import dataclass
from typing import Literal

@dataclass(frozen=True)
class Decision:
    status: Literal["ok", "unknown"]
    value: bool | None
    confidence: float | None
    reason: str

    def __post_init__(self):
        # An 'ok' decision MUST carry a value. Anything else is a bug, not a default.
        if self.status == "ok" and self.value is None:
            raise ValueError("status ok requires a value")
        if self.status == "unknown" and self.value is not None:
            raise ValueError("status unknown must not carry a value")

def make_ok(value: bool, confidence: float, reason: str) -> Decision:
    return Decision("ok", bool(value), float(confidence), reason)

def make_unknown(reason: str) -> Decision:
    return Decision("unknown", None, None, reason)

def should_alert(report) -> Decision:
    if not isinstance(report, str) or not report.strip():
        return make_unknown("empty or non-text report")
    if "[SILENT]" in report:
        return make_ok(False, 0.95, "model marked silent")
    return make_ok(True, 0.8, "substantive content present")

d = should_alert(model_output)
if d.status == "unknown":
    alert_operator(d.reason)          # visible, actionable
elif d.value:
    send_alert()

THRESHOLD = 0.7

valid = [d for d in decisions if d.status == "ok" and d.confidence >= THRESHOLD]
unknown = [d for d in decisions if d.status == "unknown"]

log.info("answered=%s unknown=%s kept=%s", len(decisions) - len(unknown), len(unknown), len(valid))

# test_classify.py
from classify import classify

def test_empty_is_unknown():
    assert classify("").status == "unknown"

def test_clear_yes_is_ok():
    d = classify("System outage in the Singapore region")
    assert d.status == "ok"
    assert d.value is True

def test_none_is_unknown():
    assert classify(None).status == "unknown"

pip install pytest
pytest -v                       # run every test
pytest test_classify.py -v      # run one file

import pytest

def test_rejects_non_text():
    assert classify(12345).status == "unknown"

def test_decision_invariant():
    with pytest.raises(ValueError):
        Decision(status="ok", value=None, confidence=0.9, reason="bad")

#!/usr/bin/env python3
"""service-check.py - verify local services are accepting connections."""
import json, socket, sys
from dataclasses import dataclass, asdict
from pathlib import Path

@dataclass(frozen=True)
class Check:
    name: str
    port: int
    ok: bool
    detail: str

def probe(host: str, port: int, timeout: float = 3.0) -> tuple[bool, str]:
    """Return (ok, detail) for a TCP connection attempt."""
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True, "accepting connections"
    except socket.timeout:
        return False, f"timed out after {timeout}s"
    except ConnectionRefusedError:
        return False, "connection refused (nothing listening)"
    except OSError as e:
        return False, f"error: {e}"

def run(services) -> list[Check]:
    return [Check(s["name"], s["port"], *probe(s.get("host", "127.0.0.1"), s["port"]))
            for s in services]

def main() -> int:
    path = Path(sys.argv[1] if len(sys.argv) > 1 else "services.json")
    try:
        services = json.loads(path.read_text())
    except (OSError, json.JSONDecodeError) as e:
        print(json.dumps({"error": f"cannot read {path}: {e}"}), file=sys.stderr)
        return 2                                     # 2 = we could not even start

    results = run(services)
    failed = [c for c in results if not c.ok]

    print(json.dumps({
        "checked": len(results),
        "healthy": len(results) - len(failed),
        "failed": [asdict(c) for c in failed],
    }, indent=2))

    return 1 if failed else 0

if __name__ == "__main__":
    sys.exit(main())

[
  {"name": "gateway",        "port": 8081},
  {"name": "cfhook-receiver", "port": 8080}
]

*/5 * * * * /home/ubuntu/.venv/bin/python /home/ubuntu/scripts/service-check.py /home/ubuntu/services.json >> /home/ubuntu/logs/service-check.log 2>&1

$ ansible-playbook site.yml
PLAY RECAP
web1 : ok=6  changed=3  failed=0

$ ansible-playbook site.yml      # run it again
web1 : ok=6  changed=0  failed=0   # nothing to do — state already correct

# inventory.ini
[web]
web1.example.com
web2.example.com

[db]
db1.example.com

[vps]
web01 ansible_host=203.0.113.10 ansible_user=deploy

[all:vars]
ansible_python_interpreter=/usr/bin/python3

ansible all -i inventory.ini -m ping                 # can I reach everything?
ansible web -i inventory.ini -a "uptime"              # run a shell command
ansible all -i inventory.ini -a "df -h" --become       # with root privileges
ansible web -i inventory.ini -m setup | head -30        # gather facts

ansible web01 -i inventory.ini -m setup
# -> ansible_os_family, ansible_memtotal_mb, ansible_distribution, ...

ansible all -i inventory.ini -m setup -a 'filter=ansible_*memory*'

---
- name: Configure web servers
  hosts: web
  become: true

  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true

    - name: Deploy the site configuration
      ansible.builtin.template:
        src: nginx-site.conf.j2
        dest: /etc/nginx/sites-available/default
        owner: root
        group: root
        mode: "0644"
      notify: reload nginx

    - name: Ensure nginx is running and enabled at boot
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

ansible-playbook -i inventory.ini site.yml --check      # dry run: what WOULD change?
ansible-playbook -i inventory.ini site.yml --limit web1 # just one host
ansible-playbook -i inventory.ini site.yml              # all of them
ansible-playbook -i inventory.ini site.yml --diff       # show the changes

PLAY RECAP ************************************************
web1 : ok=5  changed=2  unreachable=0  failed=0  skipped=0
#           │       │              │           └── nothing broke
#           │       │              └── host could not be contacted
#           │       └── tasks that actually altered the system
#           └── tasks that ran clean

# group_vars/web.yml — applies to every host in the 'web' group
nginx_worker_processes: 4
site_name: demo

# host_vars/web1.yml — applies to one host
nginx_worker_processes: 8

# templates/nginx-site.conf.j2
server {
    listen 80;
    server_name {{ site_name }}.example.com;

    # tuned for a {{ ansible_memtotal_mb }}MB machine
    worker_processes {{ nginx_worker_processes }};

    location / {
        proxy_pass http://127.0.0.1:{{ app_port }};
        proxy_set_header Host $host;
    }
}

- name: Deploy config
  ansible.builtin.template:
    src: nginx-site.conf.j2
    dest: /etc/nginx/sites-available/{{ site_name }}
    mode: "0644"

- name: Override at runtime
  ansible.builtin.debug:
    msg: "{{ site_name }} port {{ app_port }}"
# ansible-playbook site.yml -e "app_port=9090"

- name: Install the right package manager
  ansible.builtin.package:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

roles/nginx/
├── tasks/main.yml        # what to do
├── handlers/main.yml     # deferred actions
├── templates/nginx.conf.j2
├── files/index.html
├── defaults/main.yml     # overridable defaults (lowest precedence)
├── vars/main.yml         # role-internal values (higher precedence)
└── meta/main.yml         # dependencies on other roles

ansible-galaxy init roles/nginx

# roles/nginx/tasks/main.yml
---
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present
    update_cache: true

- name: Write configuration
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    mode: "0644"
  notify: restart nginx

- name: Start and enable
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

# roles/nginx/defaults/main.yml
nginx_worker_processes: 2
nginx_client_max_body_size: 1m

---
- name: Web tier
  hosts: web
  become: true
  roles:
    - role: nginx
      vars:
        nginx_worker_processes: 4

---
- name: Common baseline on everything
  hosts: all
  become: true
  roles: [common]

- name: Web servers
  hosts: web
  become: true
  roles: [nginx]

- name: Database servers
  hosts: db
  become: true
  roles: [postgres]

ansible-vault create group_vars/all/vault.yml        # new encrypted file
ansible-vault edit group_vars/all/vault.yml          # change it
ansible-vault view group_vars/all/vault.yml          # read it
ansible-vault encrypt secrets.yml                    # encrypt an existing file
ansible-vault decrypt secrets.yml                    # remove encryption (careful)

- name: Use a secret without printing it
  ansible.builtin.template:
    src: app.env.j2
    dest: /etc/app.env
    mode: "0600"                        # secrets must not be world-readable
  vars:
    db_password: "{{ vault_db_password }}"

- name: Prefer no_log for secret tasks
  ansible.builtin.command: /usr/local/bin/setup-db
  no_log: true                          # keeps the value out of the output

ansible-playbook site.yml --ask-vault-pass
# or, for unattended automation, a password file with 600 permissions:
ansible-playbook site.yml --vault-password-file ~/.ansible/vault-pass

group_vars/all/vars.yml        # non-secret values, committed
 group_vars/all/vault.yml       # secrets, committed ENCRYPTED
~/.ansible/vault-pass           # the password itself, mode 600, NEVER committed

site.yml
inventory.ini
roles/
├── common/      # baseline: packages, timezone, user, permissions
├── nginx/       # install, configure from template, enable
└── firewall/    # allow 80/443, deny the rest

---
- name: Baseline
  hosts: all
  become: true
  roles: [common]

- name: Web tier
  hosts: web
  become: true
  roles:
    - nginx
    - firewall

# roles/firewall/tasks/main.yml
---
- name: Allow SSH before anything else, or we lock ourselves out
  community.general.ufw:
    rule: allow
    port: "22"
    proto: tcp

- name: Allow web traffic
  community.general.ufw:
    rule: allow
    port: "{{ item }}"
    proto: tcp
  loop: ["80", "443"]

- name: Enable the firewall
  community.general.ufw:
    state: enabled
    policy: deny

# 1. dry run on one host — expect no surprises
ansible-playbook -i inventory.ini site.yml --check --limit web1

# 2. real run on one host
ansible-playbook -i inventory.ini site.yml --limit web1

# 3. idempotence proof: nothing should change now
ansible-playbook -i inventory.ini site.yml --limit web1   # changed=0

# 4. independent verification, not just Ansible's word
ansible web1 -i inventory.ini -a "systemctl is-active nginx"
curl -s -o /dev/null -w "%{http_code}\n" http://web1/

.github/workflows/test.yml      # the path is fixed
.github/workflows/deploy.yml

name: test

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        run: pytest -v

      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

# WRONG — this token is now public forever
deploy:
  api_token: "cf_live_a1b2c3..."

# RIGHT — stored in repository settings, injected at run time
deploy:
  env:
    CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

deploy:
  runs-on: ubuntu-latest
  environment:
    name: production
    url: https://demo.example.com
  steps:
    - name: Deploy
      run: ./deploy.sh
      env:
        CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

# DANGEROUS — a crafted branch name can run commands
- run: echo "Deploying ${{ github.head_ref }}"

# SAFER — pass it through the environment
- run: echo "Deploying $BRANCH"
  env:
    BRANCH: ${{ github.head_ref }}

name: deploy-site

on:
  push:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate HTML
        run: |
          pip install html5validator
          html5validator --root ./public

      - name: Check no secrets are present
        run: |
          if grep -rIE "(api[_-]?key|token|password)\s*[:=]\s*['\"][A-Za-z0-9]{16,}" ./public; then
            echo "Possible secret committed"; exit 1
          fi

  deploy:
    needs: build-and-test          # do not deploy if checks failed
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Publish
        run: npx wrangler pages deploy ./public --project-name my-site
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Verify it is actually live
        run: |
          sleep 10
          code=$(curl -s -o /dev/null -w "%{http_code}" https://my-site.example.com/)
          echo "live status: $code"
          test "$code" = "200"

# stamp a content hash so browsers cannot serve a stale build
HASH=$(sha256sum public/app.js | cut -c1-10)
sed -i "s/app\.js?v=[a-f0-9]*/app.js?v=$HASH/" public/index.html

# record what is deployed, so rollback is a known target
echo "$GIT_SHA" > public/VERSION

# roll back = deploy the previous recorded version
./deploy.sh --version "$PREVIOUS_SHA"

name: pipeline

on:
  push:
    branches: [main]
  workflow_dispatch:            # allow a manual run when needed

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: No secrets in the tree
        run: |
          ! grep -rIE "(api[_-]?key|secret|password)\s*[:=]\s*['\"][A-Za-z0-9_-]{16,}" . \
            --exclude-dir=.git

      - name: Check required files exist
        run: |
          test -f public/index.html || { echo "index.html missing"; exit 1; }

      - name: Record the version
        run: echo "${GITHUB_SHA:0:10}" > public/VERSION

  deploy:
    needs: verify
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        run: npx wrangler pages deploy ./public --project-name my-project
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

      - name: Verify live
        run: |
          sleep 10
          url="https://my-site.example.com/?cb=$RANDOM"    # cache-buster
          code=$(curl -s -o /dev/null -w "%{http_code}" "$url")
          echo "status=$code"
          test "$code" = "200"
          # confirm the version we shipped is the version being served
          curl -s "https://my-site.example.com/VERSION?cb=$RANDOM"

# a minimal usage check, run on a schedule
CURRENT=$(curl -s "$METRICS_URL" | jq -r '.rows_written')
LIMIT=100000
PCT=$(( CURRENT * 100 / LIMIT ))
[ "$PCT" -ge 70 ] && echo "WARNING: ${PCT}% of daily allowance used"

FROM python:3.12-slim

# non-root user: a contained compromise
RUN useradd --create-home --uid 10001 appuser

WORKDIR /app

# dependencies first, so code changes do not invalidate the cache
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser . .

USER appuser

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s \
  CMD python -c "import urllib.request;urllib.request.urlopen('http://127.0.0.1:8000/health')"

CMD ["python", "-m", "app"]

docker build -t myapp:1.0 .
docker run -d --name myapp -p 8000:8000 myapp:1.0
docker logs -f myapp
docker ps                       # what is running
docker exec -it myapp sh        # get a shell inside
docker stop myapp && docker rm myapp

services:
  web:
    build: .
    ports: ["8000:8000"]
    environment:
      DB_HOST: db
    depends_on: [db]

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - dbdata:/var/lib/postgresql/data

volumes:
  dbdata:

docker compose up -d
docker compose logs -f
docker compose down

BAD:  "Something is wrong"
GOOD: "API writes at 78% of the daily quota (78,412/100,000).
       Projection: quota reached ~16:40 UTC. First action: check the sync
       job for a retry loop; disable bulk sync to reduce writes."

# A check that only alerts on the condition worth waking someone for
usage_pct=$(curl -s "$URL" | jq -r '.pct')
if [ "$usage_pct" -ge 70 ]; then
  notify "usage ${usage_pct}% of daily allowance — action needed"
fi

# Validate and bound input: never trust what arrives
MAX_LEN = 4096

def handle(payload: dict):
    text = payload.get("text")
    if not isinstance(text, str) or len(text) > MAX_LEN:
        raise ValueError("invalid or oversized input")
    # never interpolate untrusted input into a shell command
    return run_with_argv(["tool", "--input", text])

# DANGEROUS: a crafted filename runs arbitrary commands
os.system(f"tar -czf backup.tar.gz {filename}")

# SAFE: an argument list, no shell
subprocess.run(["tar", "-czf", "backup.tar.gz", filename], check=True)

# A restore drill: prove the archive is usable, not just present
LATEST=$(ls -1t /home/ubuntu/backups/*.tar.gz | head -1)
echo "testing $LATEST"

tar -tzf "$LATEST" > /tmp/restore-list.txt     # 1. is it readable?
wc -l /tmp/restore-list.txt                     # 2. does it contain files?

tar -xzf "$LATEST" -C /tmp/restore-test         # 3. extract somewhere safe
diff -r /home/ubuntu/notes /tmp/restore-test/notes  # 4. does it match?

## Service outage — app-gateway

**Symptom**: no responses, gateway inactive.

**Check**:
1. `systemctl --user status app-gateway`
2. `journalctl --user -u app-gateway -n 50`
3. Look for a config error or a port already in use.

**Restore**:
1. `systemctl --user restart app-gateway`
2. Confirm active and listening: `ss -ltnp | grep 8081`
3. Send a test message and confirm a reply.

**If that fails**: restore `/etc/app/config.yaml` from the newest backup and restart.

**Escalate**: if unresolved in 15 minutes, notify the owner — no silent waiting.