stepview/INSTALL.md

# StepView — Unraid Installation Guide

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.

---

## Table of Contents

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)

---

## 1. Prerequisites

| 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` |

---

## 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
```

### Verify the secrets exist

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
```

Or browse to `https://registry.alwisp.com` and verify the tag appears under your package.

---

## 3. Unraid — Add the Registry

Unraid needs credentials to pull from your private registry.

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:

   | Field | Value |
   |---|---|
   | Registry URL | `https://registry.alwisp.com` |
   | Username | Your registry username |
   | Password | Your registry token (same as `REGISTRY_TOKEN`) |

4. Click **Save**.

---

## 4. Unraid — Install the Container

### 4a. Open the Add Container dialog

Go to **Docker** tab → **Add Container** (or **Edit** if you are updating an existing one).

---

### 4b. Basic settings

| Field | Value |
|---|---|
| Name | `stepview` |
| Repository | `registry.alwisp.com/<OWNER>/stepview:latest` |
| Network Type | `Bridge` |
| Console shell command | `Shell` |

> Replace `<OWNER>` with the actual Gitea repository owner (e.g. `alwisp`).

---

### 4c. Port mapping

Click **Add another Path, Port, Variable, Label or Device** → **Port**.

| 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.