jason/stepview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

installation documentation
Build and Push Docker Image / build (push) Successful in 10s
Details

Browse Source
This commit is contained in:
jason
2026-04-22 15:56:11 -05:00
parent 15ad777f2b
commit cf3f8d6fd0
2 changed files with 281 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/settings.local.json
+2 -1
View File
@@ -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\")"
]
}
}
INSTALL.md
+279 -73
View File
@@ -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 <target-repo>
Copy-Item hubs -Destination <target-repo> -Recurse
Copy-Item skills -Destination <target-repo> -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/<OWNER>/stepview:latest
```
If you also want the explanatory readme:
### Verify the secrets exist
```powershell
Copy-Item README.md -Destination <target-repo>
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/<OWNER>/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/<OWNER>/stepview:latest` |
| Network Type | `Bridge` |
| Console shell command | `Shell` |
## Updating The Bundle
> Replace `<OWNER>` 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://<UNRAID-IP>:<HOST-PORT>/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.