From cf3f8d6fd072bd11e70c8be2e9b37e6c6e663c4a Mon Sep 17 00:00:00 2001 From: jason Date: Wed, 22 Apr 2026 15:56:11 -0500 Subject: [PATCH] installation documentation --- .claude/settings.local.json | 3 +- INSTALL.md | 352 ++++++++++++++++++++++++++++-------- 2 files changed, 281 insertions(+), 74 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 5c48812..78c97b3 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -7,7 +7,8 @@ "Bash(npx vite *)", "Bash(timeout 8 npx tsx src/server/app.ts)", "Bash(node -e \"import\\('occt-import-js'\\).then\\(m => { console.log\\('occt-import-js loaded OK, keys:', Object.keys\\(m\\)\\) }\\).catch\\(e => console.error\\('FAIL:', e.message\\)\\)\")", - "Bash(timeout 8 npx tsx --env-file=.env src/server/app.ts)" + "Bash(timeout 8 npx tsx --env-file=.env src/server/app.ts)", + "Bash(del \"D:\\\\REMOTE CODING\\\\stepview\\\\.gitea\\\\workflows\\\\build.yml\")" ] } } diff --git a/INSTALL.md b/INSTALL.md index 250df3a..ff84651 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,105 +1,311 @@ -# Install and Copy Guide +# StepView — Unraid Installation Guide -Use this guide to copy the instruction suite into another repository without bloating the destination or confusing the agent. +This guide covers the full deployment path: building the Docker image via the Gitea CI runner, then installing and configuring the container through the Unraid Docker GUI. -## Recommended Install +--- -Copy these items into the target repository root: +## Table of Contents -- `AGENTS.md` -- `DEPLOYMENT-PROFILE.md` -- `SKILLS.md` -- `PROJECT-PROFILE-WORKBOOK.md` -- `ROUTING-EXAMPLES.md` -- `hubs/` -- `skills/` +1. [Prerequisites](#1-prerequisites) +2. [Build Pipeline — Gitea Actions](#2-build-pipeline--gitea-actions) +3. [Unraid — Add the Registry](#3-unraid--add-the-registry) +4. [Unraid — Install the Container](#4-unraid--install-the-container) +5. [Environment Variables Reference](#5-environment-variables-reference) +6. [Volume Paths Reference](#6-volume-paths-reference) +7. [First-Run Steps](#7-first-run-steps) +8. [Upgrading](#8-upgrading) +9. [Backups](#9-backups) +10. [Troubleshooting](#10-troubleshooting) -Optional: +--- -- `README.md` if you want human-facing explanation of the bundle in the destination repo +## 1. Prerequisites -## Fast Copy Workflow +| Requirement | Notes | +|---|---| +| Unraid 6.12 or later | Earlier versions work but UI steps may differ slightly | +| Gitea instance | Any version with Actions support (1.19+) | +| Gitea Actions runner | Registered to your Gitea instance, labeled `ubuntu-latest` | +| Docker runner image | `catthehacker/ubuntu:act-latest` (already in your workflow) | +| `REGISTRY_USER` secret | Set in Gitea repo → Settings → Secrets | +| `REGISTRY_TOKEN` secret | An access token with `package:write` scope on `registry.alwisp.com` | -From this repository root, copy the suite into another repo root while excluding `.git`: +--- -```powershell -Copy-Item AGENTS.md,DEPLOYMENT-PROFILE.md,SKILLS.md,PROJECT-PROFILE-WORKBOOK.md,ROUTING-EXAMPLES.md -Destination -Copy-Item hubs -Destination -Recurse -Copy-Item skills -Destination -Recurse +## 2. Build Pipeline — Gitea Actions + +The workflow at `.gitea/workflows/docker-build.yml` runs automatically on every push to `main`. It builds the image and pushes it to: + +``` +registry.alwisp.com//stepview:latest ``` -If you also want the explanatory readme: +### Verify the secrets exist -```powershell -Copy-Item README.md -Destination +In your Gitea repository, go to **Settings → Secrets and Variables → Actions** and confirm both of these are set: + +| Secret name | Value | +|---|---| +| `REGISTRY_USER` | Your registry username | +| `REGISTRY_TOKEN` | Registry access token (read/write) | + +### Trigger a build manually + +1. Go to your repository in Gitea. +2. Click the **Actions** tab. +3. Select **Build and Push Docker Image**. +4. Click **Run workflow** → **Run workflow**. + +### Confirm the image published + +Once the workflow passes, confirm the image is available: + +```bash +docker pull registry.alwisp.com//stepview:latest ``` -## Prefill Workflow +Or browse to `https://registry.alwisp.com` and verify the tag appears under your package. -Before deployment: +--- -1. Fill out `PROJECT-PROFILE-WORKBOOK.md`. -2. Translate the answers into agent-facing defaults in `DEPLOYMENT-PROFILE.md`. -3. Keep the deployment profile concise so it can be read early without wasting context. -4. Copy the suite with the filled-in deployment profile included. +## 3. Unraid — Add the Registry -At runtime: +Unraid needs credentials to pull from your private registry. -1. The agent reads `AGENTS.md`. -2. The agent reads `DEPLOYMENT-PROFILE.md` if it is filled in. -3. The agent reads `SKILLS.md`. -4. The agent opens the relevant hub and specialized skill files only as needed. +1. In the Unraid UI go to **Settings → Docker → Docker Hub Settings** (scroll to the bottom of the page or look for **Additional registries**). +2. Click **Add Registry**. +3. Fill in: -## Minimal Install + | Field | Value | + |---|---| + | Registry URL | `https://registry.alwisp.com` | + | Username | Your registry username | + | Password | Your registry token (same as `REGISTRY_TOKEN`) | -If the target repository wants the smallest useful setup, copy: +4. Click **Save**. -- `AGENTS.md` -- `DEPLOYMENT-PROFILE.md` -- `SKILLS.md` -- `hubs/` -- only the skill files the team expects to use often +--- -Good minimal baseline: +## 4. Unraid — Install the Container -- `skills/software/repo-exploration.md` -- `skills/software/feature-implementation.md` -- `skills/software/test-strategy.md` -- `skills/software/code-review.md` -- `skills/debugging/bug-triage.md` -- `skills/debugging/debugging-workflow.md` -- `skills/documentation/technical-docs.md` -- `skills/ui-ux/ux-review.md` +### 4a. Open the Add Container dialog -## How To Customize Safely +Go to **Docker** tab → **Add Container** (or **Edit** if you are updating an existing one). -- Keep `AGENTS.md` short and stable; put detail in hubs and skill files. -- Add repo-specific instructions near the top of `AGENTS.md` or in existing repo instruction files. -- Treat `DEPLOYMENT-PROFILE.md` as the canonical place for staged build, tool, environment, and workflow defaults. -- Prefer editing hub routing before adding more root-level rules. -- Add new skill files only when they introduce a distinct workflow, risk area, or deliverable. -- If two skills overlap heavily, merge them or make the routing distinction explicit. +--- -## Context Limit Guidance +### 4b. Basic settings -- Do not instruct the agent to load the entire `skills/` tree on every task. -- Keep the default path to one hub plus two to four specialized skills. -- Reserve four to six skills for large cross-functional tasks. -- Use the routing examples to confirm the suite still routes clearly after customization. +| Field | Value | +|---|---| +| Name | `stepview` | +| Repository | `registry.alwisp.com//stepview:latest` | +| Network Type | `Bridge` | +| Console shell command | `Shell` | -## Updating The Bundle +> Replace `` with the actual Gitea repository owner (e.g. `alwisp`). -- Pull improvements from this source repository into destination repos periodically. -- Refill the workbook and refresh the deployment profile when your preferred defaults change materially. -- Review local customizations before overwriting shared files. -- If a destination repo has stronger local conventions, keep those and treat this suite as the fallback layer. +--- -## Suggested Verification After Copying +### 4c. Port mapping -Check that the destination repo can answer these questions clearly: +Click **Add another Path, Port, Variable, Label or Device** → **Port**. -1. Where does the agent start? `AGENTS.md` -2. Where does the agent get preloaded defaults? `DEPLOYMENT-PROFILE.md` -3. Where does the agent look for available skills? `SKILLS.md` -4. How does the agent decide what to read next? Deployment profile, hubs, and routing examples -5. Does the repo still prioritize local instructions over the generic bundle? It should +| Field | Value | +|---|---| +| Container Port | `3000` | +| Host Port | `3000` | +| Protocol | `TCP` | +| Description | `StepView Web UI` | + +Change the host port if 3000 is already in use (e.g. use `7820`). Update `BASE_URL` to match. + +--- + +### 4d. Volume mappings + +Click **Add another Path, Port, Variable, Label or Device** → **Path** for each row below. + +#### App data (SQLite database) + +| Field | Value | +|---|---| +| Container Path | `/app/data` | +| Host Path | `/mnt/user/appdata/stepview/data` | +| Access Mode | `Read/Write` | +| Description | `StepView database` | + +#### Uploads (models, PDFs, brand assets) + +| Field | Value | +|---|---| +| Container Path | `/app/uploads` | +| Host Path | `/mnt/user/appdata/stepview/uploads` | +| Access Mode | `Read/Write` | +| Description | `StepView uploaded files` | + +> Both host directories are created automatically by Unraid on first container start if they do not exist. + +--- + +### 4e. Environment variables + +Click **Add another Path, Port, Variable, Label or Device** → **Variable** for each row below. + +See [Section 5](#5-environment-variables-reference) for a full description of every variable. + +| Variable | Example value | +|---|---| +| `NODE_ENV` | `production` | +| `PORT` | `3000` | +| `BASE_URL` | `http://192.168.1.X:3000` | +| `ADMIN_USER` | `admin` | +| `ADMIN_PASS` | `YourStrongPasswordHere` | +| `SESSION_SECRET` | *(random 32-char string — see below)* | +| `MAX_FILE_MB` | `500` | +| `BRAND_NAME` | `Your Company Name` | +| `BRAND_ACCENT` | `#3b82f6` | + +**Generating a session secret** — run this in any terminal and paste the output: + +```bash +openssl rand -hex 32 +``` + +--- + +### 4f. Apply and start + +Click **Apply**. Unraid will pull the image and start the container. Watch the log for: + +``` +StepView running on http://localhost:3000 +Admin: http://localhost:3000/admin +``` + +If `ADMIN_PASS` is still `changeme` you will also see a warning — change it before the app is network-accessible. + +--- + +## 5. Environment Variables Reference + +| Variable | Required | Default | Description | +|---|---|---|---| +| `NODE_ENV` | Yes | `production` | Runtime mode. Always `production` on Unraid. | +| `PORT` | No | `3000` | Port the app listens on inside the container. Match this to your container port mapping. | +| `BASE_URL` | Yes | — | Full public URL including port (e.g. `http://192.168.1.50:3000`). Used to generate shareable model links. Must be reachable by the people you share links with. | +| `ADMIN_USER` | No | `admin` | Admin login username. | +| `ADMIN_PASS` | Yes | `changeme` | Admin login password. **Change before exposing to any network.** The bcrypt hash is derived from this value at startup — changing it here and restarting the container takes effect immediately. | +| `SESSION_SECRET` | Yes | `dev-secret-change-me` | Secret used to sign session cookies. Use a random 32+ character string. Changing this invalidates all active admin sessions. | +| `MAX_FILE_MB` | No | `500` | Maximum upload file size in megabytes. Applies to models and PDFs. | +| `DATA_DIR` | No | `/app/data` | Path inside the container where the SQLite database is stored. Do not change unless you remapped the volume. | +| `UPLOADS_DIR` | No | `/app/uploads` | Path inside the container where uploaded files are stored. Do not change unless you remapped the volume. | +| `BRAND_NAME` | No | `StepView` | Bootstrap brand name shown in the UI. Can be overridden later in **Admin → Settings** without restarting. | +| `BRAND_ACCENT` | No | `#3b82f6` | Bootstrap accent colour (hex). Can be overridden later in **Admin → Settings**. | +| `TRUST_PROXY` | No | *(unset)* | Set to `true` if StepView sits behind a reverse proxy (e.g. Nginx Proxy Manager). Enables secure cookies over HTTPS. | + +--- + +## 6. Volume Paths Reference + +| Container path | Suggested host path | What it holds | +|---|---|---| +| `/app/data` | `/mnt/user/appdata/stepview/data` | `stepview.db` — all metadata, categories, settings | +| `/app/uploads` | `/mnt/user/appdata/stepview/uploads` | `models/` — STEP, STP, STL files + pre-processed geometry | +| | | `pdfs/` — attached shop diagram PDFs | +| | | `thumbnails/` — optional model thumbnail images | +| | | `brand/` — logo and favicon uploads | + +> **Tip:** If your Unraid share is on a spinning array, consider symlinking or remapping the `uploads` path to a cache-only SSD share for faster model serving. + +--- + +## 7. First-Run Steps + +1. Open `http://:/admin/login` in your browser. +2. Log in with the `ADMIN_USER` and `ADMIN_PASS` values you set. +3. If you see an amber warning banner about the default password, go to **Admin → Settings** and note the reminder — you change the password by updating the `ADMIN_PASS` variable in the Unraid Docker template and restarting the container. +4. Go to **Admin → Settings** to set your company name, logo, and accent colour. +5. Go to **Admin → Categories** and create any categories you need before uploading models. +6. Go to **Admin → Upload** to upload your first model. + - STEP/STP files are processed server-side on upload (geometry is pre-converted). Expect a few seconds for small files and up to a minute for large assemblies. + - STL files are ready immediately. +7. Once a model is uploaded, click the **copy link** icon in the dashboard and test it in a private/incognito window to confirm the public viewer works. + +--- + +## 8. Upgrading + +1. Push (or merge) changes to the `main` branch in Gitea. The Actions workflow will build and push a new `:latest` image automatically. +2. In Unraid, go to the **Docker** tab. +3. Click the StepView container icon → **Update** (or click **Check for updates** first to see if a new image is available). +4. Unraid will pull the new image and restart the container. Your data and uploads are preserved because they live on the host volumes. + +> **No database migrations are needed** for patch and minor updates in v0.x — the schema uses `CREATE TABLE IF NOT EXISTS` throughout. Major version bumps will document any required steps in the release notes. + +--- + +## 9. Backups + +The only two directories that matter for a full restore are: + +| Host path | Contents | +|---|---| +| `/mnt/user/appdata/stepview/data/` | SQLite database (`stepview.db`) | +| `/mnt/user/appdata/stepview/uploads/` | All uploaded files | + +### With Unraid's built-in backup (CA Backup/Restore) + +Add both paths to your CA Backup job. The database is a single file and is safe to copy while the container is running (SQLite WAL mode is enabled). + +### Manual snapshot + +```bash +# Run on the Unraid server or via SSH +tar -czf stepview-backup-$(date +%Y%m%d).tar.gz \ + /mnt/user/appdata/stepview/data \ + /mnt/user/appdata/stepview/uploads +``` + +--- + +## 10. Troubleshooting + +### Container won't start + +Check the Docker log in the Unraid UI (click the container icon → **Log**). + +| Symptom | Likely cause | Fix | +|---|---|---| +| `EACCES: permission denied` on `/app/data` or `/app/uploads` | Host directory owned by wrong user | On the Unraid console: `chmod -R 777 /mnt/user/appdata/stepview` | +| `address already in use :::3000` | Host port 3000 is taken | Change the host port mapping (e.g. to `7820`) and update `BASE_URL` | +| Container exits immediately | Missing required env var | Check that `BASE_URL`, `ADMIN_PASS`, and `SESSION_SECRET` are all set | + +### Admin login fails + +- Confirm `ADMIN_USER` and `ADMIN_PASS` match what you typed. +- The password hash is recomputed from `ADMIN_PASS` **at startup** — if you changed the variable, restart the container. +- Session cookies require the browser and container clock to agree. If your Unraid server clock is wrong, sessions will expire immediately. + +### STEP/STP model shows "not yet processed" + +The geometry conversion runs during the upload request. If it failed silently: + +1. Check the container log for a line containing `[stepConverter] conversion failed`. +2. The most common causes are corrupt STEP files or assemblies with zero meshes. +3. Delete the model from the admin dashboard and re-upload a known-good file. +4. If the file is valid but conversion still fails, open a Gitea issue with the file attached. + +### Share link returns 403 + +The model's visibility is set to **Private**. Toggle it to **Public** in the admin dashboard (click the green/grey visibility badge next to the model) or use the **Edit** page. + +### Viewer loads but model is black / invisible + +This is usually a scale issue with very small or very large models. Click the **Reset Camera** button (↺ icon, top-right of the viewer) to re-fit the camera. If it persists, check that the STEP conversion produced non-zero geometry in the container log. + +### Can't reach the app from outside the local network + +- Confirm `BASE_URL` is set to a hostname or IP that is reachable from outside (not `localhost`). +- If using Nginx Proxy Manager or another reverse proxy, set `TRUST_PROXY=true` so secure cookies work over HTTPS. +- Check your router/firewall allows the host port through.