initial release testing
This commit is contained in:
175
UNRAID.md
Normal file
175
UNRAID.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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
|
||||
|
||||
```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 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
|
||||
Reference in New Issue
Block a user