# 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.
- `AUTH_SECURE_COOKIES`
  Set to `false` for normal `http://` access on your LAN. Set to `true` only when the app is served over HTTPS.
- `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.
- If you access the app over plain HTTP and `AUTH_SECURE_COOKIES=true`, login will appear to work but the browser will not stay signed in.

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

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

### 2. Build the image

```bash
docker build -t inven:latest .
```

### 3. Create a persistent data directory

Example:

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

### 4. Run the container

```bash
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 AUTH_SECURE_COOKIES='false' \
  -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
- `AUTH_SECURE_COOKIES`
  Value: `false` for standard LAN HTTP access
- `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
- Confirm `AUTH_SECURE_COOKIES=false` if you are not serving the app over HTTPS

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