inven/UNRAID.md

Unraid Installation Guide

This document is part of the install contract for this repository.

If a change would alter how the container is built, started, configured, mapped, or authenticated, this file must be updated in the same change.

What You Need

• Unraid server with Docker enabled
• Network access from Unraid to clone the repository
• A persistent appdata location for the SQLite database
• Initial admin credentials and a long random auth secret

Required Environment Variables

• DATABASE_PATH Recommended: /data/inven.sqlite
• AUTH_SECRET Use a long random string. This signs login sessions.
• ADMIN_EMAIL Initial bootstrap admin email.
• ADMIN_PASSWORD Initial bootstrap admin password.

Important:

• The bootstrap admin is created only when the database has no users yet.
• Changing ADMIN_EMAIL or ADMIN_PASSWORD after first boot does not replace an existing user automatically.
• Keep AUTH_SECRET stable after deployment. Rotating it will invalidate active sessions.

CLI Build And Run

These steps are useful if you want to build on the Unraid host or another Linux machine before using the Unraid GUI.

1. Clone the repository

git clone <YOUR-REPOSITORY-URL> inven
cd inven

2. Build the image

docker build -t inven:latest .

3. Create a persistent data directory

Example:

mkdir -p /mnt/user/appdata/inven/data

4. Run the container

docker run -d \
  --name inven \
  -p 3000:3000 \
  -v /mnt/user/appdata/inven/data:/data \
  -e DATABASE_PATH=/data/inven.sqlite \
  -e AUTH_SECRET='replace-with-a-long-random-secret' \
  -e ADMIN_EMAIL='admin@example.com' \
  -e ADMIN_PASSWORD='replace-with-a-strong-password' \
  --restart unless-stopped \
  inven:latest

5. Open the app

• URL: http://<UNRAID-IP>:3000
• Sign in with the configured bootstrap admin credentials

Unraid GUI Setup

These instructions assume you are creating a custom Docker container in the Unraid web UI.

1. Build or provide an image

You need an image first. Use one of these paths:

• Build from the CLI steps above and tag/push it to a registry you can pull from Unraid
• Or build locally on the Unraid host and reference that image name directly

Example image name:

• inven:latest

2. Add the container in Unraid

In the Unraid Docker tab:

1. Click Add Container
2. Set Name to inven
3. Set Repository to your image, for example inven:latest
4. Set Network Type to bridge

3. Configure ports

Add this port mapping:

• Container Port: 3000
• Host Port: 3000
• Connection Type: TCP

If 3000 is already in use on the host, choose a different host port such as 8087.

4. Configure paths

Add this path mapping:

• Name: data
• Container Path: /data
• Host Path: /mnt/user/appdata/inven/data
• Access Mode: Read/Write

This path stores the SQLite database and must be persistent.

5. Configure environment variables

Add these variables:

• DATABASE_PATH Value: /data/inven.sqlite
• AUTH_SECRET Value: a long random secret
• ADMIN_EMAIL Value: your initial admin email
• ADMIN_PASSWORD Value: your initial admin password

6. Apply and start

1. Click Apply
2. Start the container
3. Open http://<UNRAID-IP>:3000
4. Log in with ADMIN_EMAIL and ADMIN_PASSWORD

Updating The Container

When app changes do not require install changes:

1. Pull or rebuild the updated image
2. Recreate the container with the same /data mapping
3. Keep DATABASE_PATH and AUTH_SECRET consistent

When app changes do require install changes:

• Update this document
• Update .env.example
• Update the README install section if needed

Troubleshooting

App starts but login does not work

• Confirm ADMIN_EMAIL and ADMIN_PASSWORD were present on first boot
• If the database already existed before auth was configured, the bootstrap user may not have been created
• Confirm AUTH_SECRET is set and stable

Sessions keep getting invalidated

• Confirm AUTH_SECRET is unchanged across restarts or image updates

Data disappears after container recreation

• Confirm /data is mapped to a persistent Unraid host path
• Confirm DATABASE_PATH=/data/inven.sqlite

Container starts but app is unreachable

• Confirm the host port is mapped correctly
• Confirm no other container is already using the selected host port