183 lines
4.8 KiB
Markdown
183 lines
4.8 KiB
Markdown
# 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
|