From 8294ddee7471d0def0cba4efd8140eb7f4c06e7b Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:20:18 -0700 Subject: [PATCH 01/27] chore(scenarios): deep-link KB Resolution Steps and Lab Verification sections --- scenarios/account-lockout-reset.md | 4 ++-- scenarios/outlook-reconnect-after-update.md | 4 ++-- scenarios/printer-queue-clearing.md | 4 ++-- scenarios/workstation-performance-triage.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/scenarios/account-lockout-reset.md b/scenarios/account-lockout-reset.md index d294760..50f3cdf 100644 --- a/scenarios/account-lockout-reset.md +++ b/scenarios/account-lockout-reset.md @@ -1,8 +1,8 @@ # Scenario: Account lockout and password reset - Related Ticket: /tickets/account-locked-out.md -- Related KB: /kb/account-lockout-reset.md -- Related Lab: /labs/htpasswd-auth-reset.md +- Related KB: /kb/account-lockout-reset.md#resolution-steps +- Related Lab: /labs/htpasswd-auth-reset.md#verification ## Flow 1. User reports lockout; verify identity and account status. diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 4a8a87b..8484b30 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -1,8 +1,8 @@ # Scenario: Outlook reconnect after update - Related Ticket: /tickets/outlook-disconnected-password-prompts.md -- Related KB: /kb/outlook-reconnect-after-update.md -- Related Lab: /labs/mailhog-connectivity.md +- Related KB: /kb/outlook-reconnect-after-update.md#resolution-steps +- Related Lab: /labs/mailhog-connectivity.md#verification ## Flow 1. Validate credentials on another system; check VPN if remote. diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index ed97ec3..1e7fd4a 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -1,8 +1,8 @@ # Scenario: Department-wide printer outage (queue clearing) - Related Ticket: /tickets/cannot-print-to-shared-printer.md -- Related KB: /kb/printer-queue-clearing.md -- Related Lab: /labs/print-queue-stuck.md +- Related KB: /kb/printer-queue-clearing.md#resolution-steps +- Related Lab: /labs/print-queue-stuck.md#verification ## Flow 1. Confirm scope (multiple users); check server queue/state. diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 3105810..80e9beb 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -1,8 +1,8 @@ # Scenario: Workstation performance triage - Related Ticket: /tickets/computer-running-slow-lagging.md -- Related KB: /kb/workstation-performance-triage.md -- Related Lab: /labs/resource-spike-triage.md +- Related KB: /kb/workstation-performance-triage.md#resolution-steps +- Related Lab: /labs/resource-spike-triage.md#verification ## Flow 1. Compare internal vs external latency; check local resource usage. From ecfb6f5ade989c05848d440277c0d58d4801b860 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:26:07 -0700 Subject: [PATCH 02/27] chore(pr-template): add anti-duplication + deep-link checks; lab/KB/scenario sub-checks; verify section --- .github/PULL_REQUEST_TEMPLATE.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 62165da..1540d69 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,13 +12,32 @@ Briefly describe what this PR adds or changes. - [ ] Uses the correct template (copied from 000.*-template.md) - [ ] Clear, reproducible steps and plain language - [ ] Relative links resolve inside the repo + - [ ] Avoid duplication across modules (KB = productized steps; Lab = full commands + Verification; Scenario = flow/success, links only) + - [ ] Deep link to sections where applicable (KB → #resolution-steps, Lab → #verification) - Metadata - [ ] Owner set; Last Reviewed and Next Review Due (KB/Lab) - [ ] Escalation Path filled (Ticket) - [ ] Metrics block added if useful (see docs/METRICS.md) - Quality - [ ] Verification steps included (expected outputs / pass-fail) + - [ ] Anchors exist and resolve (KB “Resolution Steps”, Lab “Verification”) - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria +### Labs (if included) +- [ ] Dedicated “Verification” section with expected outputs +- [ ] Images pinned if using containers; HTTP services include a simple healthcheck when applicable +- [ ] Assets stored under `labs//assets/` + +### KBs (if included) +- [ ] Brief (1–2 lines) verification; link to related Lab for full commands + +### Scenarios (if included) +- [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) + ## Notes Add screenshots, logs, or context as needed. + +## How to Verify (for reviewers) +- Click Related KB/Lab links and confirm they jump to the correct anchors. +- If a Lab changed, run the Verification steps and confirm expected outputs. +- Check that no personal IPs or credentials are included; use `` placeholders. From 4297b9fdbdb95b2a48939bb7657bb4d844eb39d3 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:31:20 -0700 Subject: [PATCH 03/27] ci: add markdownlint workflow + config; chore: add CODEOWNERS for reviews --- .github/CODEOWNERS | 8 ++++++++ .github/workflows/markdownlint.yml | 19 +++++++++++++++++++ .markdownlint.jsonc | 8 ++++++++ 3 files changed, 35 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/workflows/markdownlint.yml create mode 100644 .markdownlint.jsonc diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..21e3a61 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Require review from maintainers for key areas +* @iplaycomputer + +# Optional: expand with more granular ownership as project grows +# /kb/ @iplaycomputer +# /labs/ @iplaycomputer +# /tickets/ @iplaycomputer +# /scenarios/ @iplaycomputer diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 0000000..32cbb04 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,19 @@ +name: markdownlint + +on: + pull_request: + push: + branches: [ main ] + +jobs: + lint: + name: lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: | + **/*.md diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 0000000..8e06554 --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,8 @@ +{ + // Allow long lines in code blocks and tables + "MD013": false, + // Allow consecutive headings in templates/checklists + "MD025": false, + // Allow inline HTML when needed + "MD033": false +} From 608bed487ea6d56969481d0cff6e1b9c86752ff8 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:36:37 -0700 Subject: [PATCH 04/27] fix(docs): satisfy markdownlint MD022/MD032 in copilot-instructions --- .github/copilot-instructions.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1a3fa1..fceefc7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -3,6 +3,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents should prioritize clarity, reproducibility, and alignment with the troubleshooting standards in `CONTRIBUTING.md`. ## Big Picture + - Four modules map to real workflows: - Tickets (`/tickets/`): user-reported issues - Knowledge Base (`/kb/`): solution docs derived from tickets @@ -11,6 +12,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Use templates in each folder (`000.*-template.md`). ## Key Files + - `CONTRIBUTING.md`: Primary standards, workflows, and references (CompTIA A+ model, escalation, templates). - `docs/lamp-osticket-setup.md`: Optional local osTicket setup to test tickets/KBs. - `docs/ROLES.md`: Lightweight tiers, escalation cues, and ownership metadata. @@ -18,6 +20,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - `README.md`: Project overview and contribution on-ramp. ## Authoring Patterns + - Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. - Keep language plain and steps reproducible. Include environment details (OS/version), verification, and escalation path. - Link artifacts with relative paths (e.g., `/tickets/printer-failure.md` in KB/Lab/Scenario). @@ -28,20 +31,24 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Scenarios should express flow and success criteria, linking to KB "Resolution Steps" and Lab "Verification" sections (use deep links like `/kb/foo.md#resolution-steps` and `/labs/bar.md#verification`). ## Workflows + - Propose in Discussions: draft tickets/KBs/labs in appropriate categories. - Land changes via PRs adding Markdown under `/tickets`, `/kb`, `/labs`, `/scenarios`. - Labs should be verifiable on a Linux VM or container; osTicket is optional. ## Examples from Repo + - Templates: `kb/000.kb-template.md`, `labs/000.lab-template.md`, `tickets/000.ticket-template.md`, `scenarios/000.scenario-template.md`. - osTicket URLs referenced use `http:///osticket/` and `.../scp` for staff; replace `` locally and do not share it publicly. ## Conventions + - Filenames: use kebab-case, concise, and descriptive (e.g., `printer-spooler-restart.md`). - Metadata blocks: include Category, Environment, Owner, Reviewed dates when applicable. - References: cite external docs in a final section; prefer vendor support links. ## What NOT to do + - Don’t invent infrastructure or public endpoints; this repo is markdown-only. - Don’t add personal IPs or credentials. From 744b06c8efdd12687a44fca9b55c4ada4ed4d69c Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:41:03 -0700 Subject: [PATCH 05/27] ci(markdownlint): add .markdownlint-cli2.jsonc to ensure config discovery --- .markdownlint-cli2.jsonc | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .markdownlint-cli2.jsonc diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..835920e --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,6 @@ +{ + // Inherit rules from .markdownlint.jsonc and set default globs + "config": ".markdownlint.jsonc", + "globs": ["**/*.md"], + "ignores": ["**/node_modules/**", ".git/**"] +} From 655986a98d178dd04e411ac16de60c87267b1503 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:48:22 -0700 Subject: [PATCH 06/27] ci(markdownlint): temporarily relax strict rules (MD012, MD022, MD023, MD026, MD031, MD032, MD040, MD041, MD005, MD007) to unblock --- .markdownlint.jsonc | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 8e06554..4b0dc3a 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -4,5 +4,16 @@ // Allow consecutive headings in templates/checklists "MD025": false, // Allow inline HTML when needed - "MD033": false + "MD033": false, + // Temporarily relax common failures during bootstrap + "MD031": false, + "MD022": false, + "MD032": false, + "MD023": false, + "MD012": false, + "MD005": false, + "MD007": false, + "MD040": false, + "MD041": false, + "MD026": false } From 3550c95e0e2794e563c7d562fac7aa7ab4622c72 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 02:54:33 -0700 Subject: [PATCH 07/27] lint(strict): fix MD022/MD023/MD031 in labs; restore strict markdownlint config - Left-align Verification headings in labs - Ensure blank lines around fenced blocks and add languages - Keep only MD013/MD025/MD033 disabled in .markdownlint.jsonc --- .markdownlint.jsonc | 15 ++------------- labs/htpasswd-auth-reset.md | 7 ++++--- labs/mailhog-connectivity.md | 7 ++++--- labs/print-queue-stuck.md | 7 ++++--- labs/resource-spike-triage.md | 7 ++++--- 5 files changed, 18 insertions(+), 25 deletions(-) diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 4b0dc3a..56ac331 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -3,17 +3,6 @@ "MD013": false, // Allow consecutive headings in templates/checklists "MD025": false, - // Allow inline HTML when needed - "MD033": false, - // Temporarily relax common failures during bootstrap - "MD031": false, - "MD022": false, - "MD032": false, - "MD023": false, - "MD012": false, - "MD005": false, - "MD007": false, - "MD040": false, - "MD041": false, - "MD026": false + // Allow inline HTML when needed (README badges) + "MD033": false } diff --git a/labs/htpasswd-auth-reset.md b/labs/htpasswd-auth-reset.md index bb6d871..72adc62 100644 --- a/labs/htpasswd-auth-reset.md +++ b/labs/htpasswd-auth-reset.md @@ -42,12 +42,13 @@ Simulate a credential reset and prove the fix with a protected endpoint. # Expect 200 ``` - ## Verification - ```powershell +## Verification + +```powershell $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode # Expect: 200 - ``` +``` ## Cleanup ```powershell diff --git a/labs/mailhog-connectivity.md b/labs/mailhog-connectivity.md index 1077a3b..8699374 100644 --- a/labs/mailhog-connectivity.md +++ b/labs/mailhog-connectivity.md @@ -45,11 +45,12 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. 5) Verify in UI - Browse http://localhost:8025 and confirm the message is present. - ## Verification - ```powershell +## Verification + +```powershell Invoke-WebRequest http://localhost:8025 -UseBasicParsing | Select-Object -ExpandProperty StatusCode # Expect: 200 (and message visible in UI) - ``` +``` ## Cleanup ```powershell diff --git a/labs/print-queue-stuck.md b/labs/print-queue-stuck.md index 797c865..99a6171 100644 --- a/labs/print-queue-stuck.md +++ b/labs/print-queue-stuck.md @@ -52,11 +52,12 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo docker exec print-queue cat /queue/processed.txt ``` - ## Verification - ```powershell +## Verification + +```powershell docker exec print-queue cat /queue/processed.txt # Expect: remaining job name present; queue stable - ``` +``` ## Cleanup ```powershell diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index 89b4ecb..1a75242 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -41,11 +41,12 @@ Practice identifying and resolving resource spikes that cause slowness. # Expect CPU usage back to normal ``` - ## Verification - ```bash +## Verification + +```bash top -b -n 1 | head -n 20 # Expect: CPU/Disk normalized; no stress-ng running - ``` +``` ## Cleanup ```bash From 397f8013c9034c60c2a8a7ca9c170251a37c8ee4 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 03:04:10 -0700 Subject: [PATCH 08/27] lint(strict): fix MD022/MD032 blanks around headings/lists in scenarios and tickets --- scenarios/README.md | 3 +++ scenarios/outlook-reconnect-after-update.md | 3 +++ scenarios/printer-queue-clearing.md | 3 +++ scenarios/workstation-performance-triage.md | 3 +++ tickets/000.ticket-template.md | 3 +++ tickets/README.md | 4 ++++ tickets/account-locked-out.md | 3 +++ tickets/cannot-print-to-shared-printer.md | 3 +++ tickets/computer-running-slow-lagging.md | 3 +++ tickets/outlook-disconnected-password-prompts.md | 3 +++ 10 files changed, 31 insertions(+) diff --git a/scenarios/README.md b/scenarios/README.md index fb778fb..fb59a46 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -3,6 +3,7 @@ End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. - Template: [000.scenario-template.md](./000.scenario-template.md) + - Good scenarios include: - A realistic ticket with symptoms and constraints - A KB solution path with alternatives @@ -10,5 +11,7 @@ End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the stor - Clear acceptance/success criteria Conventions: + - Name scenarios clearly (e.g., `printer-spooler-end-to-end.md`). - Link artifacts with relative paths; avoid external private endpoints. + diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 8484b30..04d5af3 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -9,6 +9,9 @@ 2. Confirm connectivity; recreate profile or clear cached credentials as needed. 3. In lab, use MailHog to verify SMTP is reachable and a test message is captured. + ## Success Criteria +- - MailHog shows the test message; service reachable. - Ticket notes profile/cache actions; KB drafted with steps. + diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index 1e7fd4a..2d14b4d 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -9,6 +9,9 @@ 2. Clear stuck job(s); restart the service. 3. In lab, simulate stuck queue; clear oldest job; restart consumer. + ## Success Criteria +- - Queue shows processed jobs and accepts new test job. - Ticket documents scope, remediation, and server-side action; KB drafted. + diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 80e9beb..07c650b 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -9,6 +9,9 @@ 2. Identify culprit (scan/update/runaway process); apply remediation. 3. In lab, trigger and stop a synthetic load; verify usage returns to normal. + ## Success Criteria +- - CPU/Disk usage normalizes; simple command completes fast. - Ticket lists root cause and remediation; KB drafted. + diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index 8864eb3..74ad8d3 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -10,6 +10,7 @@ **Environment:** [OS, system, or software version] **Troubleshooting Steps Taken:** +- - [ ] [Step 1, e.g., "Checked printer connection"] - [ ] [Step 2, e.g., "Restarted Print Spooler service"] @@ -17,6 +18,8 @@ [Steps to resolve, or "TBD" if unknown] **Escalation Path:** +- - [ ] Tier 1 complete (basic troubleshooting done) - [ ] Escalated to Tier 2 (e.g., for driver issues) - [ ] Escalated to Tier 3 (e.g., for hardware replacement) + diff --git a/tickets/README.md b/tickets/README.md index e9492ec..400be77 100644 --- a/tickets/README.md +++ b/tickets/README.md @@ -3,18 +3,22 @@ User-reported issues. Start here when simulating a helpdesk intake. - Template: [000.ticket-template.md](./000.ticket-template.md) + - How to write good tickets: - Be specific about symptoms, environment, and what changed. - Include simple reproduction steps if known. - Avoid credentials or personal IPs. Conventions: + - Use kebab-case filenames (e.g., `printer-wont-print.md`). - Link related KBs/labs/scenarios with relative paths. - Follow the CompTIA A+ 6-step model in your troubleshooting notes. Examples: + - [Account locked out – cannot log in](./account-locked-out.md) - [Cannot print to shared Finance printer](./cannot-print-to-shared-printer.md) - [Outlook disconnected and password prompts](./outlook-disconnected-password-prompts.md) - [Computer is running extremely slow / lagging](./computer-running-slow-lagging.md) + diff --git a/tickets/account-locked-out.md b/tickets/account-locked-out.md index 9f6fe54..626b3ff 100644 --- a/tickets/account-locked-out.md +++ b/tickets/account-locked-out.md @@ -17,6 +17,7 @@ **Environment:** Windows desktop joined to AD; remote services (email/VPN) affected. **Troubleshooting Steps Taken:** +- - [ ] Verified user identity via secondary info (DOB, employee ID) - [ ] Checked AD status for JDoe - [ ] If locked, unlocked account @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (basic checks and unlock/reset) - [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) - [ ] Escalated to Tier 3 (directory service problems) + diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 1631e7c..7f51f9c 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -17,6 +17,7 @@ **Environment:** Windows clients printing via central print server. **Troubleshooting Steps Taken:** +- - [ ] Confirmed print server is running and reachable - [ ] Remotely checked client printer driver/port - [ ] Cleared local print queue; attempted test page @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (client/queue verification) - [ ] Escalated to Tier 2 (server-side queue/driver) - [ ] Escalated to Tier 3 (hardware/network issue) + diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index 1d06fe8..5d45901 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -17,6 +17,7 @@ **Environment:** Windows 10 desktop; corporate network. **Troubleshooting Steps Taken:** +- - [ ] Compared internal vs external network latency (ping tests) - [ ] Checked Task Manager CPU/RAM/Disk usage and processes - [ ] Ran malware scan or checked for runaway updates @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (resource & basic network checks) - [ ] Escalated to Tier 2 (network/server) - [ ] Escalated to Tier 3 (hardware upgrade/policy) + diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 66e8da5..30c9f82 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -17,6 +17,7 @@ **Environment:** Laptop (potentially remote); VPN in use when offsite. **Troubleshooting Steps Taken:** +- - [ ] Verified credentials work on another system (e.g., internal portal) - [ ] Checked Outlook status bar connectivity - [ ] Verified VPN connection if remote @@ -27,6 +28,8 @@ [TBD] **Escalation Path:** +- - [ ] Tier 1 complete (profile/credentials checks) - [ ] Escalated to Tier 2 (Exchange/Autodiscover) - [ ] Escalated to Tier 3 (SAML/MFA/identity provider) + From 7b7c8b6977363c2c0cef78ab6bb89c0854aaad30 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 03:08:39 -0700 Subject: [PATCH 09/27] lint(strict): convert bold labels to ATX headings; fix trailing/multiple blanks --- tickets/computer-running-slow-lagging.md | 10 +++++----- tickets/outlook-disconnected-password-prompts.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index 5d45901..ce05d6f 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -16,8 +16,8 @@ **Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. **Environment:** Windows 10 desktop; corporate network. -**Troubleshooting Steps Taken:** -- +## Troubleshooting Steps Taken + - [ ] Compared internal vs external network latency (ping tests) - [ ] Checked Task Manager CPU/RAM/Disk usage and processes - [ ] Ran malware scan or checked for runaway updates @@ -27,9 +27,9 @@ **Resolution:** [TBD] -**Escalation Path:** -- +## Escalation Path + - [ ] Tier 1 complete (resource & basic network checks) - [ ] Escalated to Tier 2 (network/server) - [ ] Escalated to Tier 3 (hardware upgrade/policy) - + diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 30c9f82..8b6a02b 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -16,8 +16,8 @@ **Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. **Environment:** Laptop (potentially remote); VPN in use when offsite. -**Troubleshooting Steps Taken:** -- +## Troubleshooting Steps Taken + - [ ] Verified credentials work on another system (e.g., internal portal) - [ ] Checked Outlook status bar connectivity - [ ] Verified VPN connection if remote @@ -27,9 +27,9 @@ **Resolution:** [TBD] -**Escalation Path:** -- +## Escalation Path + - [ ] Tier 1 complete (profile/credentials checks) - [ ] Escalated to Tier 2 (Exchange/Autodiscover) - [ ] Escalated to Tier 3 (SAML/MFA/identity provider) - + From df3748ec70a58aecb1ceba1f8d710cfe1e116c06 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 03:14:15 -0700 Subject: [PATCH 10/27] lint(strict): normalize ticket template headings; add editor guardrails (.editorconfig, VS Code settings) --- .editorconfig | 12 ++++++++++++ .vscode/settings.json | 8 ++++++++ tickets/000.ticket-template.md | 25 +++++++++++++++---------- 3 files changed, 35 insertions(+), 10 deletions(-) create mode 100644 .editorconfig create mode 100644 .vscode/settings.json diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..6e120d0 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +# EditorConfig helps maintain consistent coding styles +root = true + +[*] +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +[*.md] +# Keep Markdown tidy; code blocks remain untouched by trim rule exceptions +trim_trailing_whitespace = true diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..f6fc268 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,8 @@ +{ + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "files.eol": "\n", + "[markdown]": { + "editor.formatOnSave": true + } +} \ No newline at end of file diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index 74ad8d3..6897c15 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -5,21 +5,26 @@ **Impact:** Single user | Department | Organization-wide **Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) -**Problem:** [One-line description of the issue] -**Symptoms:** [What the user sees or experiences] -**Environment:** [OS, system, or software version] +## Problem +[One-line description of the issue] + +## Symptoms +[What the user sees or experiences] + +## Environment +[OS, system, or software version] + +## Troubleshooting Steps Taken -**Troubleshooting Steps Taken:** -- - [ ] [Step 1, e.g., "Checked printer connection"] - [ ] [Step 2, e.g., "Restarted Print Spooler service"] -**Resolution:** -[Steps to resolve, or "TBD" if unknown] +## Resolution +[Steps to resolve, or "TBD" if unknown] + +## Escalation Path -**Escalation Path:** -- - [ ] Tier 1 complete (basic troubleshooting done) - [ ] Escalated to Tier 2 (e.g., for driver issues) - [ ] Escalated to Tier 3 (e.g., for hardware replacement) - + From cd61b9c958bd719e0ae801ea1d71c016a49566f8 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 04:02:31 -0700 Subject: [PATCH 11/27] chore(lint): align markdownlint config and editor guardrails - Disable MD041 and MD051 to match pipeline plan - Add VS Code extension recommendations - Enable markdownlint fix-on-save for Markdown --- .markdownlint.jsonc | 6 +++++- .vscode/extensions.json | 6 ++++++ .vscode/settings.json | 3 ++- 3 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 .vscode/extensions.json diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 56ac331..596d809 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -4,5 +4,9 @@ // Allow consecutive headings in templates/checklists "MD025": false, // Allow inline HTML when needed (README badges) - "MD033": false + "MD033": false, + // Allow non-heading first lines (some files are not articles) + "MD041": false, + // Temporarily disable strict fragment validation to reduce false positives on deep-links + "MD051": false } diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..c44d7a7 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "DavidAnson.vscode-markdownlint", + "EditorConfig.EditorConfig" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json index f6fc268..afd4f67 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,6 +3,7 @@ "files.insertFinalNewline": true, "files.eol": "\n", "[markdown]": { - "editor.formatOnSave": true + "editor.formatOnSave": true, + "markdownlint.fix.onSave": true } } \ No newline at end of file From 18c266754f56f6de75903f83651e6197278c0090 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 04:11:48 -0700 Subject: [PATCH 12/27] fix(markdown): minimal lint fixes - Ticket template: fix malformed heading and add required blank lines - Printer ticket: remove stray text and add blank line before checklist --- tickets/000.ticket-template.md | 12 ++++++++---- tickets/cannot-print-to-shared-printer.md | 3 ++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index 6897c15..dc47ac0 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -1,17 +1,20 @@ # Ticket: [Short Title] -**Category:** Hardware | Software | Network | Account | Other -**Priority:** Low | Medium | High | Critical -**Impact:** Single user | Department | Organization-wide -**Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) +**Category:** Hardware | Software | Network | Account | Other +**Priority:** Low | Medium | High | Critical +**Impact:** Single user | Department | Organization-wide +**Urgency:** Low (no workflow impact) | Medium (work slowed) | High (work blocked) ## Problem + [One-line description of the issue] ## Symptoms + [What the user sees or experiences] ## Environment + [OS, system, or software version] ## Troubleshooting Steps Taken @@ -20,6 +23,7 @@ - [ ] [Step 2, e.g., "Restarted Print Spooler service"] ## Resolution + [Steps to resolve, or "TBD" if unknown] ## Escalation Path diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 7f51f9c..62eb4ca 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -28,8 +28,9 @@ [TBD] **Escalation Path:** -- + - [ ] Tier 1 complete (client/queue verification) - [ ] Escalated to Tier 2 (server-side queue/driver) - [ ] Escalated to Tier 3 (hardware/network issue) + From 893db14ef79dd534223bd99eea8d8d354f36b5aa Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 04:14:22 -0700 Subject: [PATCH 13/27] chore(markdownlint): minimal sweep - Disable MD009 (allow soft-break trailing spaces) - Fix heading/list spacing in scenarios to satisfy MD022/MD032 --- .markdownlint.jsonc | 2 ++ scenarios/outlook-reconnect-after-update.md | 3 ++- scenarios/printer-queue-clearing.md | 4 ++-- scenarios/workstation-performance-triage.md | 4 ++-- 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 596d809..83e3844 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -5,6 +5,8 @@ "MD025": false, // Allow inline HTML when needed (README badges) "MD033": false, + // Allow trailing spaces (soft line breaks) to preserve authoring style + "MD009": false, // Allow non-heading first lines (some files are not articles) "MD041": false, // Temporarily disable strict fragment validation to reduce false positives on deep-links diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 04d5af3..6c9b66d 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -5,13 +5,14 @@ - Related Lab: /labs/mailhog-connectivity.md#verification ## Flow + 1. Validate credentials on another system; check VPN if remote. 2. Confirm connectivity; recreate profile or clear cached credentials as needed. 3. In lab, use MailHog to verify SMTP is reachable and a test message is captured. ## Success Criteria -- + - MailHog shows the test message; service reachable. - Ticket notes profile/cache actions; KB drafted with steps. diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index 2d14b4d..94316cf 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -5,13 +5,13 @@ - Related Lab: /labs/print-queue-stuck.md#verification ## Flow + 1. Confirm scope (multiple users); check server queue/state. 2. Clear stuck job(s); restart the service. 3. In lab, simulate stuck queue; clear oldest job; restart consumer. - ## Success Criteria -- + - Queue shows processed jobs and accepts new test job. - Ticket documents scope, remediation, and server-side action; KB drafted. diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 07c650b..cbf69cd 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -5,13 +5,13 @@ - Related Lab: /labs/resource-spike-triage.md#verification ## Flow + 1. Compare internal vs external latency; check local resource usage. 2. Identify culprit (scan/update/runaway process); apply remediation. 3. In lab, trigger and stop a synthetic load; verify usage returns to normal. - ## Success Criteria -- + - CPU/Disk usage normalizes; simple command completes fast. - Ticket lists root cause and remediation; KB drafted. From e9b6698bbe82857e49276249b2e0f924ef6ae342 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Sun, 28 Sep 2025 04:22:22 -0700 Subject: [PATCH 14/27] docs(markdown): update scenarios and tickets (user edits + spacing fixes) --- .vscode/settings.json | 2 +- scenarios/outlook-reconnect-after-update.md | 2 - scenarios/printer-queue-clearing.md | 3 +- scenarios/workstation-performance-triage.md | 3 +- tickets/000.ticket-template.md | 11 +++-- tickets/account-locked-out.md | 43 +++++++++---------- tickets/cannot-print-to-shared-printer.md | 41 +++++++++--------- .../outlook-disconnected-password-prompts.md | 35 ++++++++------- 8 files changed, 66 insertions(+), 74 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index afd4f67..cd9b925 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -6,4 +6,4 @@ "editor.formatOnSave": true, "markdownlint.fix.onSave": true } -} \ No newline at end of file +} diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index 6c9b66d..fac0f1f 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -10,9 +10,7 @@ 2. Confirm connectivity; recreate profile or clear cached credentials as needed. 3. In lab, use MailHog to verify SMTP is reachable and a test message is captured. - ## Success Criteria - MailHog shows the test message; service reachable. - Ticket notes profile/cache actions; KB drafted with steps. - diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index 94316cf..e9d07d8 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -11,7 +11,6 @@ 3. In lab, simulate stuck queue; clear oldest job; restart consumer. ## Success Criteria - + - Queue shows processed jobs and accepts new test job. - Ticket documents scope, remediation, and server-side action; KB drafted. - diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index cbf69cd..5c6c880 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -11,7 +11,6 @@ 3. In lab, trigger and stop a synthetic load; verify usage returns to normal. ## Success Criteria - + - CPU/Disk usage normalizes; simple command completes fast. - Ticket lists root cause and remediation; KB drafted. - diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index dc47ac0..c4378e6 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -19,8 +19,8 @@ ## Troubleshooting Steps Taken -- [ ] [Step 1, e.g., "Checked printer connection"] -- [ ] [Step 2, e.g., "Restarted Print Spooler service"] +- [ ] [Step 1, e.g., "Checked printer connection"] +- [ ] [Step 2, e.g., "Restarted Print Spooler service"] ## Resolution @@ -28,7 +28,6 @@ ## Escalation Path -- [ ] Tier 1 complete (basic troubleshooting done) -- [ ] Escalated to Tier 2 (e.g., for driver issues) -- [ ] Escalated to Tier 3 (e.g., for hardware replacement) - +- [ ] Tier 1 complete (basic troubleshooting done) +- [ ] Escalated to Tier 2 (e.g., for driver issues) +- [ ] Escalated to Tier 3 (e.g., for hardware replacement) diff --git a/tickets/account-locked-out.md b/tickets/account-locked-out.md index 626b3ff..02443d0 100644 --- a/tickets/account-locked-out.md +++ b/tickets/account-locked-out.md @@ -1,35 +1,34 @@ # Ticket: Account locked out – cannot log in -**Category:** Account -**Priority:** High -**Impact:** Single user +**Category:** Account +**Priority:** High +**Impact:** Single user **Urgency:** High (work blocked) -**Ticket ID:** HLP-20250928-001 -**Status:** New -**Requester:** Jane Doe (ID: JDoe) -**Department:** Sales -**Contact:** Ext: 4122, Cell: (555) 555-4122 +**Ticket ID:** HLP-20250928-001 +**Status:** New +**Requester:** Jane Doe (ID: JDoe) +**Department:** Sales +**Contact:** Ext: 4122, Cell: (555) 555-4122 **System/Component:** Active Directory, Email/VPN Access -**Problem:** User reports account is locked and cannot access desktop, email, or files after vacation. -**Symptoms:** Login attempts fail; account lockout message. +**Problem:** User reports account is locked and cannot access desktop, email, or files after vacation. +**Symptoms:** Login attempts fail; account lockout message. **Environment:** Windows desktop joined to AD; remote services (email/VPN) affected. -**Troubleshooting Steps Taken:** -- -- [ ] Verified user identity via secondary info (DOB, employee ID) -- [ ] Checked AD status for JDoe -- [ ] If locked, unlocked account -- [ ] If password expired, initiated reset or guided through SSPR +**Troubleshooting Steps Taken:** + +- [ ] Verified user identity via secondary info (DOB, employee ID) +- [ ] Checked AD status for JDoe +- [ ] If locked, unlocked account +- [ ] If password expired, initiated reset or guided through SSPR - [ ] Instructed user to restart and attempt login on wired network -**Resolution:** +**Resolution:** [TBD] -**Escalation Path:** -- -- [ ] Tier 1 complete (basic checks and unlock/reset) -- [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) +**Escalation Path:** + +- [ ] Tier 1 complete (basic checks and unlock/reset) +- [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) - [ ] Escalated to Tier 3 (directory service problems) - diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 62eb4ca..812b41d 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -1,36 +1,35 @@ # Ticket: Cannot print to shared Finance printer -**Category:** Hardware -**Priority:** Medium -**Impact:** Department +**Category:** Hardware +**Priority:** Medium +**Impact:** Department **Urgency:** Medium (work slowed) -**Ticket ID:** HLP-20250928-002 -**Status:** New -**Requester:** Michael Smith (ID: MSmith) -**Department:** Finance -**Contact:** Ext: 3015 +**Ticket ID:** HLP-20250928-002 +**Status:** New +**Requester:** Michael Smith (ID: MSmith) +**Department:** Finance +**Contact:** Ext: 3015 **System/Component:** Shared Network Printer (HP LaserJet 5500), Print Server -**Problem:** Department cannot print to shared printer FINANCE-5500. -**Symptoms:** Print jobs stuck as Error/Spooling; device shows Ready with flashing status light. +**Problem:** Department cannot print to shared printer FINANCE-5500. +**Symptoms:** Print jobs stuck as Error/Spooling; device shows Ready with flashing status light. **Environment:** Windows clients printing via central print server. -**Troubleshooting Steps Taken:** +**Troubleshooting Steps Taken:** - -- [ ] Confirmed print server is running and reachable -- [ ] Remotely checked client printer driver/port -- [ ] Cleared local print queue; attempted test page -- [ ] Checked server print queue for large/stuck jobs + +- [ ] Confirmed print server is running and reachable +- [ ] Remotely checked client printer driver/port +- [ ] Cleared local print queue; attempted test page +- [ ] Checked server print queue for large/stuck jobs - [ ] If department-wide, escalated to Tier 2 (Server Team) -**Resolution:** +**Resolution:** [TBD] -**Escalation Path:** +**Escalation Path:** -- [ ] Tier 1 complete (client/queue verification) -- [ ] Escalated to Tier 2 (server-side queue/driver) +- [ ] Tier 1 complete (client/queue verification) +- [ ] Escalated to Tier 2 (server-side queue/driver) - [ ] Escalated to Tier 3 (hardware/network issue) - - diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 8b6a02b..8232c97 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -1,35 +1,34 @@ # Ticket: Outlook disconnected and repeatedly prompting for password -**Category:** Software -**Priority:** Medium -**Impact:** Single user +**Category:** Software +**Priority:** Medium +**Impact:** Single user **Urgency:** Medium -**Ticket ID:** HLP-20250928-003 -**Status:** New -**Requester:** Sarah Chen (ID: SChen) -**Department:** Marketing -**Contact:** Ext: 2005 +**Ticket ID:** HLP-20250928-003 +**Status:** New +**Requester:** Sarah Chen (ID: SChen) +**Department:** Marketing +**Contact:** Ext: 2005 **System/Component:** Microsoft Outlook (Cached Mode), Exchange Server -**Problem:** Outlook disconnects and repeatedly prompts for password after a company security update. -**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. +**Problem:** Outlook disconnects and repeatedly prompts for password after a company security update. +**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. **Environment:** Laptop (potentially remote); VPN in use when offsite. ## Troubleshooting Steps Taken -- [ ] Verified credentials work on another system (e.g., internal portal) -- [ ] Checked Outlook status bar connectivity -- [ ] Verified VPN connection if remote -- [ ] Toggled Cached Exchange Mode +- [ ] Verified credentials work on another system (e.g., internal portal) +- [ ] Checked Outlook status bar connectivity +- [ ] Verified VPN connection if remote +- [ ] Toggled Cached Exchange Mode - [ ] Created a new Outlook profile or cleared Credential Manager entries -**Resolution:** +**Resolution:** [TBD] ## Escalation Path -- [ ] Tier 1 complete (profile/credentials checks) -- [ ] Escalated to Tier 2 (Exchange/Autodiscover) +- [ ] Tier 1 complete (profile/credentials checks) +- [ ] Escalated to Tier 2 (Exchange/Autodiscover) - [ ] Escalated to Tier 3 (SAML/MFA/identity provider) - From 63429a101dc610c5aa35180e8c76a84e93605e33 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 01:05:18 -0700 Subject: [PATCH 15/27] chore(markdown): minimal spacing fixes to satisfy markdownlint - Add blank lines around headings, lists, and code fences (MD022/MD032/MD031) - Add code fence language in README and normalize list indentation (MD040/MD007/MD005) - Remove stray backticks and extra blank lines in scenarios and tickets (MD012) - No content changes --- README.md | 17 +++++++---- labs/resource-spike-triage.md | 11 +++++++ scenarios/000.scenario-template.md | 4 +++ scenarios/account-lockout-reset.md | 2 ++ tickets/cannot-print-to-shared-printer.md | 1 - tickets/computer-running-slow-lagging.md | 35 +++++++++++------------ 6 files changed, 45 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index cfbdc6d..278daf2 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ Whether you’re completely new to IT, sharpening your troubleshooting skills, o ## 🔰 Quick Start: Contribute in 5 Minutes 1. **Fork** this repository and clone it to your machine. + ```bash git clone https://github.com//DeskForge-Simulator.git cd DeskForge-Simulator @@ -43,27 +44,31 @@ Whether you’re completely new to IT, sharpening your troubleshooting skills, o 2. **Create a ticket** using the template in `/tickets/`. Save it as a new Markdown file, e.g.: - ``` + + ```text /tickets/printer-issue.md ``` 3. **Commit and push** your changes. + ```bash git add tickets/printer-issue.md git commit -m "Add sample printer ticket" git push origin main ``` + 4. **Open a Pull Request** to share your contribution! 🎉 👉 That’s it — you’ve added your first simulated helpdesk ticket. Check out `CONTRIBUTING.md` if you want to go deeper (KB articles, labs, scenarios). -### **Note on Real Troubleshooting**: +### **Note on Real Troubleshooting** You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. *This community will treat them as learning scenarios.* However: + - This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. - Please **do not share sensitive information** (personal IPs, passwords, or private configs). - Use advice at your own discretion. @@ -75,9 +80,9 @@ Think of it as a safe space to learn troubleshooting together, not a replacement - Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). - Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. - See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. - - For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. - - Browse available labs in the [Labs Catalog](labs/README.md). - - Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) +- For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. +- Browse available labs in the [Labs Catalog](labs/README.md). +- Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) ## ❤️ Community & Contributions @@ -90,10 +95,10 @@ DeskForge-Simulator is **community-driven**. We welcome: Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). - ## 📫 Questions & Support Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: + - Post tickets (simulated issues) - Draft KB articles - Share lab walkthroughs diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index 1a75242..88ceef2 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -9,33 +9,43 @@ Practice identifying and resolving resource spikes that cause slowness. **Environment:** Linux VM or Docker container ## Objectives + - Trigger a CPU or disk spike - Identify the culprit - Resolve and verify performance returns to normal ## Prerequisites + - Linux shell (VM or WSL2) or Docker ## Steps + 1) Create a CPU spike (Linux VM) + ```bash sudo apt-get update && sudo apt-get install -y stress-ng stress-ng --cpu 2 --timeout 60s & top -b -n 1 | head -n 20 ``` + 2) Or create a CPU spike (Docker) + ```bash docker run --rm -d --name cpu-spike alpine:3.20 sh -c "apk add --no-cache stress-ng && stress-ng --cpu 2 --timeout 60s" docker top cpu-spike ``` + 3) Resolve + ```bash # VM: kill the process if still running pkill -f stress-ng || true # Docker: stop container docker stop cpu-spike || true ``` + 4) Verify + ```bash top -b -n 1 | head -n 20 # Expect CPU usage back to normal @@ -49,6 +59,7 @@ Practice identifying and resolving resource spikes that cause slowness. ``` ## Cleanup + ```bash pkill -f stress-ng 2>/dev/null || true docker rm -f cpu-spike 2>/dev/null || true diff --git a/scenarios/000.scenario-template.md b/scenarios/000.scenario-template.md index 28f64e2..6c25910 100644 --- a/scenarios/000.scenario-template.md +++ b/scenarios/000.scenario-template.md @@ -7,18 +7,22 @@ Link tickets, KB, and labs to form an end-to-end workflow. - Related Lab: /labs/[lab].md ## Overview + Briefly describe the user story and desired outcome. ## Flow + 1) Ticket summary and context 2) Resolution path (KB reference) 3) Practice in lab ## Success Criteria + - [ ] Ticket resolved (what “resolved” means here) - [ ] KB validated (up-to-date and accurate) - [ ] Lab passes verification steps ## Notes + - Assumptions and constraints - Follow-ups or improvements diff --git a/scenarios/account-lockout-reset.md b/scenarios/account-lockout-reset.md index 50f3cdf..048049f 100644 --- a/scenarios/account-lockout-reset.md +++ b/scenarios/account-lockout-reset.md @@ -5,10 +5,12 @@ - Related Lab: /labs/htpasswd-auth-reset.md#verification ## Flow + 1. User reports lockout; verify identity and account status. 2. Reset password; instruct user to retry on wired login. 3. In lab, reset htpasswd password and verify 200 OK with Basic Auth header. ## Success Criteria + - Access restored in lab (HTTP 200) and, in real workflow, user confirms workstation login. - Ticket updated with steps, and (when created) KB drafted referencing the lab. diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 812b41d..382ba15 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -17,7 +17,6 @@ **Environment:** Windows clients printing via central print server. **Troubleshooting Steps Taken:** -- - [ ] Confirmed print server is running and reachable - [ ] Remotely checked client printer driver/port diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index ce05d6f..6c9fac1 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -1,35 +1,34 @@ # Ticket: Computer is running extremely slow / lagging -**Category:** Hardware -**Priority:** Medium -**Impact:** Single user +**Category:** Hardware +**Priority:** Medium +**Impact:** Single user **Urgency:** Medium -**Ticket ID:** HLP-20250928-004 -**Status:** New -**Requester:** David Patel (ID: DPatel) -**Department:** Operations -**Contact:** Ext: 5098 +**Ticket ID:** HLP-20250928-004 +**Status:** New +**Requester:** David Patel (ID: DPatel) +**Department:** Operations +**Contact:** Ext: 5098 **System/Component:** Endpoint PC (Windows 10), Network Connectivity -**Problem:** Computer performance is very slow for common tasks (Chrome, shared drive), despite restarts. -**Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. +**Problem:** Computer performance is very slow for common tasks (Chrome, shared drive), despite restarts. +**Symptoms:** Long app launch times; constant disk activity; internal company site loads slowly while YouTube is fine. **Environment:** Windows 10 desktop; corporate network. ## Troubleshooting Steps Taken -- [ ] Compared internal vs external network latency (ping tests) -- [ ] Checked Task Manager CPU/RAM/Disk usage and processes -- [ ] Ran malware scan or checked for runaway updates -- [ ] Assessed disk health (HDD fragmentation/SMART) +- [ ] Compared internal vs external network latency (ping tests) +- [ ] Checked Task Manager CPU/RAM/Disk usage and processes +- [ ] Ran malware scan or checked for runaway updates +- [ ] Assessed disk health (HDD fragmentation/SMART) - [ ] Isolated network cause; escalate website performance to Web/DevOps if isolated -**Resolution:** +**Resolution:** [TBD] ## Escalation Path -- [ ] Tier 1 complete (resource & basic network checks) -- [ ] Escalated to Tier 2 (network/server) +- [ ] Tier 1 complete (resource & basic network checks) +- [ ] Escalated to Tier 2 (network/server) - [ ] Escalated to Tier 3 (hardware upgrade/policy) - From 3715fee959732b297931dd2ef3022e5dd292f581 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 05:54:06 -0700 Subject: [PATCH 16/27] docs: incorporate manual edits and keep markdownlint green MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Respect user’s whitespace adjustments while keeping required blank lines - Normalize any reintroduced list/fence spacing per rules - No content changes --- README.md | 94 +++++++++++++++++------------------ labs/README.md | 3 ++ labs/resource-spike-triage.md | 22 ++++---- scenarios/README.md | 1 - tickets/README.md | 1 - 5 files changed, 60 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 278daf2..ef45df0 100644 --- a/README.md +++ b/README.md @@ -16,40 +16,40 @@

