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
2. Build Pipeline — Gitea Actions
3. Unraid — Add the Registry
4. Unraid — Install the Container
5. Environment Variables Reference
6. Volume Paths Reference
7. First-Run Steps
8. Upgrading
9. Backups
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:

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

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

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