From c317480897950500ce8c92686cca3f79d2749c50 Mon Sep 17 00:00:00 2001 From: C-West8 <125926137+C-West8@users.noreply.github.com> Date: Wed, 22 Jul 2026 18:07:19 -0500 Subject: [PATCH] adding guide for nick --- GETTING-STARTED.md | 520 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 GETTING-STARTED.md diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md new file mode 100644 index 0000000..1b4eaaf --- /dev/null +++ b/GETTING-STARTED.md @@ -0,0 +1,520 @@ +# Getting Started — Project SDE Meeting Toolkit + +**A step-by-step, no-experience-needed guide to running this app on your own computer and changing it with Claude Code.** + +Hi! This guide assumes you have **never written code before**. Every step tells you +exactly what to click, type, or copy. You will mostly be copying commands and pressing +Enter. Take it one step at a time and you'll be fine. + +- **Time needed:** about 30–45 minutes the first time (most of it is downloads installing). +- **Can I break anything?** No. Everything runs only on your computer. If something gets + messed up, the [Troubleshooting](#if-something-goes-wrong) section fixes it, and worst + case you can delete the folder and start over. +- **What you'll have at the end:** the meeting-tools website running on your own machine, + plus the ability to ask Claude Code to change it and watch the changes appear instantly. + +--- + +## Table of contents + +1. [What we're setting up (in plain English)](#1-what-were-setting-up-in-plain-english) +2. [How to use the "terminal"](#2-how-to-use-the-terminal) +3. [Step-by-step: install the tools](#3-install-the-tools) +4. [Step-by-step: get the project onto your computer](#4-get-the-project-onto-your-computer) +5. [Step-by-step: run the app](#5-run-the-app) +6. [Step-by-step: change something with Claude Code](#6-change-something-with-claude-code) +7. [Everyday use (quick reference)](#7-everyday-use--quick-reference) +8. [If something goes wrong](#if-something-goes-wrong) +9. [Word glossary](#word-glossary) + +--- + +## 1. What we're setting up (in plain English) + +The **app** is the website with the two meeting tools (Field Problem Workshop and Scope +Lock Suite). To run it on your computer, it needs three helpers: + +| Helper | What it does | Why you need it | +|---|---|---| +| **Node.js** | Runs the website's code on your computer. | The app is written in a language Node understands. | +| **Docker Desktop** | Runs a small **database** for us in the background. | The app saves its data in a database. Docker lets us start one instantly without installing a database by hand (that part is genuinely painful, so we skip it). | +| **Claude Code** | An AI assistant you talk to in the terminal. | This is how you'll change ("tweak") the app without writing code yourself. | + +You'll also install **VS Code** (a friendly editor — you'll use it to download the project +and to open the terminals you type commands into) and **Git** (a behind-the-scenes tool VS +Code and Claude use to download the code and save your changes — you won't use it directly). +Don't worry about what any of these are yet — just follow along. + +Here's the picture of what you're building: + +``` + Your computer + ┌─────────────────────────────────────────────┐ + │ │ + │ Docker ─► Database (stores the data) │ + │ ▲ │ + │ │ │ + │ Node ─► The app ─► http://localhost:5180 │ ◄── you open this in your browser + │ ▲ │ + │ │ │ + │ Claude Code ──┘ (you ask it to change the app) │ + │ │ + └─────────────────────────────────────────────┘ +``` + +--- + +## 2. How to use the "terminal" + +A **terminal** is a window where you type commands instead of clicking buttons. On Windows +the one we'll use is called **PowerShell**. + +**To open it:** press the **Windows key**, type `powershell`, and click **Windows +PowerShell**. A dark or blue window opens with a blinking cursor. That's it. + +> **Use PowerShell, not "Command Prompt" (cmd).** Windows has an older, similar-looking +> black window called *Command Prompt* or *cmd*. Some of the commands in this guide only +> work in **PowerShell**, so always start from the "Windows PowerShell" app as described +> above. If your window's cursor line starts with `PS C:\...>`, you're in the right one. + +A few things to know (this guide is Windows-only, so everything below is written for +PowerShell): + +- A **command** is a line of text you paste in and then press **Enter** to run. +- **To paste** into PowerShell: right-click inside the window (or press `Ctrl+V`). Then + press **Enter**. +- When a command finishes, you get your blinking cursor back on a new line. If it's still + "thinking," just wait. +- If you ever want to **stop** something that's running, click the window and press + **`Ctrl + C`**. +- Commands are picky about spelling and spaces. Copy-paste them exactly rather than + retyping. + +Try it now: paste this and press Enter. It just prints a message, to prove pasting works. + +```powershell +echo "Hello, I can use the terminal" +``` + +--- + +## 3. Install the tools + +Install these one at a time. **Some of them may already be on your work computer** — so +for each one, **run the "check" command first**. If it prints a version number, that tool +is already installed and you can skip straight to the next one. Only download it if the +check says the command isn't recognized. + +After any install, **close and reopen PowerShell** so it notices the new tool, then run the +check again to confirm. + +### 3a. Node.js + +**First, check if it's already installed.** In PowerShell, run: + +```powershell +node -v +npm -v +``` + +If you see two version numbers (for example `v20.11.1` and `10.2.4`), Node is already +installed — **skip to 3b**. (`npm` comes bundled with Node; you never install it +separately.) If instead you see a message like "node is not recognized," install it: + +1. Go to ****. +2. Click the button that says **LTS** (it will have a version number like "20.x.x LTS"). + LTS means the stable, recommended version. +3. Open the downloaded file and click **Next → Next → Install → Finish**. Accept all the + defaults. If it asks about "Tools for Native Modules," you can leave that unchecked. +4. Close PowerShell, open a fresh one, and run `node -v` and `npm -v` again to confirm you + now get version numbers. + +### 3b. Docker Desktop + +**First, check if it's already installed.** Run: + +```powershell +docker --version +``` + +If you see a version number, Docker is installed — just make sure the app is running +(Windows key → type "Docker" → open **Docker Desktop**, and wait for the whale icon by the +clock to go steady), then **skip to 3c**. Otherwise, install it: + +1. Go to **** and download **Docker + Desktop for Windows**. +2. Run the installer, accept the defaults, and let it finish. It may ask you to **restart + your computer** — go ahead. +3. After restarting, **open Docker Desktop** (Windows key → type "Docker" → click it). The + first launch takes a minute. Accept the service agreement if asked. +4. **Leave Docker Desktop running.** You'll know it's ready when the little whale icon + near the clock (bottom-right of your screen) is steady, not animating. Docker must be + running whenever you use the app. +5. Close and reopen PowerShell, then run `docker --version` again to confirm. + +> Docker Desktop on Windows uses something called WSL2. If the installer offers to set it +> up, say yes. If you hit an error about WSL, run PowerShell **as Administrator** (right- +> click PowerShell → "Run as administrator") and paste `wsl --install`, then restart. + +### 3c. Git + +**First, check if it's already installed.** Run: + +```powershell +git --version +``` + +If you see a version number, skip to 3d. Otherwise, install it: + +1. Go to ****. The download starts automatically. +2. Run the installer. There are a lot of screens — **just click Next through all of them** + and then Install. The defaults are fine. +3. Close and reopen PowerShell, then run `git --version` again to confirm. + +### 3d. VS Code + +VS Code is the editor you'll use to download the project and to open a terminal. We'll use +it in Step 4, so please install it. + +**First, check if it's already installed:** press the **Windows key** and type +`Visual Studio Code`. If it shows up, it's installed — skip to 3e. Otherwise: + +- Download from **** and run the installer. +- On the installer's "Select Additional Tasks" screen, **tick the "Open with Code" + checkboxes** — it makes things easier later. Then finish with the defaults. + +### 3e. Claude Code + +This is the AI assistant you'll use to change the app. + +**First, check if it's already installed.** Run: + +```powershell +claude --version +``` + +If you see a version number, skip to Step 4. Otherwise, now that Node is installed (3a), +install Claude Code with one command: + +```powershell +npm install -g @anthropic-ai/claude-code +``` + +The `-g` means "install it for the whole computer." When it finishes, close and reopen +PowerShell and confirm: + +```powershell +claude --version +``` + +You'll log in the first time you actually start it (in Step 6) — it opens your browser to +sign in with your Anthropic account. If you don't have an account yet, ask whoever gave +you this project which login to use. + +--- + +## 4. Get the project onto your computer + +You'll download ("clone") the project from our internal Gitea site straight into VS Code. +Don't download a ZIP — cloning from Gitea keeps your copy connected to the real project so +you can pull in updates later. + +We'll do this entirely through VS Code's menus — **no typing commands.** + +1. **Open VS Code** (Windows key → type `Visual Studio Code` → Enter). +2. Open the **Command Palette**: press **`Ctrl + Shift + P`**. A search box drops down from + the top. +3. Type **`Git: Clone`** and click it when it appears in the list. +4. It asks for a repository URL. Paste this exact address and press **Enter**: + + ``` + https://primegit.primecontrols-dev.com/c.west/nick-sde-value-driver-website.git + ``` + +5. A file window opens asking **where to put the project.** Choose your **Documents** + folder and click **Select as Repository Destination**. (VS Code creates a + `nick-sde-value-driver-website` folder inside it for you.) +6. The first time, a browser window or a pop-up will ask you to **sign in** to the internal + Gitea site — use your work login. If it asks to allow the "GitHub"/"Git" extension to + sign in, allow it. +7. When it finishes downloading, VS Code shows a notification in the bottom-right: + **"Would you like to open the cloned repository?"** Click **Open**. + +You should now see the project's files listed in the panel on the left side of VS Code +(names like `src`, `package.json`, `docker-compose.yml`, and `GETTING-STARTED.md` — this +guide). That means it worked. Keep VS Code open for the next step. + +> If you don't have the Gitea link or can't sign in, ask the person who shared this project +> with you — you need access to that internal site to download the code. + +--- + +## 5. Run the app + +From here on, all commands go into a terminal that is **inside the project folder**. The +easiest way to get one is to use the terminal built into VS Code — because you opened the +project there in Step 4, it already starts in the right place. + +### 5a. Open the terminal inside VS Code + +1. With the project open in VS Code, click the **Terminal** menu at the top → **New + Terminal**. (Or press **`` Ctrl + ` ``** — that's the key just above Tab, to the left of + the `1` key.) +2. A panel opens at the bottom of VS Code with a blinking cursor. This is your PowerShell + terminal, and it's already sitting inside the project folder. +3. Make sure it's PowerShell: the line should start with `PS` followed by a path ending in + `nick-sde-value-driver-website`. If it says something else, click the small **dropdown + arrow (⌄)** next to the `+` at the top-right of the terminal panel, choose **Select + Default Profile → Windows PowerShell**, then open a New Terminal again. + +To double-check you're in the right place, type this and press Enter: + +```powershell +ls +``` + +You should see names like `package.json`, `src`, `docker-compose.yml`, and this +`GETTING-STARTED.md`. If you do, you're ready. **Use this VS Code terminal for all the +commands below.** + +### 5b. Create your settings file + +The app reads its settings from a file named `.env`. There's a ready-made template called +`.env.example`. Copy it — **the default values already match the database we're about to +start, so you don't need to edit anything.** + +```powershell +Copy-Item .env.example .env +``` + +### 5c. Start the database (with Docker) + +Make sure **Docker Desktop is running** (steady whale icon). Then start just the database: + +```powershell +docker compose up -d db +``` + +- The first time, Docker downloads the database software — this can take a minute or two. +- `-d` means "run it in the background," so you get your cursor back. +- The database automatically creates the tables it needs on first startup. You don't have + to do anything. + +Check it's running: + +```powershell +docker compose ps +``` + +You should see a `db` line with status `running` (or `healthy`). Leave it running in the +background. + +### 5d. Install the app's building blocks + +The app depends on some code libraries. This command downloads them into the folder. It's +a **one-time** step (you only re-run it if someone changes the dependencies later). + +```powershell +npm install +``` + +It prints a lot of text and takes a minute. A few warnings in yellow are normal. As long +as it ends without a big red `ERR!` block, you're good. + +### 5e. Start the app + +```powershell +npm run dev +``` + +After a moment you'll see something like: + +``` + VITE ready + ➜ Local: http://localhost:5180/ +``` + +**Open your browser and go to ** — the app appears! Try the dark- +mode button in the top bar, click into the tools, enter some text. + +Important: + +- **Keep this terminal open.** As long as it's running, the app is live. If you close it + (or close VS Code), the app stops. +- To **stop** the app, click inside that terminal and press **`Ctrl + C`**. +- The address is `localhost`, which just means "this computer." Only you can see it — it's + not on the internet. + +🎉 The app is now running on your machine. Next, let's change something. + +--- + +## 6. Change something with Claude Code + +Here's the magic: while the app is running, you tell Claude Code what you want changed, and +the change shows up in your browser **automatically** — this is called "hot reload." + +### 6a. Open a *second* terminal (also in VS Code) + +Your first terminal is busy running the app — leave it alone. You'll open a **second** +terminal right next to it in VS Code: + +1. In the terminal panel at the bottom of VS Code, click the **`+`** (plus) button at its + top-right corner. This opens a fresh terminal alongside the first one — you'll see both + listed on the right side of the panel, and you can click between them. +2. The new terminal also starts inside the project folder, so you're ready to go. (Your + `npm run dev` keeps running in the other one the whole time.) + +### 6b. Start Claude Code + +```powershell +claude +``` + +The first time, it opens your browser to **log in** — follow the prompts. After that, +you'll see a prompt where you can type to Claude in plain English. + +### 6c. Ask for a change + +Type a request in normal words and press Enter. Some examples to try: + +- `Change the heading on the home page from "Meeting Toolkit" to "SDE Meeting Tools".` +- `Make the "Open →" links on the home page cards bright green.` +- `Add a short sentence under the main heading explaining what the Scope Lock tool is for.` + +Claude will explain what it's about to do and make the edits. It may ask for your approval +before changing files — read what it says and approve if it looks right. **You can't +permanently break anything** — see "undo" below. + +### 6d. Watch it happen + +Switch to your browser at and **refresh if needed**. Your change +is there. Keep chatting with Claude to refine it: `a bit darker green`, `undo that`, `move +it above the heading`, and so on. + +### 6e. Undoing changes + +If you don't like a change, just ask Claude in plain English: `undo the last change`, `put +the heading back the way it was`, or `undo everything you've changed today`. Claude keeps +track and can walk it back for you — you don't need to know how it does that. + +### 6f. When you're happy — saving your work to the repo + +Your changes so far live only on your computer. When you want to keep them and put them +back into the shared project, **just ask Claude** — for example: + +- `Save my changes and put them in the repo with a short description of what I did.` + +Claude handles all the behind-the-scenes steps for you. If it needs anything from you (like +confirming your login), it'll ask in plain language. You don't need to learn any of the +commands yourself — describe what you want and let Claude do it. + +--- + +## 7. Everyday use — quick reference + +Once everything is installed, starting up each day is quick: + +1. Make sure **Docker Desktop is running** (open it from the Start menu; wait for the steady + whale icon). +2. **Open the project in VS Code** (it should appear under **File → Open Recent**, or reopen + the `nick-sde-value-driver-website` folder). +3. Open a terminal (**Terminal → New Terminal**) and run these two commands: + +```powershell +# make sure the database is up (safe to run even if it already is) +docker compose up -d db + +# start the app (leave this terminal running while you work) +npm run dev +``` + +Then open in your browser. Open a **second** terminal in VS Code +(the **`+`** button in the terminal panel) and run `claude` to make changes. + +**Shutting down:** + +```powershell +# in the app's terminal: press Ctrl + C to stop the app +# then, if you want to stop the database too: +docker compose stop +``` + +Your data is safe when you stop — it's stored by Docker and will be there next time. (See +Troubleshooting for how to wipe it if you ever want a clean slate.) + +--- + +## If something goes wrong + +**"The app won't open in my browser / the page is blank."** +Check the first VS Code terminal is still running `npm run dev` and shows a `Local:` +address. Make sure you typed the address exactly: `http://localhost:5180`. If the terminal +shows a red error, copy it and paste it to Claude Code and ask what's wrong. + +**"Port 5180 is already in use" (or the app won't start).** +Something else is using that address — usually an old copy of the app still running. Close +any other terminals running the app (or close and reopen VS Code, or restart your +computer), then try `npm run dev` again. + +**"Cannot connect to the database" / errors mentioning `ECONNREFUSED` or `5432`.** +The database isn't running. Make sure **Docker Desktop is open**, then run +`docker compose up -d db` and wait until `docker compose ps` shows it `running`/`healthy`. + +**"docker: command not found" or "Docker Desktop is not running."** +Open Docker Desktop from the Start menu and wait for the whale icon to go steady. Then +retry your command. + +**`npm install` ended with red `ERR!` text.** +Make sure you're in the project folder (`ls` should show `package.json`). Try running it +once more. If it still fails, copy the red text to Claude Code and ask for help. + +**"claude: command not found."** +Close and reopen the VS Code terminal (it needs to pick up the new install) — the quickest +way is to close VS Code entirely and reopen the project. If it still isn't found, re-run +`npm install -g @anthropic-ai/claude-code`. + +**I want to erase all the app's saved data and start clean.** +This deletes the database contents (the tables get re-created empty next start): + +```powershell +docker compose down -v +docker compose up -d db +``` + +**When in doubt:** you have an AI assistant right here. In the second terminal, run +`claude` and describe what happened in plain English — paste any red error text. That's +literally what it's for. + +--- + +## Word glossary + +- **Terminal / PowerShell** — the window where you type commands. +- **Command** — a line of text you paste and run by pressing Enter. +- **Node.js** — the program that runs the app's code on your computer. +- **npm** — comes with Node; downloads and manages the app's code libraries. ("npm install" + fetches them; "npm run dev" starts the app.) +- **Docker** — runs the database for us in a self-contained box, so we don't install a + database by hand. +- **Database** — where the app stores the data people enter. +- **Dependencies / libraries** — pre-written code the app relies on, downloaded by + `npm install` into a `node_modules` folder. +- **`.env` file** — a small settings file the app reads on startup. +- **localhost** — "this computer." `http://localhost:5180` is the app running only on your + machine. +- **Port** — a numbered "door" on your computer. The app uses door `5180`; the database + uses `5432`. +- **Hot reload** — when you change the code, the running app updates in the browser by + itself. +- **Git** — a behind-the-scenes tool that downloads the project and saves changes. VS Code + and Claude use it for you; you don't run it yourself. +- **Repository ("repo")** — the project stored on our internal Gitea site (its code plus + its history). Your copy on your computer is connected to it. +- **Gitea** — our internal website where the project lives, like a private GitHub. +- **Claude Code** — the AI assistant in the terminal you ask to change the app. + +--- + +*Stuck on a step? Open Claude Code (`claude`) in the project folder and describe exactly +what you see. It can read this guide and walk you through it.*