-# DeskForge-Simulator +# DeskForge-Simulator -**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. +**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. -It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: +It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: -- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. -- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. -- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. -- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. +- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. +- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. +- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. +- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. -💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. +💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. -Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. +Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. ⭐ If you find **DeskForge-Simulator** useful, please give this project a **star** on GitHub — it helps the community grow and keeps the project alive! ## 🔰 Quick Start: Contribute in 5 Minutes -1. **Fork** this repository and clone it to your machine. +1. **Fork** this repository and clone it to your machine. ```bash git clone https://github.com//DeskForge-Simulator.git cd DeskForge-Simulator ``` -2. **Create a ticket** using the template in `/tickets/`. - Save it as a new Markdown file, e.g.: +2. **Create a ticket** using the template in `/tickets/`. + Save it as a new Markdown file, e.g.: ```text /tickets/printer-issue.md ``` -3. **Commit and push** your changes. +3. **Commit and push** your changes. ```bash git add tickets/printer-issue.md @@ -59,63 +59,61 @@ Whether you’re completely new to IT, sharpening your troubleshooting skills, o 4. **Open a Pull Request** to share your contribution! 🎉 -👉 That’s it — you’ve added your first simulated helpdesk ticket. +👉 That’s it — you’ve added your first simulated helpdesk ticket. Check out `CONTRIBUTING.md` if you want to go deeper (KB articles, labs, scenarios). ### **Note on Real Troubleshooting** -You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. -*This community will treat them as learning scenarios.* +You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. +*This community will treat them as learning scenarios.* -However: +However: - This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. -- Please **do not share sensitive information** (personal IPs, passwords, or private configs). -- Use advice at your own discretion. +- Please **do not share sensitive information** (personal IPs, passwords, or private configs). +- Use advice at your own discretion. -Think of it as a safe space to learn troubleshooting together, not a replacement for your workplace or vendor IT support. +Think of it as a safe space to learn troubleshooting together, not a replacement for your workplace or vendor IT support. ## 🚀 Documentation & osTicket -- Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). -- Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. -- See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. +- Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). +- Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. +- See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. - For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. - Browse available labs in the [Labs Catalog](labs/README.md). - Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) -## ❤️ Community & Contributions +## ❤️ Community & Contributions -DeskForge-Simulator is **community-driven**. We welcome: +DeskForge-Simulator is **community-driven**. We welcome: -- 🐞 Bug reports and fixes -- ✨ New tickets, KB articles, and labs -- 📖 Documentation improvements -- 💡 Ideas for scenarios or learning modules +- 🐞 Bug reports and fixes +- ✨ New tickets, KB articles, and labs +- 📖 Documentation improvements +- 💡 Ideas for scenarios or learning modules -Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). +Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). -## 📫 Questions & Support +## 📫 Questions & Support -Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: +Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: -- Post tickets (simulated issues) -- Draft KB articles -- Share lab walkthroughs -- Ask general IT or project-related questions +- Post tickets (simulated issues) +- Draft KB articles +- Share lab walkthroughs +- Ask general IT or project-related questions +## 🤝 Found a Bug? Missing a Feature? -## 🤝 Found a Bug? Missing a Feature? +- File issues here: [DeskForge-Simulator Issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues) +- Open a pull request if you’ve already got a fix or draft +- See [CONTRIBUTING.md](CONTRIBUTING.md) for coding/writing standards -- File issues here: [DeskForge-Simulator Issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues) -- Open a pull request if you’ve already got a fix or draft -- See [CONTRIBUTING.md](CONTRIBUTING.md) for coding/writing standards +## ✅ Requirements - -## ✅ Requirements - -- GitHub account (to contribute) -- Text editor (for Markdown tickets, KBs, labs) -- Optional: - - Ubuntu 24.04 VM (via VirtualBox or Docker) - - osTicket v1.18.1 (local deployment) for testing tickets & KB workflows +- GitHub account (to contribute) +- Text editor (for Markdown tickets, KBs, labs) +- Optional: + - Ubuntu 24.04 VM (via VirtualBox or Docker) + - osTicket v1.18.1 (local deployment) for testing tickets & KB workflows diff --git a/labs/README.md b/labs/README.md index 1941965..7b7f272 100644 --- a/labs/README.md +++ b/labs/README.md @@ -3,6 +3,7 @@ Hands-on troubleshooting exercises. Use these to practice skills and validate KBs. ## Start here + - Beginner: [Nginx fails to start (config error)](./nginx-startup-fail.md) - Account: [Basic auth reset verification](./htpasswd-auth-reset.md) - Email: [Mail connectivity sanity with MailHog](./mailhog-connectivity.md) @@ -10,9 +11,11 @@ Hands-on troubleshooting exercises. Use these to practice skills and validate KB - Performance: [Resource spike triage (CPU/Disk)](./resource-spike-triage.md) ## Templates + - [Lab template](./000.lab-template.md) ## Conventions + - Keep each lab self-contained under `labs//assets` (configs, docker compose, sample files). - Include commands for both PowerShell and Bash when they differ. - At the top of each lab, link any related tickets, KBs, or scenarios. diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index 88ceef2..b763f44 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -2,10 +2,10 @@ Practice identifying and resolving resource spikes that cause slowness. -**Related Ticket:** /tickets/computer-running-slow-lagging.md -**Related KB:** /kb/workstation-performance-triage.md -**Related Scenario:** /scenarios/workstation-performance-triage.md -**Category:** Hardware +**Related Ticket:** /tickets/computer-running-slow-lagging.md +**Related KB:** /kb/workstation-performance-triage.md +**Related Scenario:** /scenarios/workstation-performance-triage.md +**Category:** Hardware **Environment:** Linux VM or Docker container ## Objectives @@ -21,31 +21,31 @@ Practice identifying and resolving resource spikes that cause slowness. ## Steps 1) Create a CPU spike (Linux VM) - + ```bash sudo apt-get update && sudo apt-get install -y stress-ng stress-ng --cpu 2 --timeout 60s & top -b -n 1 | head -n 20 ``` - + 2) Or create a CPU spike (Docker) - + ```bash docker run --rm -d --name cpu-spike alpine:3.20 sh -c "apk add --no-cache stress-ng && stress-ng --cpu 2 --timeout 60s" docker top cpu-spike ``` - + 3) Resolve - + ```bash # VM: kill the process if still running pkill -f stress-ng || true # Docker: stop container docker stop cpu-spike || true ``` - + 4) Verify - + ```bash top -b -n 1 | head -n 20 # Expect CPU usage back to normal diff --git a/scenarios/README.md b/scenarios/README.md index fb59a46..bd9e940 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -14,4 +14,3 @@ Conventions: - Name scenarios clearly (e.g., `printer-spooler-end-to-end.md`). - Link artifacts with relative paths; avoid external private endpoints. - diff --git a/tickets/README.md b/tickets/README.md index 400be77..b6e3106 100644 --- a/tickets/README.md +++ b/tickets/README.md @@ -21,4 +21,3 @@ Examples: - [Cannot print to shared Finance printer](./cannot-print-to-shared-printer.md) - [Outlook disconnected and password prompts](./outlook-disconnected-password-prompts.md) - [Computer is running extremely slow / lagging](./computer-running-slow-lagging.md) - From bab74c5e2470a874a74e8265b41bc72a1d5e57b1 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 05:58:06 -0700 Subject: [PATCH 17/27] fix(labs): satisfy markdownlint in nginx-startup-fail and print-queue-stuck - Add blank lines around headings/lists/fences (MD022/MD032/MD031) - Convert bare URL to angle-bracket link (MD034) - Normalize bullet/fence indentation - No content changes --- labs/nginx-startup-fail.md | 35 ++++++++++++++++++++++++++++++++--- labs/print-queue-stuck.md | 32 ++++++++++++++++++++++++-------- 2 files changed, 56 insertions(+), 11 deletions(-) diff --git a/labs/nginx-startup-fail.md b/labs/nginx-startup-fail.md index 4994965..b5f63be 100644 --- a/labs/nginx-startup-fail.md +++ b/labs/nginx-startup-fail.md @@ -11,47 +11,64 @@ Make a broken web server boot again by fixing a one-word typo. **Next Review Due:** ## Why this matters (30 seconds) + This is what real-life looks like: “my web page won’t load” and the container keeps restarting. Your job is to read the logs, spot the typo, make a tiny change, and prove the fix. ## Objectives + - Diagnose a containerized Nginx startup failure - Fix a simple configuration error and verify success Time: ~10–15 min • Difficulty: Beginner ## Prerequisites (quick preflight) + - Docker is installed and running - PowerShell - ```powershell + + ```powershell docker --version docker compose version ``` + - Bash - ```bash + + ```bash docker --version docker compose version ``` + ## Steps + 1) Start the broken stack (from repo root) + - PowerShell + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml up -d ``` + - Bash + ```bash docker compose -f ./labs/nginx-startup-fail/assets/compose.yaml up -d ``` + 2) Observe the failure - Status + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps ``` + - Logs (look for “unknown directive” or “invalid”) + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml logs nginx ``` + 3) Identify the issue - Open `labs/nginx-startup-fail/assets/nginx.conf` @@ -60,47 +77,59 @@ Time: ~10–15 min • Difficulty: Beginner 4) Fix and retry - Change `roooot` to `root` in nginx.conf - Recreate the container + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml up -d --force-recreate ``` ## Verification (success criteria) -- Browse http://localhost:8080 and see “Nginx is up” + +- Browse and see “Nginx is up” - Container health should go to `healthy` once the page is served - Or use a CLI check: - Check health status quickly + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps # Expect: State shows "running (healthy)" ``` - PowerShell + ```powershell Invoke-WebRequest http://localhost:8080 -UseBasicParsing | Select-Object -ExpandProperty StatusCode # Expect: 200 ``` + - Bash + ```bash curl -s -o /dev/null -w "%{http_code}" http://localhost:8080 # Expect: 200 ``` + ## Hints (if you’re stuck) + - Re-run logs and read the first error: it usually tells you exactly what Nginx didn’t understand. - If the fix doesn’t apply, make sure you recreated the container with `--force-recreate`. - If port 8080 is busy, edit `compose.yaml` and change `8080:80` to another free port (e.g., `8081:80`). - On Windows, if you see file permission issues, temporarily remove `:ro` from the volume lines to test. ## Metrics / Feedback + - Estimated time: 10 minutes - Common pitfalls: wrong compose path; forgetting `--force-recreate` after config changes - Optional next step: write a KB titled “Nginx: fix startup syntax errors” linking this lab ## Bonus challenges (optional) + - Inspect the health status with `docker compose ps` and experiment with failing/healthy states - Explain in one sentence why pinning `nginx:1.27-alpine` improves reproducibility - Change the published port and update your verification command ## Cleanup + ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml down -v ``` + diff --git a/labs/print-queue-stuck.md b/labs/print-queue-stuck.md index 99a6171..a67b9d5 100644 --- a/labs/print-queue-stuck.md +++ b/labs/print-queue-stuck.md @@ -9,25 +9,34 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Simulate a department-wide stuck print queue - Clear the queue and restart the service - Verify a new job processes ## Prerequisites (preflight) + - Docker running - PowerShell or Bash ## Steps + 1) Start the simulated print service (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\print-queue-stuck\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/print-queue-stuck/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\print-queue-stuck\assets\compose.yaml up -d + ``` + + + - Bash + + ```bash + docker compose -f ./labs/print-queue-stuck/assets/compose.yaml up -d + ``` + 2) Submit a job and simulate a stuck queue + ```powershell # submit two jobs docker exec print-queue echo "report-a.pdf" >> /queue/jobs.txt @@ -35,18 +44,23 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo # simulate stuck consumer docker stop print-queue-consumer ``` + 3) Diagnose + ```powershell docker exec print-queue cat /queue/jobs.txt docker compose -f .\labs\print-queue-stuck\assets\compose.yaml ps ``` + 4) Fix + ```powershell # clear the oldest bad job and restart consumer docker exec print-queue sed -i '1d' /queue/jobs.txt docker start print-queue-consumer ``` 5) Verify + ```powershell # remaining job should be processed (file moved to processed.txt) docker exec print-queue cat /queue/processed.txt @@ -59,7 +73,9 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo # Expect: remaining job name present; queue stable ``` + ## Cleanup + ```powershell docker compose -f .\labs\print-queue-stuck\assets\compose.yaml down -v ``` From e67beb734675f6c2de6d1d592fe01a5bf9cd3c2c Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 05:59:48 -0700 Subject: [PATCH 18/27] chore(ci): make PR template markdownlint-compliant (MD022/MD032) - Add blank lines around headings and lists - No content changes --- .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 1540d69..a9bab9f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,13 +1,16 @@ ## Summary + Briefly describe what this PR adds or changes. ## Linked Artifacts (relative paths) + - Ticket(s): /tickets/[file].md - KB: /kb/[file].md - Lab: /labs/[file].md (optional) - Scenario: /scenarios/[file].md (optional) ## Checklists + - Content - [ ] Uses the correct template (copied from 000.*-template.md) - [ ] Clear, reproducible steps and plain language @@ -24,20 +27,25 @@ Briefly describe what this PR adds or changes. - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria ### Labs (if included) + - [ ] Dedicated “Verification” section with expected outputs - [ ] Images pinned if using containers; HTTP services include a simple healthcheck when applicable - [ ] Assets stored under `labs//assets/` ### KBs (if included) + - [ ] Brief (1–2 lines) verification; link to related Lab for full commands ### Scenarios (if included) + - [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) ## Notes + Add screenshots, logs, or context as needed. ## How to Verify (for reviewers) + - Click Related KB/Lab links and confirm they jump to the correct anchors. - If a Lab changed, run the Verification steps and confirm expected outputs. - Check that no personal IPs or credentials are included; use `` placeholders. From 09d3379ffce96c9105aa600aafaf8a6aff89126b Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:04:20 -0700 Subject: [PATCH 19/27] ci(markdownlint): ignore .github/*.md to loosen restrictions for PR templates and meta docs; keep strict rules elsewhere --- .markdownlint-cli2.jsonc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 835920e..a3fbcab 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,6 +1,14 @@ { // Inherit rules from .markdownlint.jsonc and set default globs - "config": ".markdownlint.jsonc", + "config": { + // Extend the base markdownlint rules from repo root + "extends": ".markdownlint.jsonc" + }, "globs": ["**/*.md"], - "ignores": ["**/node_modules/**", ".git/**"] + "ignores": [ + "**/node_modules/**", + ".git/**", + // Loosen restrictions only for repo meta/docs under .github (e.g., PR template) + ".github/**/*.md" + ] } From eb15fda38cdc151e9e6fb3844c4bf0bd54f4aaba Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:20:44 -0700 Subject: [PATCH 20/27] fix(markdownlint): add required blank lines, fix list/fence spacing, and wrap bare URLs across KBs and labs (MD022/MD032/MD031/MD034); fix list indent issues (MD005/MD007) --- kb/README.md | 1 + kb/outlook-reconnect-after-update.md | 6 +++++- kb/printer-queue-clearing.md | 4 ++++ kb/workstation-performance-triage.md | 4 ++++ labs/000.lab-template.md | 12 ++++++++++- labs/htpasswd-auth-reset.md | 32 ++++++++++++++++++---------- labs/mailhog-connectivity.md | 30 +++++++++++++++++--------- 7 files changed, 66 insertions(+), 23 deletions(-) diff --git a/kb/README.md b/kb/README.md index 68233e4..5a93042 100644 --- a/kb/README.md +++ b/kb/README.md @@ -9,6 +9,7 @@ Reusable solution docs derived from tickets and verified in labs. - Cite vendor docs in a References section. Conventions: + - Filename in kebab-case (e.g., `printer-spooler-restart.md`). - Include a short metadata block (category, environment, owner). - Link back to the originating ticket and any validating lab. diff --git a/kb/outlook-reconnect-after-update.md b/kb/outlook-reconnect-after-update.md index c22f939..4c8c527 100644 --- a/kb/outlook-reconnect-after-update.md +++ b/kb/outlook-reconnect-after-update.md @@ -11,22 +11,26 @@ **Next Review Due:** 2026-03-28 ## Resolution Steps + 1. Validate user credentials on another system (SSO/portal) to rule out auth failure. 2. Check VPN/Network connectivity (if remote): ensure stable connection. 3. Toggle Cached Exchange Mode (disable → enable) and restart Outlook. 4. Clear Windows Credential Manager entries for Office/Outlook; restart Outlook. 5. If needed, create a new Outlook profile (Control Panel → Mail → Profiles). -6. Verification: Outlook shows Connected; send/receive works. In lab, MailHog captures a test message at http://localhost:8025/. +6. Verification: Outlook shows Connected; send/receive works. In lab, MailHog captures a test message at . ## Troubleshooting Notes + - After updates, Autodiscover or token cache can cause loops; clearing credentials/profile often resolves. - If organization-wide, check Exchange/identity provider status and service health. - Logs: Windows Event Viewer → Application (Outlook), Office logs. ## Linked Incidents + - /tickets/outlook-disconnected-password-prompts.md ## Metrics / References + - MTTR: TBD - Recurrence: TBD - External reference: Microsoft Docs (Outlook connectivity, Autodiscover) diff --git a/kb/printer-queue-clearing.md b/kb/printer-queue-clearing.md index 78f2eef..354f48e 100644 --- a/kb/printer-queue-clearing.md +++ b/kb/printer-queue-clearing.md @@ -11,6 +11,7 @@ **Next Review Due:** 2026-03-28 ## Resolution Steps + 1. Confirm scope: multiple users affected implies server-side issue. 2. On server: open Print Management; check the queue; cancel the oldest/large stuck job. 3. Restart the Print Spooler service (Services.msc or `net stop spooler` / `net start spooler`). @@ -18,14 +19,17 @@ 5. Verification: new test job prints; in lab, remaining job is processed and queue shows steady state. ## Troubleshooting Notes + - Ensure correct driver model on server (Type 3/4) and clients. - Watch for mis-sized PDFs or offline ports. - If department-wide and persistent, check network path to printer, SNMP status, or firmware. ## Linked Incidents + - /tickets/cannot-print-to-shared-printer.md ## Metrics / References + - MTTR: TBD - Recurrence: TBD - External reference: Microsoft Docs (Print Management); Vendor printer admin guide diff --git a/kb/workstation-performance-triage.md b/kb/workstation-performance-triage.md index d43ba09..f3ec712 100644 --- a/kb/workstation-performance-triage.md +++ b/kb/workstation-performance-triage.md @@ -11,6 +11,7 @@ **Next Review Due:** 2026-03-28 ## Resolution Steps + 1. Differentiate network vs local: ping internal resource vs external site. 2. Check Task Manager for CPU/RAM/Disk spikes; identify culprit process. 3. Remediate: stop runaway task; reschedule AV scans/OneDrive sync; check Windows Update. @@ -18,14 +19,17 @@ 5. Verification: CPU/Disk usage normalizes; common actions (open browser/drive) are fast; in lab, top shows normal usage. ## Troubleshooting Notes + - If only company site is slow, escalate to web/app owners. - Confirm no VPN tunnel conflicts or DNS issues. - Capture before/after metrics if possible for MTTR. ## Linked Incidents + - /tickets/computer-running-slow-lagging.md ## Metrics / References + - MTTR: TBD - Recurrence: TBD - External reference: Microsoft Docs (Performance troubleshooting), vendor AV scheduling docs diff --git a/labs/000.lab-template.md b/labs/000.lab-template.md index b6d3257..7634729 100644 --- a/labs/000.lab-template.md +++ b/labs/000.lab-template.md @@ -9,31 +9,41 @@ **Next Review Due:** [YYYY-MM-DD] ## Objectives + - [Skill or goal, e.g., "Learn to diagnose and fix a failed print service"] ## Prerequisites + - [Setup, e.g., "Ubuntu 24.04 VM with CUPS installed"] - [Credentials, e.g., "User with sudo access"] ## Steps + 1. [Instruction, e.g., "Simulate a failure: sudo systemctl stop "] 2. [Instruction, e.g., "Check service status: sudo systemctl status "] 3. [Command, e.g.,] - `sudo systemctl restart ` + + ```bash + sudo systemctl restart + ``` ## Verification + - [Expected outcome, e.g., "Run lpstat -p; confirm printer is enabled"] - [Pass condition, e.g., "Test page prints successfully"] - [Fail condition, e.g., "Error: ‘printer not found’"] ## Escalation Context + - [If lab fails, e.g., "Check /var/log//error_log and escalate to Tier 2 if driver issues persist. See ROLES.md"] ## Metrics / Feedback + - Estimated time to complete: [e.g., "15 minutes"] - Common errors: [e.g., "‘ not found’ ( not installed)"] - Links: [/tickets/[incident].md or /scenarios/[scenario].md] ## Cleanup + - [Reset steps, e.g., "Restart service: sudo systemctl start "] - [Ensure readiness, e.g., "Verify service status with systemctl status "] diff --git a/labs/htpasswd-auth-reset.md b/labs/htpasswd-auth-reset.md index 72adc62..c2c0c0e 100644 --- a/labs/htpasswd-auth-reset.md +++ b/labs/htpasswd-auth-reset.md @@ -9,33 +9,42 @@ Simulate a credential reset and prove the fix with a protected endpoint. **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Protect a page with HTTP Basic Auth - Reset the password and verify access ## Prerequisites + - Docker running - PowerShell or Bash ## Steps + 1) Start stack (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/htpasswd-auth-reset/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml up -d + ``` + + - Bash + + ```bash + docker compose -f ./labs/htpasswd-auth-reset/assets/compose.yaml up -d + ``` 2) Try accessing (expect auth required) + ```powershell Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = ("Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("user:wrong"))) } | Select-Object -ExpandProperty StatusCode # Expect 401/403 ``` 3) Reset password + ```powershell docker exec htpasswd sh -lc "htpasswd -b /auth/.htpasswd user newpass" ``` 4) Verify access succeeds + ```powershell $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode @@ -45,12 +54,13 @@ Simulate a credential reset and prove the fix with a protected endpoint. ## Verification ```powershell - $pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); - Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode - # Expect: 200 +$pair = "user:newpass"; $b64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair)); +Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = "Basic $b64" } | Select-Object -ExpandProperty StatusCode +# Expect: 200 ``` ## Cleanup + ```powershell docker compose -f .\labs\htpasswd-auth-reset\assets\compose.yaml down -v ``` diff --git a/labs/mailhog-connectivity.md b/labs/mailhog-connectivity.md index 8699374..d884587 100644 --- a/labs/mailhog-connectivity.md +++ b/labs/mailhog-connectivity.md @@ -9,41 +9,50 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives + - Stand up a local SMTP sink and web UI - Simulate disconnect by stopping service / changing port - Verify send/receive via test message ## Prerequisites + - Docker running - PowerShell or Bash ## Steps + 1) Start MailHog (from repo root) - - PowerShell - ```powershell - docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml up -d - ``` - - Bash - ```bash - docker compose -f ./labs/mailhog-connectivity/assets/compose.yaml up -d - ``` + - PowerShell + + ```powershell + docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml up -d + ``` + + - Bash + + ```bash + docker compose -f ./labs/mailhog-connectivity/assets/compose.yaml up -d + ``` 2) Check status + ```powershell docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml ps - # UI at http://localhost:8025 + # UI at ``` 3) Send a test message + ```powershell docker exec mailhog bash -lc "echo -e 'HELO test\nMAIL FROM:\nRCPT TO:\nDATA\nSubject: hello\n\nmailhog test\n.\nQUIT' | nc 127.0.0.1 1025" ``` 4) Simulate disconnect and recover + ```powershell docker stop mailhog # expect UI down; restart docker start mailhog ``` 5) Verify in UI - - Browse http://localhost:8025 and confirm the message is present. + - Browse and confirm the message is present. ## Verification @@ -53,6 +62,7 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. ``` ## Cleanup + ```powershell docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml down -v ``` From 4788f69b747b250d5f730d239cc78929bc136a3f Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:37:42 -0700 Subject: [PATCH 21/27] style(markdownlint): allow incrementing ordered lists (MD029 style: ordered) to reduce churn --- .markdownlint.jsonc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 83e3844..6187e9d 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -10,5 +10,7 @@ // Allow non-heading first lines (some files are not articles) "MD041": false, // Temporarily disable strict fragment validation to reduce false positives on deep-links - "MD051": false + "MD051": false, + // Prefer incrementing ordered lists (1/2/3) to avoid renumbering churn + "MD029": { "style": "ordered" } } From dbc87ca10688da5bc8d20c5126a795d94910406c Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:51:25 -0700 Subject: [PATCH 22/27] fix(markdownlint): spacing around headings/lists/fences and minor list indent; allow ordered lists (MD029) via config - Convert bold-only pseudo-headings to proper headings where applicable (MD036) - Ensure blank lines around code fences (MD031), lists (MD032), and headings (MD022) - Normalize top-level list indentation (MD007) --- .github/PULL_REQUEST_TEMPLATE.md | 15 +- .github/copilot-instructions.md | 11 +- CONTRIBUTING.md | 102 +++++++----- README.md | 52 +++--- docs/METRICS.md | 32 ++-- docs/ROLES.md | 25 +-- docs/lamp-osticket-setup.md | 152 +++++++++++++----- kb/000.kb-template.md | 7 +- kb/README.md | 2 +- kb/account-lockout-reset.md | 36 +++-- kb/outlook-reconnect-after-update.md | 42 ++--- kb/printer-queue-clearing.md | 38 ++--- kb/workstation-performance-triage.md | 38 ++--- labs/000.lab-template.md | 52 +++--- labs/README.md | 2 +- labs/htpasswd-auth-reset.md | 13 +- labs/mailhog-connectivity.md | 14 +- labs/nginx-startup-fail.md | 42 +++-- labs/print-queue-stuck.md | 13 +- labs/resource-spike-triage.md | 2 +- scenarios/000.scenario-template.md | 4 +- scenarios/README.md | 4 +- scenarios/account-lockout-reset.md | 2 +- scenarios/outlook-reconnect-after-update.md | 2 +- scenarios/printer-queue-clearing.md | 2 +- scenarios/workstation-performance-triage.md | 2 +- tickets/000.ticket-template.md | 2 +- tickets/README.md | 4 +- tickets/account-locked-out.md | 9 +- tickets/cannot-print-to-shared-printer.md | 9 +- tickets/computer-running-slow-lagging.md | 5 +- .../outlook-disconnected-password-prompts.md | 7 +- 32 files changed, 434 insertions(+), 308 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a9bab9f..5d10491 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ -## Summary +## Summary Briefly describe what this PR adds or changes. @@ -16,29 +16,29 @@ Briefly describe what this PR adds or changes. - [ ] Clear, reproducible steps and plain language - [ ] Relative links resolve inside the repo - [ ] Avoid duplication across modules (KB = productized steps; Lab = full commands + Verification; Scenario = flow/success, links only) - - [ ] Deep link to sections where applicable (KB → #resolution-steps, Lab → #verification) + - [ ] Deep link to sections where applicable (KB → #resolution-steps, Lab → #verification) - Metadata - [ ] Owner set; Last Reviewed and Next Review Due (KB/Lab) - [ ] Escalation Path filled (Ticket) - [ ] Metrics block added if useful (see docs/METRICS.md) - Quality - [ ] Verification steps included (expected outputs / pass-fail) - - [ ] Anchors exist and resolve (KB “Resolution Steps”, Lab “Verification”) - - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria + - [ ] Anchors exist and resolve (KB “Resolution Steps”, Lab “Verification”) + - [ ] Scenario (if present) ties Ticket → KB → Lab and defines success criteria ### Labs (if included) -- [ ] Dedicated “Verification” section with expected outputs +- [ ] Dedicated “Verification” section with expected outputs - [ ] Images pinned if using containers; HTTP services include a simple healthcheck when applicable - [ ] Assets stored under `labs//assets/` ### KBs (if included) -- [ ] Brief (1–2 lines) verification; link to related Lab for full commands +- [ ] Brief (1–2 lines) verification; link to related Lab for full commands ### Scenarios (if included) -- [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) +- [ ] Uses deep links to KB “Resolution Steps” and Lab “Verification” (no step duplication) ## Notes @@ -49,3 +49,4 @@ Add screenshots, logs, or context as needed. - Click Related KB/Lab links and confirm they jump to the correct anchors. - If a Lab changed, run the Verification steps and confirm expected outputs. - Check that no personal IPs or credentials are included; use `` placeholders. + diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fceefc7..1239640 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,4 +1,4 @@ -# Copilot Instructions for DeskForge-Simulator +# Copilot Instructions for DeskForge-Simulator This repo simulates real helpdesk workflows using Markdown contributions. Agents should prioritize clarity, reproducibility, and alignment with the troubleshooting standards in `CONTRIBUTING.md`. @@ -8,7 +8,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents - Tickets (`/tickets/`): user-reported issues - Knowledge Base (`/kb/`): solution docs derived from tickets - Labs (`/labs/`): hands-on practice exercises - - Scenarios (`/scenarios/`): end-to-end flows linking ticket → KB → lab + - Scenarios (`/scenarios/`): end-to-end flows linking ticket → KB → lab - Use templates in each folder (`000.*-template.md`). ## Key Files @@ -21,7 +21,7 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents ## Authoring Patterns -- Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. +- Follow CompTIA A+ 6-step model: Identify → Theory → Test → Plan/Implement → Verify → Document. - Keep language plain and steps reproducible. Include environment details (OS/version), verification, and escalation path. - Link artifacts with relative paths (e.g., `/tickets/printer-failure.md` in KB/Lab/Scenario). - Use checklists for Tier 1/2/3 completion; mark what you actually did. @@ -49,8 +49,9 @@ This repo simulates real helpdesk workflows using Markdown contributions. Agents ## What NOT to do -- Don’t invent infrastructure or public endpoints; this repo is markdown-only. -- Don’t add personal IPs or credentials. +- Don’t invent infrastructure or public endpoints; this repo is markdown-only. +- Don’t add personal IPs or credentials. --- Clarifications welcome: if any folder structure or template changes, update this file to match. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43c8ab2..3334c99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,30 @@ -# Contributing to DeskForge-Simulator (Beginner-Friendly Guide) +# Contributing to DeskForge-Simulator (Beginner-Friendly Guide) -Welcome to **DeskForge-Simulator**! This project simulates real-world helpdesk workflows, guiding you through creating tickets, troubleshooting issues, writing knowledge base (KB) articles, and building labs. Whether you’re new to IT or an experienced pro, we’re excited to have you contribute! +Welcome to **DeskForge-Simulator**! This project simulates real-world helpdesk workflows, guiding you through creating tickets, troubleshooting issues, writing knowledge base (KB) articles, and building labs. Whether you’re new to IT or an experienced pro, we’re excited to have you contribute! This guide provides **guidelines** (not strict rules) for contributing to DeskForge-Simulator. Use your best judgment and suggest improvements via pull requests. **Note**: Setting up a local osTicket instance is **optional** but recommended to learn how ticketing systems work in real-world IT jobs (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md)). You can contribute by writing Markdown files directly or sharing real-world tech support issues, KB drafts, or labs via GitHub Discussions. -## What You’ll Need +## What You’ll Need + - A GitHub account to submit contributions (sign up at [github.com](https://github.com)). - A text editor for writing Markdown files in `/tickets/`, `/kb/`, and `/labs/` (we provide templates!). -- **Optional**: A local osTicket setup to test tickets and KB articles (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) for installing osTicket v1.18.1 in a VirtualBox VM with Ubuntu 24.04 Desktop; client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +- **Optional**: A local osTicket setup to test tickets and KB articles (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) for installing osTicket v1.18.1 in a VirtualBox VM with Ubuntu 24.04 Desktop; client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - For labs: A lightweight Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container) to test troubleshooting steps, which can be the same VM as osTicket or a separate one. -- Curiosity and a willingness to learn—no IT expertise required! +- Curiosity and a willingness to learn—no IT expertise required! ## Contribution Workflow + To keep contributions organized, use the following channels: + - **GitHub Discussions ([https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions))**: - **Tickets**: Share real-world tech support issues, fictional scenarios, or training exercises in the `Tickets` category. Convert these into Markdown files for `/tickets/`. - **Knowledge Base**: Share KB drafts or solution ideas in the `Knowledge Base` category. Convert these into Markdown files for `/kb/`. - **Labs**: Share lab ideas or troubleshooting exercises in the `Labs` category. Convert these into Markdown files for `/labs/`. - - **Scenarios & General**: Discuss end-to-end workflows (Ticket → KB → Lab) or general Q&A in the `Scenarios & General` category. + - **Scenarios & General**: Discuss end-to-end workflows (Ticket → KB → Lab) or general Q&A in the `Scenarios & General` category. - **GitHub Issues ([https://github.com/iplaycomputer/DeskForge-Simulator/issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues))**: - Report project-related problems (e.g., bugs, broken setup instructions in `lamp-osticket-setup.md`, missing dependencies). - **Pull Requests**: Submit your final Markdown files (`/tickets/`, `/kb/`, `/labs/`, `/scenarios/`) as pull requests for review. @@ -31,7 +34,9 @@ To keep contributions organized, use the following channels: This keeps Discussions for collaboration and learning, Issues for project fixes, and the repo clean with structured contributions. ## What This Guide Does + This guide will help you: + - Write tickets, KB articles, and labs in Markdown for the DeskForge-Simulator repo. - Share tickets, KB drafts, or labs via GitHub Discussions or test them in a local osTicket instance. - Test labs in a Linux VM or sandbox environment without needing osTicket. @@ -39,6 +44,7 @@ This guide will help you: - Use community resources to ask questions and get help. ## Table of Contents + 1. [Code of Conduct](#code-of-conduct) 2. [I Have a Question!](#i-have-a-question) 3. [Troubleshooting Philosophy](#troubleshooting-philosophy) @@ -52,52 +58,60 @@ This guide will help you: 7. [Roadmap Note](#roadmap-note) ## Code of Conduct + We want DeskForge-Simulator to be a welcoming, respectful, and professional community. By contributing, you agree to follow the **DeskForge Code of Conduct**, which emphasizes: + - Respectful communication. - Collaboration and inclusivity. - Professional behavior. If you encounter unacceptable behavior, report it via GitHub issues or by contacting the maintainers directly. -## I Have a Question! -Don’t file a GitHub issue for general questions—you’ll get faster answers in the `Scenarios & General` category of [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). Other resources: +## I Have a Question + +Don’t file a GitHub issue for general questions—you’ll get faster answers in the `Scenarios & General` category of [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). Other resources: + - **[r/helpdesk on Reddit](https://reddit.com/r/helpdesk)**: Share and learn from real-world troubleshooting stories. - **[Spiceworks Community](https://community.spiceworks.com/)**: Connect with IT pros for tips and best practices. - **[Microsoft TechNet Forums](https://docs.microsoft.com/en-us/answers/products/)**: Get help with OS, networking, or enterprise issues. - **[Stack Overflow](https://stackoverflow.com/)**: Ask programming or script-related questions. ## Troubleshooting Philosophy + DeskForge-Simulator follows industry-standard helpdesk practices to ensure contributions are clear, professional, and useful. When writing tickets, KB articles, or labs, align with these principles: | Principle | Description | Reference | |-----------|-------------|-----------| | **Clear communication** | Use simple, step-by-step instructions and plain language in tickets and KB articles. | Blokdyk, 2020 | -| **User focus & empathy** | Include technical details and the user’s experience (e.g., what they see, how it affects them). | Blokdyk, 2020; Art of Service, 2021 | -| **Structured troubleshooting** | Follow the CompTIA A+ six-step diagnostic model:
1. Identify the problem
2. Establish a theory of probable cause
3. Test the theory
4. Establish a plan and implement the solution
5. Verify functionality
6. Document findings, actions, and outcomes | O’Shea, 2025 | +| **User focus & empathy** | Include technical details and the user’s experience (e.g., what they see, how it affects them). | Blokdyk, 2020; Art of Service, 2021 | +| **Structured troubleshooting** | Follow the CompTIA A+ six-step diagnostic model:
1. Identify the problem
2. Establish a theory of probable cause
3. Test the theory
4. Establish a plan and implement the solution
5. Verify functionality
6. Document findings, actions, and outcomes | O’Shea, 2025 | | **Escalation & scope** | Know when an issue needs higher-level support and document the escalation path. | Art of Service, 2021 | | **Consistency** | Use standard templates for tickets, KB articles, and labs to keep things uniform. | Blokdyk, 2020 | | **Metrics & improvement** | Track resolution times and root causes to improve the helpdesk process. | Art of Service, 2021 | | **Knowledge management** | Turn solved tickets into KB articles or labs to prevent repeat issues. | Blokdyk, 2020; Art of Service, 2021 | ### References -- *Help Desk: A Complete Guide – 2020 Edition* (Gerardus Blokdyk, ISBN 978-1867309383) -- *CompTIA A+ Complete Practice Tests, 4th Edition* (Audrey O’Shea, 2025, Print ISBN 978-1394330331; eText ISBN 978-1394330348) + +- *Help Desk: A Complete Guide – 2020 Edition* (Gerardus Blokdyk, ISBN 978-1867309383) +- *CompTIA A+ Complete Practice Tests, 4th Edition* (Audrey O’Shea, 2025, Print ISBN 978-1394330331; eText ISBN 978-1394330348) - *IT Service Desk: A Complete Guide, 2021 Edition* (The Art of Service, ISBN 978-1867437223) - [Atlassian: What Is ITIL? Best Practices for ITSM](https://www.atlassian.com/itsm) ## What Should I Know Before I Get Started? -DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute tickets, KB articles, and labs in Markdown. Testing tickets and KB articles in a local osTicket instance is optional but recommended to understand how ticketing systems work in real-world IT jobs. Here’s what you need to know: -- **GitHub Basics**: If you’re new to GitHub, check out [Contributing to a Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) to learn about forking, branching, committing, and pull requests. -- **Helpdesk Skills**: You don’t need to be an expert! Focus on: +DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute tickets, KB articles, and labs in Markdown. Testing tickets and KB articles in a local osTicket instance is optional but recommended to understand how ticketing systems work in real-world IT jobs. Here’s what you need to know: + +- **GitHub Basics**: If you’re new to GitHub, check out [Contributing to a Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) to learn about forking, branching, committing, and pull requests. +- **Helpdesk Skills**: You don’t need to be an expert! Focus on: - Clear communication with non-technical users. - Basic troubleshooting (e.g., OS, hardware, network issues). - Following templates and asking questions to clarify issues. -- **osTicket Setup (Optional)**: For a hands-on ticketing system experience, set up a local osTicket instance using [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) (client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +- **osTicket Setup (Optional)**: For a hands-on ticketing system experience, set up a local osTicket instance using [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) (client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - **Lab Testing**: Test labs in a local Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container), which can be the same VM as osTicket or a separate one. osTicket is not required for labs. - **Learning by Doing**: The best way to learn is to write tickets, test solutions, and get feedback. Start small and improve with each contribution! ## DeskForge Modules + DeskForge-Simulator is built around four modules that mirror real helpdesk workflows: | Module | Path | Purpose | @@ -107,37 +121,42 @@ DeskForge-Simulator is built around four modules that mirror real helpdesk workf | **Labs** | `/labs/` | Hands-on troubleshooting exercises, tested in a Linux VM or sandbox, written in Markdown and shared via GitHub Discussions. | | **Scenarios** | `/scenarios/` | End-to-end workflows combining tickets, KB articles, and labs, written in Markdown. | -Folder guides for quick navigation: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Labs](labs/README.md) · [Scenarios](scenarios/README.md) +Folder guides for quick navigation: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Labs](labs/README.md) · [Scenarios](scenarios/README.md) Roles (to avoid duplication): + - Labs are the canonical source of exact commands and environment setup. Always put full commands in Labs and include a small "Verification" section. -- KBs contain productized resolution steps with 1–2 verification lines (max). Link to the Lab for full commands. +- KBs contain productized resolution steps with 1–2 verification lines (max). Link to the Lab for full commands. - Scenarios define the flow and success criteria; they should link to specific sections in the KB (Resolution Steps) and Lab (Verification) rather than restating steps. ### How Modules Work Together -Contributions flow like this: **Ticket → Resolution → KB → Lab → Scenario**. -- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). -Optionally, test it in your local osTicket instance’s client portal (`http:///osticket/`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +Contributions flow like this: **Ticket → Resolution → KB → Lab → Scenario**. -- **KB Articles**: Share a KB draft in GitHub Discussions (`Knowledge Base` category) or write a Markdown file in `/kb/` formalizing the solution (e.g., “How to restart the Print Spooler”). Optionally, test it in your local osTicket instance’s admin/staff panel (`http:///osticket/scp`). +- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). + +Optionally, test it in your local osTicket instance’s client portal (`http:///osticket/`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. + +- **KB Articles**: Share a KB draft in GitHub Discussions (`Knowledge Base` category) or write a Markdown file in `/kb/` formalizing the solution (e.g., “How to restart the Print Spooler”). Optionally, test it in your local osTicket instance’s admin/staff panel (`http:///osticket/scp`). - **Labs**: Share a lab idea in GitHub Discussions (`Labs` category) or write a Markdown file in `/labs/` for a hands-on exercise, tested in a Linux VM or sandbox. - **Scenarios**: Combine tickets, KB articles, and labs into a complete workflow in `/scenarios/`. ## How Can I Contribute? + You can contribute by writing tickets, KB articles, or labs in Markdown, sharing them via GitHub Discussions, or testing tickets/KB articles in a local osTicket instance. Below are the details for each. ### Submitting Tickets + Tickets represent user-reported problems (real, training, or fictional). You can share them in GitHub Discussions, write them directly in Markdown for `/tickets/`, or test them in a local osTicket instance for realism. -- **Option 1: GitHub Discussions**: Post a ticket in the `Tickets` category at [https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) with details of a real-world tech support issue (e.g., “My laptop won’t connect to Wi-Fi”). Convert the details into the Markdown template and save in `/tickets/`. +- **Option 1: GitHub Discussions**: Post a ticket in the `Tickets` category at [https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) with details of a real-world tech support issue (e.g., “My laptop won’t connect to Wi-Fi”). Convert the details into the Markdown template and save in `/tickets/`. - **Option 2: Direct Markdown**: Write a ticket in the Markdown template below and save it in `/tickets/`. -- **Option 3: Local osTicket (Recommended for Learning)**: Access your local client portal (e.g., `http:///osticket/`), click “Open a New Ticket,” select a help topic (e.g., “Hardware”), and submit. Configure help topics in the admin panel (e.g., `http:///osticket/scp`, Admin Panel → Manage → Help Topics). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. Copy the ticket details into the Markdown template. +- **Option 3: Local osTicket (Recommended for Learning)**: Access your local client portal (e.g., `http:///osticket/`), click “Open a New Ticket,” select a help topic (e.g., “Hardware”), and submit. Configure help topics in the admin panel (e.g., `http:///osticket/scp`, Admin Panel → Manage → Help Topics). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. Copy the ticket details into the Markdown template. -- **Example**: For a “Unable to print” issue, post in GitHub Discussions (`Tickets` category) with details, write `/tickets/printer-failure.md` directly, or test it in your local osTicket instance and document it in `/tickets/`. +- **Example**: For a “Unable to print” issue, post in GitHub Discussions (`Tickets` category) with details, write `/tickets/printer-failure.md` directly, or test it in your local osTicket instance and document it in `/tickets/`. - **Inspiration**: Browse existing examples in the `/tickets/` folder and the `Tickets` category in Discussions. - **Roles**: See [docs/ROLES.md](docs/ROLES.md) for tiers and escalation patterns. - **Metrics**: See [docs/METRICS.md](docs/METRICS.md) for lightweight fields to add to Tickets/KBs. @@ -147,32 +166,37 @@ Template: copy `/tickets/000.ticket-template.md` to `/tickets/.md` a Folder guide: see [tickets/README.md](tickets/README.md) **Tips**: -- Use GitHub Discussions (`Tickets` category) to share real-world tech support issues you’ve encountered. + +- Use GitHub Discussions (`Tickets` category) to share real-world tech support issues you’ve encountered. - Test tickets in your local osTicket instance (if set up) to simulate a real helpdesk. -- Follow the CompTIA A+ six-step model (see “Troubleshooting Philosophy”). +- Follow the CompTIA A+ six-step model (see “Troubleshooting Philosophy”). - Submit your ticket as a pull request in the `/tickets/` folder. ### Creating KB Articles -KB articles document solutions from solved tickets. Share them in GitHub Discussions (`Knowledge Base` category) or write them in Markdown for `/kb/`. Optionally, test them in your local osTicket instance’s admin/staff panel. + +KB articles document solutions from solved tickets. Share them in GitHub Discussions (`Knowledge Base` category) or write them in Markdown for `/kb/`. Optionally, test them in your local osTicket instance’s admin/staff panel. Template: copy `/kb/000.kb-template.md` to `/kb/.md` and complete the fields. Folder guide: see [kb/README.md](kb/README.md) **Tips**: + - Share KB drafts in GitHub Discussions (`Knowledge Base` category) for feedback. -- Use your local osTicket admin/staff panel (e.g., `http:///osticket/scp`) to draft KB articles, if set up. Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +- Use your local osTicket admin/staff panel (e.g., `http:///osticket/scp`) to draft KB articles, if set up. Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - Ensure steps are clear, reproducible, and tested. -- Keep verification concise (1–2 lines). For full commands and environment, link to the related Lab. +- Keep verification concise (1–2 lines). For full commands and environment, link to the related Lab. - Submit as a pull request in the `/kb/` folder. ### Creating Labs + Labs are standalone troubleshooting exercises in `/labs/`, tested in a Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container), not requiring osTicket. Share them in GitHub Discussions (`Labs` category) or write them in Markdown. **Testing Labs**: Use a local Linux VM or sandbox to simulate issues (e.g., stop a service with `sudo systemctl stop `). Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up a VM, or use a Docker container for simplicity. Template: copy `/labs/000.lab-template.md` to `/labs/.md` and follow the structure. **Tips**: + - Share lab ideas in GitHub Discussions (`Labs` category) for feedback. - Test labs in a Linux VM or Docker container, not osTicket. - Include a dedicated "Verification" section with specific commands/outputs (Labs are the source of truth for commands). @@ -181,32 +205,30 @@ Template: copy `/labs/000.lab-template.md` to `/labs/.md` and follow Folder guide: see [labs/README.md](labs/README.md) ### Creating Scenarios -Scenarios stitch together one or more tickets, a KB article, and an optional lab into an end-to-end learning flow. Use them to show how a real incident moves from report → resolution → documentation → practice. -**When to create a scenario** +Scenarios stitch together one or more tickets, a KB article, and an optional lab into an end-to-end learning flow. Use them to show how a real incident moves from report → resolution → documentation → practice. +## When to create a scenario - You have at least one ticket and a corresponding KB article; a lab is recommended but optional. - You want a guided narrative that learners can follow front-to-back. - -**How to author** +## How to author - Start from the template at `/scenarios/000.scenario-template.md`. - Create a new file under `/scenarios/`, e.g. `/scenarios/printer-outage-end-to-end.md`. - Fill in: - Related Ticket(s): link to one or more tickets, e.g. `/tickets/printer-failure.md`. - Related KB: link to your KB, e.g. `/kb/printer-spooler-restart.md`. - Related Lab: link if you have one, e.g. `/labs/restart-print-spooler.md`. - - Overview, Flow (Ticket → KB → Lab), Success Criteria. - -**Submission** + - Overview, Flow (Ticket → KB → Lab), Success Criteria. +## Submission - Open a PR with the new scenario file in `/scenarios/`. - In your PR description, briefly summarize the learning goals and link the related ticket/KB/lab. Folder guide: see [scenarios/README.md](scenarios/README.md) - -**Tips** +## Tips - Keep links relative so they work in GitHub and downstream clones. - Be explicit about pass/fail checks so learners can self-verify. - Prefer deep links to existing sections instead of rewriting steps, e.g.: `/kb/...#resolution-steps` and `/labs/...#verification`. - ## Roadmap Note + Public ticket submissions are not yet enabled. If a central osTicket instance is launched, it will likely allow public users to submit tickets via the client portal only, with the admin/staff panel restricted to maintainers. + diff --git a/README.md b/README.md index ef45df0..a58e337 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

Last commit @@ -18,22 +18,22 @@ # DeskForge-Simulator -**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. +**DeskForge-Simulator** is an open-source project that recreates the experience of working on a real IT helpdesk — but in a safe, collaborative learning environment. -It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: +It’s designed for **beginners exploring IT support** as well as **experienced contributors who want to practice professional workflows**. By contributing, you’ll gain hands-on experience with the same skills used in real service desk roles: -- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. -- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. -- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. -- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. +- 🎫 **Submitting and triaging tickets** — learn to capture user issues, categorize problems, and document troubleshooting steps. +- 📚 **Writing and refining knowledge base (KB) articles** — transform solved tickets into reusable documentation that helps prevent repeat issues. +- 🧪 **Building troubleshooting labs** — create interactive exercises that let others practice resolving common IT incidents. +- 🌐 **Practicing escalation paths and IT workflows** — follow industry-standard processes like the CompTIA A+ six-step troubleshooting model and learn when to escalate issues. -💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. +💡 Think of it as a **helpdesk-in-a-repo**: instead of just reading about IT support, you actively practice it — using tickets, KBs, and labs that mirror real-world scenarios. -Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. +Whether you’re completely new to IT, sharpening your troubleshooting skills, or mentoring others, DeskForge-Simulator gives you a structured, low-stakes environment to learn, contribute, and grow. -⭐ If you find **DeskForge-Simulator** useful, please give this project a **star** on GitHub — it helps the community grow and keeps the project alive! +⭐ If you find **DeskForge-Simulator** useful, please give this project a **star** on GitHub — it helps the community grow and keeps the project alive! -## 🔰 Quick Start: Contribute in 5 Minutes +## 🔰 Quick Start: Contribute in 5 Minutes 1. **Fork** this repository and clone it to your machine. @@ -57,45 +57,45 @@ Whether you’re completely new to IT, sharpening your troubleshooting skills, o git push origin main ``` -4. **Open a Pull Request** to share your contribution! 🎉 +4. **Open a Pull Request** to share your contribution! 🎉 -👉 That’s it — you’ve added your first simulated helpdesk ticket. +👉 That’s it — you’ve added your first simulated helpdesk ticket. Check out `CONTRIBUTING.md` if you want to go deeper (KB articles, labs, scenarios). ### **Note on Real Troubleshooting** -You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. +You’re welcome to post **real tech support questions** (e.g., “my printer won’t connect” or “Windows update keeps failing”) in GitHub Discussions. *This community will treat them as learning scenarios.* However: -- This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. +- This project is for **education only** — responses are not official IT support. This means no guarantees of fixes and we are not responsible for people's devices. - Please **do not share sensitive information** (personal IPs, passwords, or private configs). - Use advice at your own discretion. Think of it as a safe space to learn troubleshooting together, not a replacement for your workplace or vendor IT support. -## 🚀 Documentation & osTicket +## 🚀 Documentation & osTicket - Follow [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) to set up an optional **local osTicket instance** on Ubuntu 24.04 (for realism). - Or start contributing right away using **GitHub Discussions** and Markdown files in `/tickets/`, `/kb/`, and `/labs/`. - See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for templates and workflow details. - For end-to-end flows, see the `/scenarios/` folder and use the template at `/scenarios/000.scenario-template.md`. - Browse available labs in the [Labs Catalog](labs/README.md). -- Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) +- Explore folder guides: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Scenarios](scenarios/README.md) -## ❤️ Community & Contributions +## ❤️ Community & Contributions DeskForge-Simulator is **community-driven**. We welcome: -- 🐞 Bug reports and fixes -- ✨ New tickets, KB articles, and labs -- 📖 Documentation improvements -- 💡 Ideas for scenarios or learning modules +- 🐞 Bug reports and fixes +- ✨ New tickets, KB articles, and labs +- 📖 Documentation improvements +- 💡 Ideas for scenarios or learning modules Check out the [CONTRIBUTING.md](CONTRIBUTING.md) guide and join the conversation in [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). -## 📫 Questions & Support +## 📫 Questions & Support Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) to: @@ -104,13 +104,13 @@ Use [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/di - Share lab walkthroughs - Ask general IT or project-related questions -## 🤝 Found a Bug? Missing a Feature? +## 🤝 Found a Bug? Missing a Feature? - File issues here: [DeskForge-Simulator Issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues) -- Open a pull request if you’ve already got a fix or draft +- Open a pull request if you’ve already got a fix or draft - See [CONTRIBUTING.md](CONTRIBUTING.md) for coding/writing standards -## ✅ Requirements +## ✅ Requirements - GitHub account (to contribute) - Text editor (for Markdown tickets, KBs, labs) diff --git a/docs/METRICS.md b/docs/METRICS.md index ef9d78c..659cf3a 100644 --- a/docs/METRICS.md +++ b/docs/METRICS.md @@ -1,8 +1,9 @@ -# Helpdesk Metrics (Lightweight) +# Helpdesk Metrics (Lightweight) Use simple, repeatable fields so contributors can track quality without heavy tooling. Add these to Tickets and KBs when helpful. ## Ticket Metrics + - Reported: YYYY-MM-DD - Resolved: YYYY-MM-DD (or TBD) - MTTR (mins): (Resolved - Reported) @@ -10,35 +11,40 @@ Use simple, repeatable fields so contributors can track quality without heavy to - Affected Users: 1 | few | many Example block for tickets: + ```markdown -**Metrics:** -- Reported: 2025-09-26 -- Resolved: 2025-09-26 -- MTTR (mins): 12 -- Recurrence: No -- Affected Users: 1 +## Metrics: +- Reported: 2025-09-26 +- Resolved: 2025-09-26 +- MTTR (mins): 12 +- Recurrence: No +- Affected Users: 1 ``` ## KB Metrics + - Verification Date: YYYY-MM-DD - Verified By: @handle - Validated Against: OS/App version(s) - Recurrence Notes: When to apply or retire Example block for KBs: + ```markdown -**Metrics / Verification:** -- Verification Date: 2025-09-26 -- Verified By: @your-handle -- Validated Against: Windows 11 23H2, HP LaserJet Pro -- Recurrence Notes: Common after major Windows updates +## Metrics / Verification: +- Verification Date: 2025-09-26 +- Verified By: @your-handle +- Validated Against: Windows 11 23H2, HP LaserJet Pro +- Recurrence Notes: Common after major Windows updates ``` ## When To Track + - New incident patterns emerge (multiple similar tickets) - Longer-than-expected MTTR - Playbooks or KBs need periodic review windows ## Keep It Practical -- No dashboards required—just fill fields in Markdown. + +- No dashboards required—just fill fields in Markdown. - Prefer consistency over precision. diff --git a/docs/ROLES.md b/docs/ROLES.md index a53b370..ebdde50 100644 --- a/docs/ROLES.md +++ b/docs/ROLES.md @@ -1,8 +1,9 @@ -# Roles and Escalation +# Roles and Escalation Keep contributions simple and consistent. Use these lightweight roles and tiers to signal ownership and when to escalate. ## Project Roles + - Contributor: Anyone adding or improving tickets, KBs, labs, or scenarios. - Reviewer: Anyone giving peer feedback in Discussions or PRs. - Maintainer: Approves PRs, curates templates, and organizes Discussions categories. @@ -10,38 +11,42 @@ Keep contributions simple and consistent. Use these lightweight roles and tiers Tip: In KBs and Labs, use metadata fields like Owner, Last Reviewed, Next Review Due to show stewardship. ## Support Tiers (Scope and Actions) + - Tier 1 (Frontline) - Scope: Single-user issues, basic checks, standard fixes. - Typical actions: Verify problem, collect environment, reproduce, apply known fixes. - - Timebox: 10–20 minutes before escalating. + - Timebox: 10–20 minutes before escalating. - Tier 2 (Specialist) - Scope: Drivers, services, complex app configs, small network issues. - Typical actions: Logs review, driver/config changes, targeted scripts. -- Tier 3 (Deep) +- Tier 3 (Deep) - Scope: OS-level faults, hardware failures, infrastructure dependencies. - Typical actions: Advanced diagnostics, vendor docs, replacement decisions. ## Escalation Signals + - Safety or data risk detected. - Permissions or tooling required beyond your access. - Timebox exceeded with no progress. - Systemic/recurring incident (affects multiple users). ## How To Mark Tiers in Tickets + Include this block (edit as you go): ```markdown -**Escalation Path:** -- [x] Tier 1 complete (basic troubleshooting done) -- [ ] Escalated to Tier 2 (e.g., driver or service-level change) -- [ ] Escalated to Tier 3 (e.g., OS/hardware/vendor) +## Escalation Path: +- [x] Tier 1 complete (basic troubleshooting done) +- [ ] Escalated to Tier 2 (e.g., driver or service-level change) +- [ ] Escalated to Tier 3 (e.g., OS/hardware/vendor) ``` ## KB/Lab Ownership Example + Add to the metadata block: ```markdown -**Owner:** @your-handle -**Last Reviewed:** 2025-09-26 -**Next Review Due:** 2026-03-26 +**Owner:** @your-handle +**Last Reviewed:** 2025-09-26 +**Next Review Due:** 2026-03-26 ``` diff --git a/docs/lamp-osticket-setup.md b/docs/lamp-osticket-setup.md index 05cbfd5..0a709ff 100644 --- a/docs/lamp-osticket-setup.md +++ b/docs/lamp-osticket-setup.md @@ -1,30 +1,36 @@ -# Deploying osTicket +# Deploying osTicket -This guide explains how to set up **osTicket v1.18.1**, a free helpdesk ticketing system, on **Ubuntu 24.04 Desktop** using **VirtualBox**. It’s written for beginners to help you get osTicket running step-by-step. Sensitive details (like passwords or IP addresses) are replaced with placeholders to keep things safe. +This guide explains how to set up **osTicket v1.18.1**, a free helpdesk ticketing system, on **Ubuntu 24.04 Desktop** using **VirtualBox**. It’s written for beginners to help you get osTicket running step-by-step. Sensitive details (like passwords or IP addresses) are replaced with placeholders to keep things safe. -**Warning**: This setup is for testing or development. Do **not** use it in production without adding HTTPS (SSL), a firewall, and other security measures (see “What to Do Next” section). +**Warning**: This setup is for testing or development. Do **not** use it in production without adding HTTPS (SSL), a firewall, and other security measures (see “What to Do Next” section). + +## What You’ll Need -## What You’ll Need - A computer with **Oracle VirtualBox** installed (download from [virtualbox.org](https://www.virtualbox.org)). - The **Ubuntu 24.04 Desktop ISO** file (get it from [ubuntu.com](https://ubuntu.com)). -- A basic understanding of how to use a computer terminal (we’ll explain commands clearly!). -- About 1–2 hours to follow along. +- A basic understanding of how to use a computer terminal (we’ll explain commands clearly!). +- About 1–2 hours to follow along. ## Using Placeholders + This guide uses placeholders for sensitive information: + - Replace `YOUR_DB_PASSWORD` with a strong password (e.g., generate one with `openssl rand -base64 12` in the terminal). -- Replace `` with your VM’s IP address (find it by running `ip addr show` in the terminal and looking for the IP under `inet`, usually starting with `192.168.`). -- Replace `osticket-server.localdomain` with your VM’s hostname or IP if needed. +- Replace `` with your VM’s IP address (find it by running `ip addr show` in the terminal and looking for the IP under `inet`, usually starting with `192.168.`). +- Replace `osticket-server.localdomain` with your VM’s hostname or IP if needed. ## What This Guide Does + This guide will help you: + - Create a virtual machine (VM) in VirtualBox. - Install Ubuntu 24.04 Desktop on the VM. -- Set up a web server, database, and PHP (the “LAMP stack”). +- Set up a web server, database, and PHP (the “LAMP stack”). - Install osTicket v1.18.1 and make it secure. - Check that everything works. ## Table of Contents + 1. [Set Up Your Virtual Machine](#set-up-your-virtual-machine) 2. [Install Ubuntu](#install-ubuntu) 3. [Set Up the Web Server and Database](#set-up-the-web-server-and-database) @@ -38,99 +44,131 @@ This guide will help you: 11. [What to Do Next](#what-to-do-next) ## Set Up Your Virtual Machine + 1. Open VirtualBox and click **New** to create a virtual machine. -2. Name it (e.g., “osTicket-VM”). +2. Name it (e.g., “osTicket-VM”). 3. Choose **Linux** as the type and **Ubuntu (64-bit)** as the version. 4. Set these settings: - **CPUs**: 2 - **RAM**: 4 GB (or 8 GB if your computer has enough memory) - **Disk**: 40 GB (this gives space for tickets and logs) - - **Network**: Choose “Bridged Adapter” so the VM can connect to your network. - - **VT-x**: Enable in your computer’s BIOS if it’s not already on (check VirtualBox’s error messages if it fails). + - **Network**: Choose “Bridged Adapter” so the VM can connect to your network. + - **VT-x**: Enable in your computer’s BIOS if it’s not already on (check VirtualBox’s error messages if it fails). 5. Select the Ubuntu 24.04 Desktop ISO file when prompted and start the VM. ## Install Ubuntu + 1. The VM will boot from the Ubuntu ISO. Follow the on-screen steps to install Ubuntu 24.04 Desktop. 2. Choose a hostname (e.g., `osticket-server`) and a domain (e.g., `localdomain`) during setup. 3. Complete the installation and log in to the Ubuntu desktop. ## Set Up the Web Server and Database -1. Open the **Terminal** (search for it in Ubuntu’s menu or press `Ctrl + Alt + T`). + +1. Open the **Terminal** (search for it in Ubuntu’s menu or press `Ctrl + Alt + T`). 2. Update your system and install Apache (web server), MySQL (database), PHP, and required tools: + ```bash sudo apt update sudo apt install -y apache2 mysql-server php libapache2-mod-php php-mysql php-imap php-intl php-gd php-xml php-cli php-mbstring unzip curl sudo systemctl enable --now apache2 mysql ``` - - **What this does**: Updates your system, installs the web server, database, and PHP, then starts them. + +- **What this does**: Updates your system, installs the web server, database, and PHP, then starts them. + 3. Check that Apache and MySQL are running: + ```bash systemctl status apache2 systemctl status mysql ``` - - **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. + +- **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. + 4. Confirm PHP is installed (version should be 7.2 or higher): + ```bash php -v ``` ## Set Up the Database + 1. **Secure MySQL**: - Run this command to make MySQL safer: + ```bash sudo mysql_secure_installation ``` - - Follow the prompts: - - Keep the default `auth_socket` for local root access (just press Enter). - - Remove anonymous users (say “Yes”). - - Disallow remote root login (say “Yes”). - - Drop the test database (say “Yes”). - - Reload privileges (say “Yes”). + +- Follow the prompts: + - Keep the default `auth_socket` for local root access (just press Enter). + - Remove anonymous users (say “Yes”). + - Disallow remote root login (say “Yes”). + - Drop the test database (say “Yes”). + - Reload privileges (say “Yes”). + 2. **Create a database and user for osTicket**: - Log in to MySQL: + ```bash sudo mysql ``` - - Run these commands (replace `YOUR_DB_PASSWORD` with a strong password, e.g., generate one with `openssl rand -base64 12`): + +- Run these commands (replace `YOUR_DB_PASSWORD` with a strong password, e.g., generate one with `openssl rand -base64 12`): + ```sql CREATE DATABASE IF NOT EXISTS osticket; CREATE USER 'osticketuser'@'localhost' IDENTIFIED BY 'YOUR_DB_PASSWORD'; GRANT ALL PRIVILEGES ON osticket.* TO 'osticketuser'@'localhost'; FLUSH PRIVILEGES; ``` - - Exit MySQL: + +- Exit MySQL: + ```sql EXIT; ``` + 3. Verify MySQL version and authentication plugin: + ```sql SELECT VERSION(); ``` - - **What to look for**: You should see MySQL 8.x and `caching_sha2_password` as the default plugin. + +- **What to look for**: You should see MySQL 8.x and `caching_sha2_password` as the default plugin. ## Install osTicket Files + 1. Download osTicket v1.18.1 from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). Save the ZIP file to your VM (e.g., in `/tmp`). -2. If the ZIP file doesn’t work (e.g., corrupt), download it again. -3. Extract the ZIP and copy the `upload/` folder contents to the web server’s directory: +2. If the ZIP file doesn’t work (e.g., corrupt), download it again. +3. Extract the ZIP and copy the `upload/` folder contents to the web server’s directory: + ```bash sudo cp -r /tmp/upload/* /var/www/html/osticket/ ``` - - **Note**: If you unzipped the file and the `upload` folder is intact (not extracted), use this instead: + +- **Note**: If you unzipped the file and the `upload` folder is intact (not extracted), use this instead: + ```bash sudo mv /tmp/upload /var/www/html/osticket ``` + 4. Set the correct ownership so the web server can access the files: + ```bash sudo chown -R www-data:www-data /var/www/html/osticket ``` ## Configure the Web Server + 1. Create a configuration file for osTicket at `/etc/apache2/sites-available/osticket.conf`: - Use a text editor like `nano`: + ```bash sudo nano /etc/apache2/sites-available/osticket.conf ``` - - Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): + +- Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): + ```apache ServerName osticket-server.localdomain @@ -144,22 +182,29 @@ sudo nano /etc/apache2/sites-available/osticket.conf CustomLog ${APACHE_LOG_DIR}/osticket_access.log combined ``` - - Save and exit (`Ctrl + O`, Enter, `Ctrl + X`). + +- Save and exit (`Ctrl + O`, Enter, `Ctrl + X`). + 2. Enable the site and URL rewriting: + ```bash sudo a2ensite osticket.conf sudo a2enmod rewrite sudo systemctl daemon-reload sudo systemctl reload apache2 ``` + 3. Check that the configuration is correct: + ```bash sudo apache2ctl configtest ``` - - **What to look for**: It should say `Syntax OK`. If not, check for typos in `osticket.conf`. + +- **What to look for**: It should say `Syntax OK`. If not, check for typos in `osticket.conf`. ## Run the osTicket Web Installer -1. Open a web browser on the VM (or your host computer) and go to `http:///osticket/setup/` (replace `` with your VM’s IP address, found via `ip addr show` in the terminal). + +1. Open a web browser on the VM (or your host computer) and go to `http:///osticket/setup/` (replace `` with your VM’s IP address, found via `ip addr show` in the terminal). 2. You should see the osTicket setup page. If not, check that Apache is running (`systemctl status apache2`). 3. Fill in the database details: - **Hostname**: `localhost` @@ -168,82 +213,111 @@ sudo apache2ctl configtest - **Password**: (the secure password you set earlier) 4. Follow the setup wizard to complete installation. 5. Note: The installer may say the APCu extension is optional. You can install it later if needed: + ```bash sudo apt install php-apcu ``` ## Secure Your Setup + 1. During installation, osTicket copies a sample config to `ost-config.php`. 2. Remove the setup folder to prevent unauthorized access: + ```bash sudo rm -rf /var/www/html/osticket/setup/ ``` + 3. Lock down the config file so only the web server can read it: + ```bash sudo chmod 0444 /var/www/html/osticket/include/ost-config.php sudo chown root:www-data /var/www/html/osticket/include/ost-config.php ``` + 4. Double-check file permissions: + ```bash ls -l /var/www/html/osticket/include/ost-config.php ``` - - It should show `-r--r--r-- root www-data`. + +- It should show `-r--r--r-- root www-data`. ## Check That It Works + 1. Open `http:///osticket/` in your browser. You should see the osTicket client portal. 2. Log in to the staff panel (usually at `http:///osticket/scp`) with the admin credentials you set during installation. 3. Check that the database tables were created: - Log in to MySQL: + ```bash sudo mysql -u osticketuser -p ``` - - Enter your `YOUR_DB_PASSWORD`. - - Run: + +- Enter your `YOUR_DB_PASSWORD`. +- Run: + ```sql USE osticket; SHOW TABLES; ``` - - You should see a list of tables (e.g., `ost_ticket`, `ost_user`). + +- You should see a list of tables (e.g., `ost_ticket`, `ost_user`). + 4. Check for insecure files in the web directory (this should return nothing): + ```bash sudo find /var/www/html/osticket -type f -perm -o=w -ls sudo find /var/www/html/osticket -type d -perm -o=w -ls ``` ## Troubleshooting Common Issues -- **Corrupt ZIP file**: If the osTicket ZIP doesn’t extract, it might have downloaded incorrectly. Re-download from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). -- **MySQL shows `->` prompt**: This means you didn’t finish a command. Type `;` to complete it or `\c` to cancel. + +- **Corrupt ZIP file**: If the osTicket ZIP doesn’t extract, it might have downloaded incorrectly. Re-download from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). +- **MySQL shows `->` prompt**: This means you didn’t finish a command. Type `;` to complete it or `\c` to cancel. - **ERROR 1064 in MySQL**: This happens if you press Enter too soon or use wrong syntax. Check your command and verify MySQL version: + ```sql SELECT VERSION(); ``` -- **ERROR 1410 (GRANT)**: This means the user doesn’t exist or you’re not logged in as root. Use `sudo mysql` to log in as root. + +- **ERROR 1410 (GRANT)**: This means the user doesn’t exist or you’re not logged in as root. Use `sudo mysql` to log in as root. ## What to Do Next + **Important**: This setup is for testing only. For production, you must add security measures like HTTPS and a firewall to protect your osTicket instance. - Set up an email account for osTicket to send notifications (use a custom domain and a service like Gmail to avoid spam issues). -- Add HTTPS for security using Let’s Encrypt: +- Add HTTPS for security using Let’s Encrypt: + ```bash sudo apt install certbot python3-certbot-apache sudo certbot --apache ``` + - Set up a firewall to allow web traffic: + ```bash sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` + - Install `fail2ban` to protect against brute-force attacks: + ```bash sudo apt install fail2ban ``` + - Back up your web files and database regularly: + ```bash sudo tar -czf /backup/osticket_backup_$(date +%F).tar.gz /var/www/html/osticket/ mysqldump -u osticketuser -p osticket > /backup/osticket_db_$(date +%F).sql ``` + - Keep your system updated: + ```bash sudo apt update && sudo apt upgrade ``` + diff --git a/kb/000.kb-template.md b/kb/000.kb-template.md index b3dede5..03df247 100644 --- a/kb/000.kb-template.md +++ b/kb/000.kb-template.md @@ -1,4 +1,4 @@ -# KB: [Short Title] +# KB: [Short Title] **Related Ticket(s):** /tickets/[filename].md **Category:** Hardware | Software | Network | Account | Other @@ -9,20 +9,25 @@ **Next Review Due:** [YYYY-MM-DD] ## Resolution Steps + 1. [Step 1, e.g., "Open Services.msc and locate Print Spooler"] 2. [Step 2, e.g., "Restart the service"] 3. Verification: [Confirm the outcome, e.g., "Print a test page to ensure success"] ## Troubleshooting Notes + - [Escalation guidance, e.g., "If restarting fails, check driver compatibility"] - [Known limitations, e.g., "Solution may not work for network printers"] - [Logs or outputs, e.g., "Check /var/log/syslog for errors"] ## Linked Incidents + - /tickets/[incident1].md - /tickets/[incident2].md ## Metrics / References + - Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] - Recurrence: [Yes/No, e.g., "No"] - External reference: [e.g., "HP Printer Manual, https://support.hp.com"] + diff --git a/kb/README.md b/kb/README.md index 5a93042..acb2f08 100644 --- a/kb/README.md +++ b/kb/README.md @@ -1,4 +1,4 @@ -# Knowledge Base Index +# Knowledge Base Index Reusable solution docs derived from tickets and verified in labs. diff --git a/kb/account-lockout-reset.md b/kb/account-lockout-reset.md index 92cc6b4..5295194 100644 --- a/kb/account-lockout-reset.md +++ b/kb/account-lockout-reset.md @@ -1,32 +1,36 @@ -# KB: Account lockout reset and verification +# KB: Account lockout reset and verification -**Related Ticket(s):** /tickets/account-locked-out.md -**Related Lab(s):** /labs/htpasswd-auth-reset.md -**Related Scenario:** /scenarios/account-lockout-reset.md -**Category:** Account +**Related Ticket(s):** /tickets/account-locked-out.md +**Related Lab(s):** /labs/htpasswd-auth-reset.md +**Related Scenario:** /scenarios/account-lockout-reset.md +**Category:** Account **Environment:** Windows workstation joined to Active Directory; VPN/Email access -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps -1. Verify identity per policy (secondary info, manager approval if required). -2. In AD Users and Computers: check account state; unlock if locked. -3. If password expired/unknown, reset to a temporary value; require change at next logon. -4. Instruct the user to sign in on a wired network if possible; wait for policy replication if applicable. + +1. Verify identity per policy (secondary info, manager approval if required). +2. In AD Users and Computers: check account state; unlock if locked. +3. If password expired/unknown, reset to a temporary value; require change at next logon. +4. Instruct the user to sign in on a wired network if possible; wait for policy replication if applicable. 5. Verification: user confirms workstation login; for lab parity, Basic Auth to `/secure` returns HTTP 200. ## Troubleshooting Notes -- If repeated lockouts occur, look for stale credentials on other devices (mobile email, mapped services, scheduled tasks). -- Confirm MFA/SSPR state and recent policy changes. -- Check domain controller replication or account lockout policy thresholds. + +- If repeated lockouts occur, look for stale credentials on other devices (mobile email, mapped services, scheduled tasks). +- Confirm MFA/SSPR state and recent policy changes. +- Check domain controller replication or account lockout policy thresholds. - Logs: Security Event Log (user lockout), DC lockout status. ## Linked Incidents + - /tickets/account-locked-out.md ## Metrics / References -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Account lockout troubleshooting) diff --git a/kb/outlook-reconnect-after-update.md b/kb/outlook-reconnect-after-update.md index 4c8c527..6754c93 100644 --- a/kb/outlook-reconnect-after-update.md +++ b/kb/outlook-reconnect-after-update.md @@ -1,36 +1,36 @@ -# KB: Resolve Outlook disconnect / password prompts +# KB: Resolve Outlook disconnect / password prompts -**Related Ticket(s):** /tickets/outlook-disconnected-password-prompts.md -**Related Lab(s):** /labs/mailhog-connectivity.md -**Related Scenario:** /scenarios/outlook-reconnect-after-update.md -**Category:** Software +**Related Ticket(s):** /tickets/outlook-disconnected-password-prompts.md +**Related Lab(s):** /labs/mailhog-connectivity.md +**Related Scenario:** /scenarios/outlook-reconnect-after-update.md +**Category:** Software **Environment:** Windows 10/11; Outlook (Microsoft 365); VPN (if remote) -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps - -1. Validate user credentials on another system (SSO/portal) to rule out auth failure. -2. Check VPN/Network connectivity (if remote): ensure stable connection. -3. Toggle Cached Exchange Mode (disable → enable) and restart Outlook. -4. Clear Windows Credential Manager entries for Office/Outlook; restart Outlook. -5. If needed, create a new Outlook profile (Control Panel → Mail → Profiles). + +1. Validate user credentials on another system (SSO/portal) to rule out auth failure. +2. Check VPN/Network connectivity (if remote): ensure stable connection. +3. Toggle Cached Exchange Mode (disable → enable) and restart Outlook. +4. Clear Windows Credential Manager entries for Office/Outlook; restart Outlook. +5. If needed, create a new Outlook profile (Control Panel → Mail → Profiles). 6. Verification: Outlook shows Connected; send/receive works. In lab, MailHog captures a test message at . ## Troubleshooting Notes - -- After updates, Autodiscover or token cache can cause loops; clearing credentials/profile often resolves. -- If organization-wide, check Exchange/identity provider status and service health. -- Logs: Windows Event Viewer → Application (Outlook), Office logs. + +- After updates, Autodiscover or token cache can cause loops; clearing credentials/profile often resolves. +- If organization-wide, check Exchange/identity provider status and service health. +- Logs: Windows Event Viewer → Application (Outlook), Office logs. ## Linked Incidents - + - /tickets/outlook-disconnected-password-prompts.md ## Metrics / References - -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Outlook connectivity, Autodiscover) diff --git a/kb/printer-queue-clearing.md b/kb/printer-queue-clearing.md index 354f48e..c8e08a2 100644 --- a/kb/printer-queue-clearing.md +++ b/kb/printer-queue-clearing.md @@ -1,35 +1,35 @@ -# KB: Clear stuck print queue (client/server) +# KB: Clear stuck print queue (client/server) -**Related Ticket(s):** /tickets/cannot-print-to-shared-printer.md -**Related Lab(s):** /labs/print-queue-stuck.md -**Related Scenario:** /scenarios/printer-queue-clearing.md -**Category:** Hardware +**Related Ticket(s):** /tickets/cannot-print-to-shared-printer.md +**Related Lab(s):** /labs/print-queue-stuck.md +**Related Scenario:** /scenarios/printer-queue-clearing.md +**Category:** Hardware **Environment:** Windows clients; server-hosted printer (e.g., HP LaserJet series) -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps - -1. Confirm scope: multiple users affected implies server-side issue. -2. On server: open Print Management; check the queue; cancel the oldest/large stuck job. -3. Restart the Print Spooler service (Services.msc or `net stop spooler` / `net start spooler`). -4. On a client: clear local queue if needed and print a test page. + +1. Confirm scope: multiple users affected implies server-side issue. +2. On server: open Print Management; check the queue; cancel the oldest/large stuck job. +3. Restart the Print Spooler service (Services.msc or `net stop spooler` / `net start spooler`). +4. On a client: clear local queue if needed and print a test page. 5. Verification: new test job prints; in lab, remaining job is processed and queue shows steady state. ## Troubleshooting Notes - -- Ensure correct driver model on server (Type 3/4) and clients. -- Watch for mis-sized PDFs or offline ports. + +- Ensure correct driver model on server (Type 3/4) and clients. +- Watch for mis-sized PDFs or offline ports. - If department-wide and persistent, check network path to printer, SNMP status, or firmware. ## Linked Incidents - + - /tickets/cannot-print-to-shared-printer.md ## Metrics / References - -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Print Management); Vendor printer admin guide diff --git a/kb/workstation-performance-triage.md b/kb/workstation-performance-triage.md index f3ec712..2c97985 100644 --- a/kb/workstation-performance-triage.md +++ b/kb/workstation-performance-triage.md @@ -1,35 +1,35 @@ -# KB: Workstation performance triage (CPU/Disk/Network) +# KB: Workstation performance triage (CPU/Disk/Network) -**Related Ticket(s):** /tickets/computer-running-slow-lagging.md -**Related Lab(s):** /labs/resource-spike-triage.md -**Related Scenario:** /scenarios/workstation-performance-triage.md -**Category:** Hardware +**Related Ticket(s):** /tickets/computer-running-slow-lagging.md +**Related Lab(s):** /labs/resource-spike-triage.md +**Related Scenario:** /scenarios/workstation-performance-triage.md +**Category:** Hardware **Environment:** Windows 10/11; corporate network -**Owner:** TBD -**Last Reviewed:** 2025-09-28 +**Owner:** TBD +**Last Reviewed:** 2025-09-28 **Next Review Due:** 2026-03-28 ## Resolution Steps - -1. Differentiate network vs local: ping internal resource vs external site. -2. Check Task Manager for CPU/RAM/Disk spikes; identify culprit process. -3. Remediate: stop runaway task; reschedule AV scans/OneDrive sync; check Windows Update. -4. Disk health: check SMART, consider SSD upgrade if HDD and recurring. + +1. Differentiate network vs local: ping internal resource vs external site. +2. Check Task Manager for CPU/RAM/Disk spikes; identify culprit process. +3. Remediate: stop runaway task; reschedule AV scans/OneDrive sync; check Windows Update. +4. Disk health: check SMART, consider SSD upgrade if HDD and recurring. 5. Verification: CPU/Disk usage normalizes; common actions (open browser/drive) are fast; in lab, top shows normal usage. ## Troubleshooting Notes - -- If only company site is slow, escalate to web/app owners. -- Confirm no VPN tunnel conflicts or DNS issues. + +- If only company site is slow, escalate to web/app owners. +- Confirm no VPN tunnel conflicts or DNS issues. - Capture before/after metrics if possible for MTTR. ## Linked Incidents - + - /tickets/computer-running-slow-lagging.md ## Metrics / References - -- MTTR: TBD -- Recurrence: TBD + +- MTTR: TBD +- Recurrence: TBD - External reference: Microsoft Docs (Performance troubleshooting), vendor AV scheduling docs diff --git a/labs/000.lab-template.md b/labs/000.lab-template.md index 7634729..c2a9581 100644 --- a/labs/000.lab-template.md +++ b/labs/000.lab-template.md @@ -1,26 +1,26 @@ -# Lab: [Short Title] +# Lab: [Short Title] -**Related KB:** /kb/[filename].md -**Category:** Hardware | Software | Network | Account | Other -**Environment:** [OS, system, or software version, e.g., "Ubuntu 24.04"] +**Related KB:** /kb/[filename].md +**Category:** Hardware | Software | Network | Account | Other +**Environment:** [OS, system, or software version, e.g., "Ubuntu 24.04"] -**Owner:** [Your name or team] -**Last Reviewed:** [YYYY-MM-DD] -**Next Review Due:** [YYYY-MM-DD] +**Owner:** [Your name or team] +**Last Reviewed:** [YYYY-MM-DD] +**Next Review Due:** [YYYY-MM-DD] ## Objectives - + - [Skill or goal, e.g., "Learn to diagnose and fix a failed print service"] ## Prerequisites - -- [Setup, e.g., "Ubuntu 24.04 VM with CUPS installed"] -- [Credentials, e.g., "User with sudo access"] + +- [Setup, e.g., "Ubuntu 24.04 VM with CUPS installed"] +- [Credentials, e.g., "User with sudo access"] ## Steps - -1. [Instruction, e.g., "Simulate a failure: sudo systemctl stop "] -2. [Instruction, e.g., "Check service status: sudo systemctl status "] + +1. [Instruction, e.g., "Simulate a failure: sudo systemctl stop "] +2. [Instruction, e.g., "Check service status: sudo systemctl status "] 3. [Command, e.g.,] ```bash @@ -28,22 +28,22 @@ ``` ## Verification - -- [Expected outcome, e.g., "Run lpstat -p; confirm printer is enabled"] -- [Pass condition, e.g., "Test page prints successfully"] -- [Fail condition, e.g., "Error: ‘printer not found’"] + +- [Expected outcome, e.g., "Run lpstat -p; confirm printer is enabled"] +- [Pass condition, e.g., "Test page prints successfully"] +- [Fail condition, e.g., "Error: ‘printer not found’"] ## Escalation Context - -- [If lab fails, e.g., "Check /var/log//error_log and escalate to Tier 2 if driver issues persist. See ROLES.md"] + +- [If lab fails, e.g., "Check /var/log//error_log and escalate to Tier 2 if driver issues persist. See ROLES.md"] ## Metrics / Feedback - -- Estimated time to complete: [e.g., "15 minutes"] -- Common errors: [e.g., "‘ not found’ ( not installed)"] -- Links: [/tickets/[incident].md or /scenarios/[scenario].md] + +- Estimated time to complete: [e.g., "15 minutes"] +- Common errors: [e.g., "‘ not found’ ( not installed)"] +- Links: [/tickets/[incident].md or /scenarios/[scenario].md] ## Cleanup - -- [Reset steps, e.g., "Restart service: sudo systemctl start "] + +- [Reset steps, e.g., "Restart service: sudo systemctl start "] - [Ensure readiness, e.g., "Verify service status with systemctl status "] diff --git a/labs/README.md b/labs/README.md index 7b7f272..2744b81 100644 --- a/labs/README.md +++ b/labs/README.md @@ -1,4 +1,4 @@ -# Labs Catalog +# Labs Catalog Hands-on troubleshooting exercises. Use these to practice skills and validate KBs. diff --git a/labs/htpasswd-auth-reset.md b/labs/htpasswd-auth-reset.md index c2c0c0e..98deee9 100644 --- a/labs/htpasswd-auth-reset.md +++ b/labs/htpasswd-auth-reset.md @@ -1,11 +1,11 @@ -# Lab: Basic auth reset verification (htpasswd + Nginx) +# Lab: Basic auth reset verification (htpasswd + Nginx) Simulate a credential reset and prove the fix with a protected endpoint. -**Related Ticket:** /tickets/account-locked-out.md -**Related KB:** /kb/account-lockout-reset.md -**Related Scenario:** /scenarios/account-lockout-reset.md -**Category:** Account +**Related Ticket:** /tickets/account-locked-out.md +**Related KB:** /kb/account-lockout-reset.md +**Related Scenario:** /scenarios/account-lockout-reset.md +**Category:** Account **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives @@ -32,17 +32,20 @@ Simulate a credential reset and prove the fix with a protected endpoint. ```bash docker compose -f ./labs/htpasswd-auth-reset/assets/compose.yaml up -d ``` + 2) Try accessing (expect auth required) ```powershell Invoke-WebRequest http://localhost:8090/secure -UseBasicParsing -Headers @{ Authorization = ("Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("user:wrong"))) } | Select-Object -ExpandProperty StatusCode # Expect 401/403 ``` + 3) Reset password ```powershell docker exec htpasswd sh -lc "htpasswd -b /auth/.htpasswd user newpass" ``` + 4) Verify access succeeds ```powershell diff --git a/labs/mailhog-connectivity.md b/labs/mailhog-connectivity.md index d884587..56fc1cd 100644 --- a/labs/mailhog-connectivity.md +++ b/labs/mailhog-connectivity.md @@ -1,11 +1,11 @@ -# Lab: Mail connectivity sanity with MailHog +# Lab: Mail connectivity sanity with MailHog Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. -**Related Ticket:** /tickets/outlook-disconnected-password-prompts.md -**Related KB:** /kb/outlook-reconnect-after-update.md -**Related Scenario:** /scenarios/outlook-reconnect-after-update.md -**Category:** Software +**Related Ticket:** /tickets/outlook-disconnected-password-prompts.md +**Related KB:** /kb/outlook-reconnect-after-update.md +**Related Scenario:** /scenarios/outlook-reconnect-after-update.md +**Category:** Software **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives @@ -33,17 +33,20 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. ```bash docker compose -f ./labs/mailhog-connectivity/assets/compose.yaml up -d ``` + 2) Check status ```powershell docker compose -f .\labs\mailhog-connectivity\assets\compose.yaml ps # UI at ``` + 3) Send a test message ```powershell docker exec mailhog bash -lc "echo -e 'HELO test\nMAIL FROM:\nRCPT TO:\nDATA\nSubject: hello\n\nmailhog test\n.\nQUIT' | nc 127.0.0.1 1025" ``` + 4) Simulate disconnect and recover ```powershell @@ -51,6 +54,7 @@ Use MailHog to practice diagnosing "client disconnected / prompting" symptoms. # expect UI down; restart docker start mailhog ``` + 5) Verify in UI - Browse and confirm the message is present. diff --git a/labs/nginx-startup-fail.md b/labs/nginx-startup-fail.md index b5f63be..acdec8c 100644 --- a/labs/nginx-startup-fail.md +++ b/labs/nginx-startup-fail.md @@ -1,25 +1,27 @@ -# Lab: Nginx fails to start (config error) +# Lab: Nginx fails to start (config error) Make a broken web server boot again by fixing a one-word typo. -**Related KB:** /kb/nginx-config-basics.md (optional) -**Category:** Software +**Related KB:** /kb/nginx-config-basics.md (optional) +**Category:** Software **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) -**Owner:** -**Last Reviewed:** -**Next Review Due:** +## Owner + +## Last Reviewed + +## Next Review Due ## Why this matters (30 seconds) -This is what real-life looks like: “my web page won’t load” and the container keeps restarting. Your job is to read the logs, spot the typo, make a tiny change, and prove the fix. +This is what real-life looks like: “my web page won’t load” and the container keeps restarting. Your job is to read the logs, spot the typo, make a tiny change, and prove the fix. ## Objectives - Diagnose a containerized Nginx startup failure - Fix a simple configuration error and verify success -Time: ~10–15 min • Difficulty: Beginner +Time: ~10–15 min • Difficulty: Beginner ## Prerequisites (quick preflight) @@ -30,14 +32,13 @@ Time: ~10–15 min • Difficulty: Beginner docker --version docker compose version ``` - + - Bash ```bash docker --version docker compose version ``` - ## Steps @@ -48,13 +49,12 @@ Time: ~10–15 min • Difficulty: Beginner ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml up -d ``` - + - Bash ```bash docker compose -f ./labs/nginx-startup-fail/assets/compose.yaml up -d ``` - 2) Observe the failure - Status @@ -62,13 +62,12 @@ Time: ~10–15 min • Difficulty: Beginner ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps ``` - - - Logs (look for “unknown directive” or “invalid”) + + - Logs (look for “unknown directive” or “invalid”) ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml logs nginx ``` - 3) Identify the issue - Open `labs/nginx-startup-fail/assets/nginx.conf` @@ -84,7 +83,7 @@ Time: ~10–15 min • Difficulty: Beginner ## Verification (success criteria) -- Browse and see “Nginx is up” +- Browse and see “Nginx is up” - Container health should go to `healthy` once the page is served - Or use a CLI check: - Check health status quickly @@ -93,6 +92,7 @@ Time: ~10–15 min • Difficulty: Beginner docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml ps # Expect: State shows "running (healthy)" ``` + - PowerShell ```powershell @@ -107,11 +107,10 @@ Time: ~10–15 min • Difficulty: Beginner # Expect: 200 ``` +## Hints (if you’re stuck) -## Hints (if you’re stuck) - -- Re-run logs and read the first error: it usually tells you exactly what Nginx didn’t understand. -- If the fix doesn’t apply, make sure you recreated the container with `--force-recreate`. +- Re-run logs and read the first error: it usually tells you exactly what Nginx didn’t understand. +- If the fix doesn’t apply, make sure you recreated the container with `--force-recreate`. - If port 8080 is busy, edit `compose.yaml` and change `8080:80` to another free port (e.g., `8081:80`). - On Windows, if you see file permission issues, temporarily remove `:ro` from the volume lines to test. @@ -119,7 +118,7 @@ Time: ~10–15 min • Difficulty: Beginner - Estimated time: 10 minutes - Common pitfalls: wrong compose path; forgetting `--force-recreate` after config changes -- Optional next step: write a KB titled “Nginx: fix startup syntax errors” linking this lab +- Optional next step: write a KB titled “Nginx: fix startup syntax errors” linking this lab ## Bonus challenges (optional) @@ -132,4 +131,3 @@ Time: ~10–15 min • Difficulty: Beginner ```powershell docker compose -f .\labs\nginx-startup-fail\assets\compose.yaml down -v ``` - diff --git a/labs/print-queue-stuck.md b/labs/print-queue-stuck.md index a67b9d5..8ea4382 100644 --- a/labs/print-queue-stuck.md +++ b/labs/print-queue-stuck.md @@ -1,11 +1,11 @@ -# Lab: Print queue stuck (department-wide) +# Lab: Print queue stuck (department-wide) Reproduce a stuck print queue and practice clearing jobs and restarting the "spooler" safely. -**Related Ticket:** /tickets/cannot-print-to-shared-printer.md -**Related KB:** /kb/printer-queue-clearing.md -**Related Scenario:** /scenarios/printer-queue-clearing.md -**Category:** Hardware +**Related Ticket:** /tickets/cannot-print-to-shared-printer.md +**Related KB:** /kb/printer-queue-clearing.md +**Related Scenario:** /scenarios/printer-queue-clearing.md +**Category:** Hardware **Environment:** Docker Desktop (Windows/macOS) or Docker Engine (Linux) ## Objectives @@ -28,7 +28,6 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo docker compose -f .\labs\print-queue-stuck\assets\compose.yaml up -d ``` - - Bash ```bash @@ -59,6 +58,7 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo docker exec print-queue sed -i '1d' /queue/jobs.txt docker start print-queue-consumer ``` + 5) Verify ```powershell @@ -73,7 +73,6 @@ Reproduce a stuck print queue and practice clearing jobs and restarting the "spo # Expect: remaining job name present; queue stable ``` - ## Cleanup ```powershell diff --git a/labs/resource-spike-triage.md b/labs/resource-spike-triage.md index b763f44..ed60a61 100644 --- a/labs/resource-spike-triage.md +++ b/labs/resource-spike-triage.md @@ -1,4 +1,4 @@ -# Lab: Resource spike triage (CPU/Disk) +# Lab: Resource spike triage (CPU/Disk) Practice identifying and resolving resource spikes that cause slowness. diff --git a/scenarios/000.scenario-template.md b/scenarios/000.scenario-template.md index 6c25910..ca70a04 100644 --- a/scenarios/000.scenario-template.md +++ b/scenarios/000.scenario-template.md @@ -1,4 +1,4 @@ -# Scenario: [Short Title] +# Scenario: [Short Title] Link tickets, KB, and labs to form an end-to-end workflow. @@ -18,7 +18,7 @@ Briefly describe the user story and desired outcome. ## Success Criteria -- [ ] Ticket resolved (what “resolved” means here) +- [ ] Ticket resolved (what “resolved” means here) - [ ] KB validated (up-to-date and accurate) - [ ] Lab passes verification steps diff --git a/scenarios/README.md b/scenarios/README.md index bd9e940..fb472d2 100644 --- a/scenarios/README.md +++ b/scenarios/README.md @@ -1,6 +1,6 @@ -# Scenarios Index +# Scenarios Index -End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. +End-to-end flows that link Ticket → KB → Lab. Use scenarios to tell the story and define success criteria. - Template: [000.scenario-template.md](./000.scenario-template.md) diff --git a/scenarios/account-lockout-reset.md b/scenarios/account-lockout-reset.md index 048049f..f549c34 100644 --- a/scenarios/account-lockout-reset.md +++ b/scenarios/account-lockout-reset.md @@ -1,4 +1,4 @@ -# Scenario: Account lockout and password reset +# Scenario: Account lockout and password reset - Related Ticket: /tickets/account-locked-out.md - Related KB: /kb/account-lockout-reset.md#resolution-steps diff --git a/scenarios/outlook-reconnect-after-update.md b/scenarios/outlook-reconnect-after-update.md index fac0f1f..f3fbe8c 100644 --- a/scenarios/outlook-reconnect-after-update.md +++ b/scenarios/outlook-reconnect-after-update.md @@ -1,4 +1,4 @@ -# Scenario: Outlook reconnect after update +# Scenario: Outlook reconnect after update - Related Ticket: /tickets/outlook-disconnected-password-prompts.md - Related KB: /kb/outlook-reconnect-after-update.md#resolution-steps diff --git a/scenarios/printer-queue-clearing.md b/scenarios/printer-queue-clearing.md index e9d07d8..57d846c 100644 --- a/scenarios/printer-queue-clearing.md +++ b/scenarios/printer-queue-clearing.md @@ -1,4 +1,4 @@ -# Scenario: Department-wide printer outage (queue clearing) +# Scenario: Department-wide printer outage (queue clearing) - Related Ticket: /tickets/cannot-print-to-shared-printer.md - Related KB: /kb/printer-queue-clearing.md#resolution-steps diff --git a/scenarios/workstation-performance-triage.md b/scenarios/workstation-performance-triage.md index 5c6c880..36d28ee 100644 --- a/scenarios/workstation-performance-triage.md +++ b/scenarios/workstation-performance-triage.md @@ -1,4 +1,4 @@ -# Scenario: Workstation performance triage +# Scenario: Workstation performance triage - Related Ticket: /tickets/computer-running-slow-lagging.md - Related KB: /kb/workstation-performance-triage.md#resolution-steps diff --git a/tickets/000.ticket-template.md b/tickets/000.ticket-template.md index c4378e6..362d512 100644 --- a/tickets/000.ticket-template.md +++ b/tickets/000.ticket-template.md @@ -1,4 +1,4 @@ -# Ticket: [Short Title] +# Ticket: [Short Title] **Category:** Hardware | Software | Network | Account | Other **Priority:** Low | Medium | High | Critical diff --git a/tickets/README.md b/tickets/README.md index b6e3106..1082139 100644 --- a/tickets/README.md +++ b/tickets/README.md @@ -1,4 +1,4 @@ -# Tickets Index +# Tickets Index User-reported issues. Start here when simulating a helpdesk intake. @@ -17,7 +17,7 @@ Conventions: Examples: -- [Account locked out – cannot log in](./account-locked-out.md) +- [Account locked out – cannot log in](./account-locked-out.md) - [Cannot print to shared Finance printer](./cannot-print-to-shared-printer.md) - [Outlook disconnected and password prompts](./outlook-disconnected-password-prompts.md) - [Computer is running extremely slow / lagging](./computer-running-slow-lagging.md) diff --git a/tickets/account-locked-out.md b/tickets/account-locked-out.md index 02443d0..3eca812 100644 --- a/tickets/account-locked-out.md +++ b/tickets/account-locked-out.md @@ -1,4 +1,4 @@ -# Ticket: Account locked out – cannot log in +# Ticket: Account locked out – cannot log in **Category:** Account **Priority:** High @@ -16,7 +16,7 @@ **Symptoms:** Login attempts fail; account lockout message. **Environment:** Windows desktop joined to AD; remote services (email/VPN) affected. -**Troubleshooting Steps Taken:** +## Troubleshooting Steps Taken - [ ] Verified user identity via secondary info (DOB, employee ID) - [ ] Checked AD status for JDoe @@ -24,10 +24,11 @@ - [ ] If password expired, initiated reset or guided through SSPR - [ ] Instructed user to restart and attempt login on wired network -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** +## Escalation Path - [ ] Tier 1 complete (basic checks and unlock/reset) - [ ] Escalated to Tier 2 (e.g., repeated lockouts, MFA issues) diff --git a/tickets/cannot-print-to-shared-printer.md b/tickets/cannot-print-to-shared-printer.md index 382ba15..8f3710f 100644 --- a/tickets/cannot-print-to-shared-printer.md +++ b/tickets/cannot-print-to-shared-printer.md @@ -1,4 +1,4 @@ -# Ticket: Cannot print to shared Finance printer +# Ticket: Cannot print to shared Finance printer **Category:** Hardware **Priority:** Medium @@ -16,7 +16,7 @@ **Symptoms:** Print jobs stuck as Error/Spooling; device shows Ready with flashing status light. **Environment:** Windows clients printing via central print server. -**Troubleshooting Steps Taken:** +## Troubleshooting Steps Taken - [ ] Confirmed print server is running and reachable - [ ] Remotely checked client printer driver/port @@ -24,10 +24,11 @@ - [ ] Checked server print queue for large/stuck jobs - [ ] If department-wide, escalated to Tier 2 (Server Team) -**Resolution:** +## Resolution + [TBD] -**Escalation Path:** +## Escalation Path - [ ] Tier 1 complete (client/queue verification) - [ ] Escalated to Tier 2 (server-side queue/driver) diff --git a/tickets/computer-running-slow-lagging.md b/tickets/computer-running-slow-lagging.md index 6c9fac1..93fa0b4 100644 --- a/tickets/computer-running-slow-lagging.md +++ b/tickets/computer-running-slow-lagging.md @@ -1,4 +1,4 @@ -# Ticket: Computer is running extremely slow / lagging +# Ticket: Computer is running extremely slow / lagging **Category:** Hardware **Priority:** Medium @@ -24,7 +24,8 @@ - [ ] Assessed disk health (HDD fragmentation/SMART) - [ ] Isolated network cause; escalate website performance to Web/DevOps if isolated -**Resolution:** +## Resolution + [TBD] ## Escalation Path diff --git a/tickets/outlook-disconnected-password-prompts.md b/tickets/outlook-disconnected-password-prompts.md index 8232c97..c05d2be 100644 --- a/tickets/outlook-disconnected-password-prompts.md +++ b/tickets/outlook-disconnected-password-prompts.md @@ -1,4 +1,4 @@ -# Ticket: Outlook disconnected and repeatedly prompting for password +# Ticket: Outlook disconnected and repeatedly prompting for password **Category:** Software **Priority:** Medium @@ -13,7 +13,7 @@ **System/Component:** Microsoft Outlook (Cached Mode), Exchange Server **Problem:** Outlook disconnects and repeatedly prompts for password after a company security update. -**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. +**Symptoms:** Disconnected status; repeated password prompts; can’t send/receive recent emails. **Environment:** Laptop (potentially remote); VPN in use when offsite. ## Troubleshooting Steps Taken @@ -24,7 +24,8 @@ - [ ] Toggled Cached Exchange Mode - [ ] Created a new Outlook profile or cleared Credential Manager entries -**Resolution:** +## Resolution + [TBD] ## Escalation Path From 41e07fd4740a0f1b06c0fda3e9b765ab530e6e70 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:54:56 -0700 Subject: [PATCH 23/27] chore: stage trailing edits in CONTRIBUTING and lamp-osticket-setup --- CONTRIBUTING.md | 83 ++++++++++++++++++++----------------- docs/lamp-osticket-setup.md | 73 ++++++++++++++++---------------- 2 files changed, 81 insertions(+), 75 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3334c99..dd96015 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,20 @@ -# Contributing to DeskForge-Simulator (Beginner-Friendly Guide) +# Contributing to DeskForge-Simulator (Beginner-Friendly Guide) -Welcome to **DeskForge-Simulator**! This project simulates real-world helpdesk workflows, guiding you through creating tickets, troubleshooting issues, writing knowledge base (KB) articles, and building labs. Whether you’re new to IT or an experienced pro, we’re excited to have you contribute! +Welcome to **DeskForge-Simulator**! This project simulates real-world helpdesk workflows, guiding you through creating tickets, troubleshooting issues, writing knowledge base (KB) articles, and building labs. Whether you’re new to IT or an experienced pro, we’re excited to have you contribute! This guide provides **guidelines** (not strict rules) for contributing to DeskForge-Simulator. Use your best judgment and suggest improvements via pull requests. **Note**: Setting up a local osTicket instance is **optional** but recommended to learn how ticketing systems work in real-world IT jobs (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md)). You can contribute by writing Markdown files directly or sharing real-world tech support issues, KB drafts, or labs via GitHub Discussions. -## What You’ll Need +## What You’ll Need - A GitHub account to submit contributions (sign up at [github.com](https://github.com)). - A text editor for writing Markdown files in `/tickets/`, `/kb/`, and `/labs/` (we provide templates!). - -- **Optional**: A local osTicket setup to test tickets and KB articles (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) for installing osTicket v1.18.1 in a VirtualBox VM with Ubuntu 24.04 Desktop; client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - + +- **Optional**: A local osTicket setup to test tickets and KB articles (see [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) for installing osTicket v1.18.1 in a VirtualBox VM with Ubuntu 24.04 Desktop; client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. + - For labs: A lightweight Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container) to test troubleshooting steps, which can be the same VM as osTicket or a separate one. -- Curiosity and a willingness to learn—no IT expertise required! +- Curiosity and a willingness to learn—no IT expertise required! ## Contribution Workflow @@ -24,7 +24,7 @@ To keep contributions organized, use the following channels: - **Tickets**: Share real-world tech support issues, fictional scenarios, or training exercises in the `Tickets` category. Convert these into Markdown files for `/tickets/`. - **Knowledge Base**: Share KB drafts or solution ideas in the `Knowledge Base` category. Convert these into Markdown files for `/kb/`. - **Labs**: Share lab ideas or troubleshooting exercises in the `Labs` category. Convert these into Markdown files for `/labs/`. - - **Scenarios & General**: Discuss end-to-end workflows (Ticket → KB → Lab) or general Q&A in the `Scenarios & General` category. + - **Scenarios & General**: Discuss end-to-end workflows (Ticket → KB → Lab) or general Q&A in the `Scenarios & General` category. - **GitHub Issues ([https://github.com/iplaycomputer/DeskForge-Simulator/issues](https://github.com/iplaycomputer/DeskForge-Simulator/issues))**: - Report project-related problems (e.g., bugs, broken setup instructions in `lamp-osticket-setup.md`, missing dependencies). - **Pull Requests**: Submit your final Markdown files (`/tickets/`, `/kb/`, `/labs/`, `/scenarios/`) as pull requests for review. @@ -69,7 +69,7 @@ If you encounter unacceptable behavior, report it via GitHub issues or by contac ## I Have a Question -Don’t file a GitHub issue for general questions—you’ll get faster answers in the `Scenarios & General` category of [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). Other resources: +Don’t file a GitHub issue for general questions—you’ll get faster answers in the `Scenarios & General` category of [GitHub Discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions). Other resources: - **[r/helpdesk on Reddit](https://reddit.com/r/helpdesk)**: Share and learn from real-world troubleshooting stories. - **[Spiceworks Community](https://community.spiceworks.com/)**: Connect with IT pros for tips and best practices. @@ -83,8 +83,8 @@ DeskForge-Simulator follows industry-standard helpdesk practices to ensure contr | Principle | Description | Reference | |-----------|-------------|-----------| | **Clear communication** | Use simple, step-by-step instructions and plain language in tickets and KB articles. | Blokdyk, 2020 | -| **User focus & empathy** | Include technical details and the user’s experience (e.g., what they see, how it affects them). | Blokdyk, 2020; Art of Service, 2021 | -| **Structured troubleshooting** | Follow the CompTIA A+ six-step diagnostic model:
1. Identify the problem
2. Establish a theory of probable cause
3. Test the theory
4. Establish a plan and implement the solution
5. Verify functionality
6. Document findings, actions, and outcomes | O’Shea, 2025 | +| **User focus & empathy** | Include technical details and the user’s experience (e.g., what they see, how it affects them). | Blokdyk, 2020; Art of Service, 2021 | +| **Structured troubleshooting** | Follow the CompTIA A+ six-step diagnostic model:
1. Identify the problem
2. Establish a theory of probable cause
3. Test the theory
4. Establish a plan and implement the solution
5. Verify functionality
6. Document findings, actions, and outcomes | O’Shea, 2025 | | **Escalation & scope** | Know when an issue needs higher-level support and document the escalation path. | Art of Service, 2021 | | **Consistency** | Use standard templates for tickets, KB articles, and labs to keep things uniform. | Blokdyk, 2020 | | **Metrics & improvement** | Track resolution times and root causes to improve the helpdesk process. | Art of Service, 2021 | @@ -92,21 +92,21 @@ DeskForge-Simulator follows industry-standard helpdesk practices to ensure contr ### References -- *Help Desk: A Complete Guide – 2020 Edition* (Gerardus Blokdyk, ISBN 978-1867309383) -- *CompTIA A+ Complete Practice Tests, 4th Edition* (Audrey O’Shea, 2025, Print ISBN 978-1394330331; eText ISBN 978-1394330348) +- *Help Desk: A Complete Guide – 2020 Edition* (Gerardus Blokdyk, ISBN 978-1867309383) +- *CompTIA A+ Complete Practice Tests, 4th Edition* (Audrey O’Shea, 2025, Print ISBN 978-1394330331; eText ISBN 978-1394330348) - *IT Service Desk: A Complete Guide, 2021 Edition* (The Art of Service, ISBN 978-1867437223) - [Atlassian: What Is ITIL? Best Practices for ITSM](https://www.atlassian.com/itsm) ## What Should I Know Before I Get Started? -DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute tickets, KB articles, and labs in Markdown. Testing tickets and KB articles in a local osTicket instance is optional but recommended to understand how ticketing systems work in real-world IT jobs. Here’s what you need to know: +DeskForge-Simulator mimics a real IT helpdesk, allowing you to contribute tickets, KB articles, and labs in Markdown. Testing tickets and KB articles in a local osTicket instance is optional but recommended to understand how ticketing systems work in real-world IT jobs. Here’s what you need to know: -- **GitHub Basics**: If you’re new to GitHub, check out [Contributing to a Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) to learn about forking, branching, committing, and pull requests. -- **Helpdesk Skills**: You don’t need to be an expert! Focus on: +- **GitHub Basics**: If you’re new to GitHub, check out [Contributing to a Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) to learn about forking, branching, committing, and pull requests. +- **Helpdesk Skills**: You don’t need to be an expert! Focus on: - Clear communication with non-technical users. - Basic troubleshooting (e.g., OS, hardware, network issues). - Following templates and asking questions to clarify issues. -- **osTicket Setup (Optional)**: For a hands-on ticketing system experience, set up a local osTicket instance using [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) (client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +- **osTicket Setup (Optional)**: For a hands-on ticketing system experience, set up a local osTicket instance using [lamp-osticket-setup.md](docs/lamp-osticket-setup.md) (client portal at `http:///osticket/`, admin/staff panel at `http:///osticket/scp`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - **Lab Testing**: Test labs in a local Linux VM or sandbox (e.g., Ubuntu 24.04 Desktop or Docker container), which can be the same VM as osTicket or a separate one. osTicket is not required for labs. - **Learning by Doing**: The best way to learn is to write tickets, test solutions, and get feedback. Start small and improve with each contribution! @@ -121,23 +121,23 @@ DeskForge-Simulator is built around four modules that mirror real helpdesk workf | **Labs** | `/labs/` | Hands-on troubleshooting exercises, tested in a Linux VM or sandbox, written in Markdown and shared via GitHub Discussions. | | **Scenarios** | `/scenarios/` | End-to-end workflows combining tickets, KB articles, and labs, written in Markdown. | -Folder guides for quick navigation: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Labs](labs/README.md) · [Scenarios](scenarios/README.md) +Folder guides for quick navigation: [Tickets](tickets/README.md) · [KB](kb/README.md) · [Labs](labs/README.md) · [Scenarios](scenarios/README.md) Roles (to avoid duplication): - Labs are the canonical source of exact commands and environment setup. Always put full commands in Labs and include a small "Verification" section. -- KBs contain productized resolution steps with 1–2 verification lines (max). Link to the Lab for full commands. +- KBs contain productized resolution steps with 1–2 verification lines (max). Link to the Lab for full commands. - Scenarios define the flow and success criteria; they should link to specific sections in the KB (Resolution Steps) and Lab (Verification) rather than restating steps. ### How Modules Work Together -Contributions flow like this: **Ticket → Resolution → KB → Lab → Scenario**. +Contributions flow like this: **Ticket → Resolution → KB → Lab → Scenario**. -- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). +- **Tickets**: Share a ticket in GitHub Discussions (`Tickets` category) or write a Markdown file in `/tickets/` describing a problem (e.g., “Printer not working”). -Optionally, test it in your local osTicket instance’s client portal (`http:///osticket/`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +Optionally, test it in your local osTicket instance’s client portal (`http:///osticket/`). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. -- **KB Articles**: Share a KB draft in GitHub Discussions (`Knowledge Base` category) or write a Markdown file in `/kb/` formalizing the solution (e.g., “How to restart the Print Spooler”). Optionally, test it in your local osTicket instance’s admin/staff panel (`http:///osticket/scp`). +- **KB Articles**: Share a KB draft in GitHub Discussions (`Knowledge Base` category) or write a Markdown file in `/kb/` formalizing the solution (e.g., “How to restart the Print Spooler”). Optionally, test it in your local osTicket instance’s admin/staff panel (`http:///osticket/scp`). - **Labs**: Share a lab idea in GitHub Discussions (`Labs` category) or write a Markdown file in `/labs/` for a hands-on exercise, tested in a Linux VM or sandbox. - **Scenarios**: Combine tickets, KB articles, and labs into a complete workflow in `/scenarios/`. @@ -150,13 +150,13 @@ You can contribute by writing tickets, KB articles, or labs in Markdown, sharing Tickets represent user-reported problems (real, training, or fictional). You can share them in GitHub Discussions, write them directly in Markdown for `/tickets/`, or test them in a local osTicket instance for realism. -- **Option 1: GitHub Discussions**: Post a ticket in the `Tickets` category at [https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) with details of a real-world tech support issue (e.g., “My laptop won’t connect to Wi-Fi”). Convert the details into the Markdown template and save in `/tickets/`. +- **Option 1: GitHub Discussions**: Post a ticket in the `Tickets` category at [https://github.com/iplaycomputer/DeskForge-Simulator/discussions](https://github.com/iplaycomputer/DeskForge-Simulator/discussions) with details of a real-world tech support issue (e.g., “My laptop won’t connect to Wi-Fi”). Convert the details into the Markdown template and save in `/tickets/`. - **Option 2: Direct Markdown**: Write a ticket in the Markdown template below and save it in `/tickets/`. -- **Option 3: Local osTicket (Recommended for Learning)**: Access your local client portal (e.g., `http:///osticket/`), click “Open a New Ticket,” select a help topic (e.g., “Hardware”), and submit. Configure help topics in the admin panel (e.g., `http:///osticket/scp`, Admin Panel → Manage → Help Topics). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. Copy the ticket details into the Markdown template. +- **Option 3: Local osTicket (Recommended for Learning)**: Access your local client portal (e.g., `http:///osticket/`), click “Open a New Ticket,” select a help topic (e.g., “Hardware”), and submit. Configure help topics in the admin panel (e.g., `http:///osticket/scp`, Admin Panel → Manage → Help Topics). Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. Copy the ticket details into the Markdown template. -- **Example**: For a “Unable to print” issue, post in GitHub Discussions (`Tickets` category) with details, write `/tickets/printer-failure.md` directly, or test it in your local osTicket instance and document it in `/tickets/`. +- **Example**: For a “Unable to print” issue, post in GitHub Discussions (`Tickets` category) with details, write `/tickets/printer-failure.md` directly, or test it in your local osTicket instance and document it in `/tickets/`. - **Inspiration**: Browse existing examples in the `/tickets/` folder and the `Tickets` category in Discussions. - **Roles**: See [docs/ROLES.md](docs/ROLES.md) for tiers and escalation patterns. - **Metrics**: See [docs/METRICS.md](docs/METRICS.md) for lightweight fields to add to Tickets/KBs. @@ -167,14 +167,14 @@ Folder guide: see [tickets/README.md](tickets/README.md) **Tips**: -- Use GitHub Discussions (`Tickets` category) to share real-world tech support issues you’ve encountered. +- Use GitHub Discussions (`Tickets` category) to share real-world tech support issues you’ve encountered. - Test tickets in your local osTicket instance (if set up) to simulate a real helpdesk. -- Follow the CompTIA A+ six-step model (see “Troubleshooting Philosophy”). +- Follow the CompTIA A+ six-step model (see “Troubleshooting Philosophy”). - Submit your ticket as a pull request in the `/tickets/` folder. ### Creating KB Articles -KB articles document solutions from solved tickets. Share them in GitHub Discussions (`Knowledge Base` category) or write them in Markdown for `/kb/`. Optionally, test them in your local osTicket instance’s admin/staff panel. +KB articles document solutions from solved tickets. Share them in GitHub Discussions (`Knowledge Base` category) or write them in Markdown for `/kb/`. Optionally, test them in your local osTicket instance’s admin/staff panel. Template: copy `/kb/000.kb-template.md` to `/kb/.md` and complete the fields. @@ -183,9 +183,9 @@ Folder guide: see [kb/README.md](kb/README.md) **Tips**: - Share KB drafts in GitHub Discussions (`Knowledge Base` category) for feedback. -- Use your local osTicket admin/staff panel (e.g., `http:///osticket/scp`) to draft KB articles, if set up. Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. +- Use your local osTicket admin/staff panel (e.g., `http:///osticket/scp`) to draft KB articles, if set up. Replace `` with your VM’s IP (use `ip addr show` in the terminal). Keep this private—do not share personal IPs in public contributions. - Ensure steps are clear, reproducible, and tested. -- Keep verification concise (1–2 lines). For full commands and environment, link to the related Lab. +- Keep verification concise (1–2 lines). For full commands and environment, link to the related Lab. - Submit as a pull request in the `/kb/` folder. ### Creating Labs @@ -206,24 +206,32 @@ Folder guide: see [labs/README.md](labs/README.md) ### Creating Scenarios -Scenarios stitch together one or more tickets, a KB article, and an optional lab into an end-to-end learning flow. Use them to show how a real incident moves from report → resolution → documentation → practice. -## When to create a scenario +Scenarios stitch together one or more tickets, a KB article, and an optional lab into an end-to-end learning flow. Use them to show how a real incident moves from report → resolution → documentation → practice. + +#### When to create a scenario + - You have at least one ticket and a corresponding KB article; a lab is recommended but optional. - You want a guided narrative that learners can follow front-to-back. -## How to author + +#### How to author + - Start from the template at `/scenarios/000.scenario-template.md`. - Create a new file under `/scenarios/`, e.g. `/scenarios/printer-outage-end-to-end.md`. - Fill in: - Related Ticket(s): link to one or more tickets, e.g. `/tickets/printer-failure.md`. - Related KB: link to your KB, e.g. `/kb/printer-spooler-restart.md`. - Related Lab: link if you have one, e.g. `/labs/restart-print-spooler.md`. - - Overview, Flow (Ticket → KB → Lab), Success Criteria. -## Submission + - Overview, Flow (Ticket → KB → Lab), Success Criteria. + +#### Submission + - Open a PR with the new scenario file in `/scenarios/`. - In your PR description, briefly summarize the learning goals and link the related ticket/KB/lab. Folder guide: see [scenarios/README.md](scenarios/README.md) -## Tips + +### Tips + - Keep links relative so they work in GitHub and downstream clones. - Be explicit about pass/fail checks so learners can self-verify. - Prefer deep links to existing sections instead of rewriting steps, e.g.: `/kb/...#resolution-steps` and `/labs/...#verification`. @@ -231,4 +239,3 @@ Folder guide: see [scenarios/README.md](scenarios/README.md) ## Roadmap Note Public ticket submissions are not yet enabled. If a central osTicket instance is launched, it will likely allow public users to submit tickets via the client portal only, with the admin/staff panel restricted to maintainers. - diff --git a/docs/lamp-osticket-setup.md b/docs/lamp-osticket-setup.md index 0a709ff..e255e47 100644 --- a/docs/lamp-osticket-setup.md +++ b/docs/lamp-osticket-setup.md @@ -1,23 +1,23 @@ -# Deploying osTicket +# Deploying osTicket -This guide explains how to set up **osTicket v1.18.1**, a free helpdesk ticketing system, on **Ubuntu 24.04 Desktop** using **VirtualBox**. It’s written for beginners to help you get osTicket running step-by-step. Sensitive details (like passwords or IP addresses) are replaced with placeholders to keep things safe. +This guide explains how to set up **osTicket v1.18.1**, a free helpdesk ticketing system, on **Ubuntu 24.04 Desktop** using **VirtualBox**. It’s written for beginners to help you get osTicket running step-by-step. Sensitive details (like passwords or IP addresses) are replaced with placeholders to keep things safe. -**Warning**: This setup is for testing or development. Do **not** use it in production without adding HTTPS (SSL), a firewall, and other security measures (see “What to Do Next” section). +**Warning**: This setup is for testing or development. Do **not** use it in production without adding HTTPS (SSL), a firewall, and other security measures (see “What to Do Next” section). -## What You’ll Need +## What You’ll Need - A computer with **Oracle VirtualBox** installed (download from [virtualbox.org](https://www.virtualbox.org)). - The **Ubuntu 24.04 Desktop ISO** file (get it from [ubuntu.com](https://ubuntu.com)). -- A basic understanding of how to use a computer terminal (we’ll explain commands clearly!). -- About 1–2 hours to follow along. +- A basic understanding of how to use a computer terminal (we’ll explain commands clearly!). +- About 1–2 hours to follow along. ## Using Placeholders This guide uses placeholders for sensitive information: - Replace `YOUR_DB_PASSWORD` with a strong password (e.g., generate one with `openssl rand -base64 12` in the terminal). -- Replace `` with your VM’s IP address (find it by running `ip addr show` in the terminal and looking for the IP under `inet`, usually starting with `192.168.`). -- Replace `osticket-server.localdomain` with your VM’s hostname or IP if needed. +- Replace `` with your VM’s IP address (find it by running `ip addr show` in the terminal and looking for the IP under `inet`, usually starting with `192.168.`). +- Replace `osticket-server.localdomain` with your VM’s hostname or IP if needed. ## What This Guide Does @@ -25,7 +25,7 @@ This guide will help you: - Create a virtual machine (VM) in VirtualBox. - Install Ubuntu 24.04 Desktop on the VM. -- Set up a web server, database, and PHP (the “LAMP stack”). +- Set up a web server, database, and PHP (the “LAMP stack”). - Install osTicket v1.18.1 and make it secure. - Check that everything works. @@ -46,14 +46,14 @@ This guide will help you: ## Set Up Your Virtual Machine 1. Open VirtualBox and click **New** to create a virtual machine. -2. Name it (e.g., “osTicket-VM”). +2. Name it (e.g., “osTicket-VM”). 3. Choose **Linux** as the type and **Ubuntu (64-bit)** as the version. 4. Set these settings: - **CPUs**: 2 - **RAM**: 4 GB (or 8 GB if your computer has enough memory) - **Disk**: 40 GB (this gives space for tickets and logs) - - **Network**: Choose “Bridged Adapter” so the VM can connect to your network. - - **VT-x**: Enable in your computer’s BIOS if it’s not already on (check VirtualBox’s error messages if it fails). + - **Network**: Choose “Bridged Adapter” so the VM can connect to your network. + - **VT-x**: Enable in your computer’s BIOS if it’s not already on (check VirtualBox’s error messages if it fails). 5. Select the Ubuntu 24.04 Desktop ISO file when prompted and start the VM. ## Install Ubuntu @@ -64,7 +64,7 @@ This guide will help you: ## Set Up the Web Server and Database -1. Open the **Terminal** (search for it in Ubuntu’s menu or press `Ctrl + Alt + T`). +1. Open the **Terminal** (search for it in Ubuntu’s menu or press `Ctrl + Alt + T`). 2. Update your system and install Apache (web server), MySQL (database), PHP, and required tools: ```bash @@ -75,16 +75,16 @@ sudo systemctl enable --now apache2 mysql - **What this does**: Updates your system, installs the web server, database, and PHP, then starts them. -3. Check that Apache and MySQL are running: +1. Check that Apache and MySQL are running: ```bash systemctl status apache2 systemctl status mysql ``` -- **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. +- **What to look for**: You should see “active (running)” for both. Press `Ctrl + C` to exit each status check. -4. Confirm PHP is installed (version should be 7.2 or higher): +1. Confirm PHP is installed (version should be 7.2 or higher): ```bash php -v @@ -101,12 +101,12 @@ sudo mysql_secure_installation - Follow the prompts: - Keep the default `auth_socket` for local root access (just press Enter). - - Remove anonymous users (say “Yes”). - - Disallow remote root login (say “Yes”). - - Drop the test database (say “Yes”). - - Reload privileges (say “Yes”). + - Remove anonymous users (say “Yes”). + - Disallow remote root login (say “Yes”). + - Drop the test database (say “Yes”). + - Reload privileges (say “Yes”). -2. **Create a database and user for osTicket**: +1. **Create a database and user for osTicket**: - Log in to MySQL: ```bash @@ -128,7 +128,7 @@ FLUSH PRIVILEGES; EXIT; ``` -3. Verify MySQL version and authentication plugin: +1. Verify MySQL version and authentication plugin: ```sql SELECT VERSION(); @@ -139,8 +139,8 @@ SELECT VERSION(); ## Install osTicket Files 1. Download osTicket v1.18.1 from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). Save the ZIP file to your VM (e.g., in `/tmp`). -2. If the ZIP file doesn’t work (e.g., corrupt), download it again. -3. Extract the ZIP and copy the `upload/` folder contents to the web server’s directory: +2. If the ZIP file doesn’t work (e.g., corrupt), download it again. +3. Extract the ZIP and copy the `upload/` folder contents to the web server’s directory: ```bash sudo cp -r /tmp/upload/* /var/www/html/osticket/ @@ -152,7 +152,7 @@ sudo cp -r /tmp/upload/* /var/www/html/osticket/ sudo mv /tmp/upload /var/www/html/osticket ``` -4. Set the correct ownership so the web server can access the files: +1. Set the correct ownership so the web server can access the files: ```bash sudo chown -R www-data:www-data /var/www/html/osticket @@ -167,7 +167,7 @@ sudo chown -R www-data:www-data /var/www/html/osticket sudo nano /etc/apache2/sites-available/osticket.conf ``` -- Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): +- Add this content (replace `osticket-server.localdomain` with your VM’s hostname or IP): ```apache @@ -185,7 +185,7 @@ sudo nano /etc/apache2/sites-available/osticket.conf - Save and exit (`Ctrl + O`, Enter, `Ctrl + X`). -2. Enable the site and URL rewriting: +1. Enable the site and URL rewriting: ```bash sudo a2ensite osticket.conf @@ -194,7 +194,7 @@ sudo systemctl daemon-reload sudo systemctl reload apache2 ``` -3. Check that the configuration is correct: +1. Check that the configuration is correct: ```bash sudo apache2ctl configtest @@ -204,7 +204,7 @@ sudo apache2ctl configtest ## Run the osTicket Web Installer -1. Open a web browser on the VM (or your host computer) and go to `http:///osticket/setup/` (replace `` with your VM’s IP address, found via `ip addr show` in the terminal). +1. Open a web browser on the VM (or your host computer) and go to `http:///osticket/setup/` (replace `` with your VM’s IP address, found via `ip addr show` in the terminal). 2. You should see the osTicket setup page. If not, check that Apache is running (`systemctl status apache2`). 3. Fill in the database details: - **Hostname**: `localhost` @@ -227,14 +227,14 @@ sudo apt install php-apcu sudo rm -rf /var/www/html/osticket/setup/ ``` -3. Lock down the config file so only the web server can read it: +1. Lock down the config file so only the web server can read it: ```bash sudo chmod 0444 /var/www/html/osticket/include/ost-config.php sudo chown root:www-data /var/www/html/osticket/include/ost-config.php ``` -4. Double-check file permissions: +1. Double-check file permissions: ```bash ls -l /var/www/html/osticket/include/ost-config.php @@ -263,7 +263,7 @@ SHOW TABLES; - You should see a list of tables (e.g., `ost_ticket`, `ost_user`). -4. Check for insecure files in the web directory (this should return nothing): +1. Check for insecure files in the web directory (this should return nothing): ```bash sudo find /var/www/html/osticket -type f -perm -o=w -ls @@ -272,22 +272,22 @@ sudo find /var/www/html/osticket -type d -perm -o=w -ls ## Troubleshooting Common Issues -- **Corrupt ZIP file**: If the osTicket ZIP doesn’t extract, it might have downloaded incorrectly. Re-download from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). -- **MySQL shows `->` prompt**: This means you didn’t finish a command. Type `;` to complete it or `\c` to cancel. +- **Corrupt ZIP file**: If the osTicket ZIP doesn’t extract, it might have downloaded incorrectly. Re-download from [GitHub](https://github.com/osTicket/osTicket/releases/tag/v1.18.1). +- **MySQL shows `->` prompt**: This means you didn’t finish a command. Type `;` to complete it or `\c` to cancel. - **ERROR 1064 in MySQL**: This happens if you press Enter too soon or use wrong syntax. Check your command and verify MySQL version: ```sql SELECT VERSION(); ``` -- **ERROR 1410 (GRANT)**: This means the user doesn’t exist or you’re not logged in as root. Use `sudo mysql` to log in as root. +- **ERROR 1410 (GRANT)**: This means the user doesn’t exist or you’re not logged in as root. Use `sudo mysql` to log in as root. ## What to Do Next **Important**: This setup is for testing only. For production, you must add security measures like HTTPS and a firewall to protect your osTicket instance. - Set up an email account for osTicket to send notifications (use a custom domain and a service like Gmail to avoid spam issues). -- Add HTTPS for security using Let’s Encrypt: +- Add HTTPS for security using Let’s Encrypt: ```bash sudo apt install certbot python3-certbot-apache @@ -320,4 +320,3 @@ mysqldump -u osticketuser -p osticket > /backup/osticket_db_$(date +%F).sql ```bash sudo apt update && sudo apt upgrade ``` - From 68911fc9f67b6d48d657d388f1a6432dc3cf38e9 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:56:22 -0700 Subject: [PATCH 24/27] fix(kb-template): remove extra blank line (MD012) --- kb/000.kb-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kb/000.kb-template.md b/kb/000.kb-template.md index 03df247..1bc1d2b 100644 --- a/kb/000.kb-template.md +++ b/kb/000.kb-template.md @@ -30,4 +30,4 @@ - Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] - Recurrence: [Yes/No, e.g., "No"] - External reference: [e.g., "HP Printer Manual, https://support.hp.com"] - + From 9d07f5b717914cdd567796dfe3dedd73018a3bee Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 06:59:59 -0700 Subject: [PATCH 25/27] fix(kb-template): normalize EOF whitespace/newlines (MD012) --- kb/000.kb-template.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/kb/000.kb-template.md b/kb/000.kb-template.md index 1bc1d2b..589ae9f 100644 --- a/kb/000.kb-template.md +++ b/kb/000.kb-template.md @@ -1,4 +1,4 @@ -# KB: [Short Title] +# KB: [Short Title] **Related Ticket(s):** /tickets/[filename].md **Category:** Hardware | Software | Network | Account | Other @@ -30,4 +30,3 @@ - Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] - Recurrence: [Yes/No, e.g., "No"] - External reference: [e.g., "HP Printer Manual, https://support.hp.com"] - From bbf56e2539c274080fcb17d20ab85646e7318e38 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 07:04:58 -0700 Subject: [PATCH 26/27] docs(contributing): add optional local lint + pre-commit hook tip --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd96015..42a25e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -236,6 +236,28 @@ Folder guide: see [scenarios/README.md](scenarios/README.md) - Be explicit about pass/fail checks so learners can self-verify. - Prefer deep links to existing sections instead of rewriting steps, e.g.: `/kb/...#resolution-steps` and `/labs/...#verification`. +## Local Lint (Optional) + +Before you commit, you can run the Markdown linter locally to catch spacing/format issues early: + +- Windows PowerShell: + +```powershell +npx -y markdownlint-cli2 +``` + +Optional Git hook (runs locally, does not affect CI): + +1. Create a file at `.git/hooks/pre-commit` with the following and make sure it’s executable in your Git environment: + +```bash +#!/usr/bin/env bash +set -euo pipefail +npx -y markdownlint-cli2 +``` + +1. Save. The hook will block commits that fail linting. You can always run the linter manually if you prefer. + ## Roadmap Note Public ticket submissions are not yet enabled. If a central osTicket instance is launched, it will likely allow public users to submit tickets via the client portal only, with the admin/staff panel restricted to maintainers. From de92539b432ea569d0ac45680e0d7140f861c020 Mon Sep 17 00:00:00 2001 From: iplaycomputer Date: Mon, 29 Sep 2025 07:07:00 -0700 Subject: [PATCH 27/27] chore: sync kb template whitespace (no-op) --- kb/000.kb-template.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/kb/000.kb-template.md b/kb/000.kb-template.md index 589ae9f..3d056ae 100644 --- a/kb/000.kb-template.md +++ b/kb/000.kb-template.md @@ -1,32 +1,32 @@ # KB: [Short Title] -**Related Ticket(s):** /tickets/[filename].md -**Category:** Hardware | Software | Network | Account | Other -**Environment:** [OS, system, or software version, e.g., "Windows 10, HP LaserJet Pro"] +**Related Ticket(s):** /tickets/[filename].md +**Category:** Hardware | Software | Network | Account | Other +**Environment:** [OS, system, or software version, e.g., "Windows 10, HP LaserJet Pro"] -**Owner:** [Your name or team] -**Last Reviewed:** [YYYY-MM-DD] -**Next Review Due:** [YYYY-MM-DD] +**Owner:** [Your name or team] +**Last Reviewed:** [YYYY-MM-DD] +**Next Review Due:** [YYYY-MM-DD] ## Resolution Steps -1. [Step 1, e.g., "Open Services.msc and locate Print Spooler"] -2. [Step 2, e.g., "Restart the service"] -3. Verification: [Confirm the outcome, e.g., "Print a test page to ensure success"] +1. [Step 1, e.g., "Open Services.msc and locate Print Spooler"] +2. [Step 2, e.g., "Restart the service"] +3. Verification: [Confirm the outcome, e.g., "Print a test page to ensure success"] ## Troubleshooting Notes -- [Escalation guidance, e.g., "If restarting fails, check driver compatibility"] -- [Known limitations, e.g., "Solution may not work for network printers"] -- [Logs or outputs, e.g., "Check /var/log/syslog for errors"] +- [Escalation guidance, e.g., "If restarting fails, check driver compatibility"] +- [Known limitations, e.g., "Solution may not work for network printers"] +- [Logs or outputs, e.g., "Check /var/log/syslog for errors"] ## Linked Incidents -- /tickets/[incident1].md -- /tickets/[incident2].md +- /tickets/[incident1].md +- /tickets/[incident2].md ## Metrics / References -- Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] -- Recurrence: [Yes/No, e.g., "No"] +- Mean Time to Resolution (MTTR): [Optional, e.g., "10 minutes"] +- Recurrence: [Yes/No, e.g., "No"] - External reference: [e.g., "HP Printer Manual, https://support.hp.com"]