-- Docs - | - Demo - | - Discord -
- -## Quick Start - -[Configuration & Docker Compose](https://hay-kot.github.io/homebox/quick-start) - -```bash -# If using the rootless image, ensure data -# folder has correct permissions -mkdir -p /path/to/data/folder -chown 65532:65532 -R /path/to/data/folder -docker run -d \ - --name homebox \ - --restart unless-stopped \ - --publish 3100:7745 \ - --env TZ=Europe/Bucharest \ - --volume /path/to/data/folder/:/data \ - ghcr.io/hay-kot/homebox:latest -# ghcr.io/hay-kot/homebox:latest-rootless -``` - - -## Contributing - -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. - -If you are not a coder, you can still contribute financially. Financial contributions help me prioritize working on this project over others and helps me know that there is a real demand for project development. - -
-## Credits
-
-- Logo by [@lakotelman](https://github.com/lakotelman)
diff --git a/SECURITY.md b/SECURITY.md
deleted file mode 100644
index 56b13b5..0000000
--- a/SECURITY.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Since this software is still considered beta/WIP support is always only given for the latest version.
-
-## Reporting a Vulnerability
-
-Please open a normal public issue if you have any security related concerns.
\ No newline at end of file
diff --git a/Taskfile.yml b/Taskfile.yml
deleted file mode 100644
index 4d9c1aa..0000000
--- a/Taskfile.yml
+++ /dev/null
@@ -1,157 +0,0 @@
-version: "3"
-
-env:
- HBOX_LOG_LEVEL: debug
- HBOX_STORAGE_SQLITE_URL: .data/homebox.db?_pragma=busy_timeout=1000&_pragma=journal_mode=WAL&_fk=1
- HBOX_OPTIONS_ALLOW_REGISTRATION: true
- UNSAFE_DISABLE_PASSWORD_PROJECTION: "yes_i_am_sure"
-tasks:
- setup:
- desc: Install development dependencies
- cmds:
- - go install github.com/swaggo/swag/cmd/swag@latest
- - cd backend && go mod tidy
- - cd frontend && pnpm install --shamefully-hoist
-
- swag:
- desc: Generate swagger docs
- dir: backend/app/api/static/
- vars:
- API: "../"
- INTERNAL: "../../../internal"
- PKGS: "../../../pkgs"
- cmds:
- - swag fmt --dir={{ .API }}
- - swag init --dir={{ .API }},{{ .INTERNAL }}/core/services,{{ .INTERNAL }}/data/repo --parseDependency
- sources:
- - "./backend/app/api/**/*"
- - "./backend/internal/data/**"
- - "./backend/internal/core/services/**/*"
- - "./backend/app/tools/typegen/main.go"
-
- typescript-types:
- desc: Generates typescript types from swagger definition
- cmds:
- - |
- npx swagger-typescript-api \
- --no-client \
- --modular \
- --path ./backend/app/api/static/docs/swagger.json \
- --output ./frontend/lib/api/types
- - go run ./backend/app/tools/typegen/main.go ./frontend/lib/api/types/data-contracts.ts
- sources:
- - ./backend/app/tools/typegen/main.go
- - ./backend/app/api/static/docs/swagger.json
-
- generate:
- deps:
- - db:generate
- cmds:
- - task: swag
- - task: typescript-types
- - cp ./backend/app/api/static/docs/swagger.json docs/docs/api/openapi-2.0.json
-
- go:run:
- desc: Starts the backend api server (depends on generate task)
- dir: backend
- deps:
- - generate
- cmds:
- - go run ./app/api/ {{ .CLI_ARGS }}
- silent: false
-
- go:test:
- desc: Runs all go tests using gotestsum - supports passing gotestsum args
- dir: backend
- cmds:
- - gotestsum {{ .CLI_ARGS }} ./...
-
- go:coverage:
- desc: Runs all go tests with -race flag and generates a coverage report
- dir: backend
- cmds:
- - go test -race -coverprofile=coverage.out -covermode=atomic ./app/... ./internal/... ./pkgs/... -v -cover
- silent: true
-
- go:tidy:
- desc: Runs go mod tidy on the backend
- dir: backend
- cmds:
- - go mod tidy
-
- go:lint:
- desc: Runs golangci-lint
- dir: backend
- cmds:
- - golangci-lint run ./...
-
- go:all:
- desc: Runs all go test and lint related tasks
- cmds:
- - task: go:tidy
- - task: go:lint
- - task: go:test
-
- go:build:
- desc: Builds the backend binary
- dir: backend
- cmds:
- - go build -o ../build/backend ./app/api
-
- db:generate:
- desc: Run Entgo.io Code Generation
- dir: backend/internal/
- cmds:
- - |
- go generate ./...
- sources:
- - "./backend/internal/data/ent/schema/**/*"
-
- db:migration:
- desc: Runs the database diff engine to generate a SQL migration files
- deps:
- - db:generate
- cmds:
- - cd backend && go run app/tools/migrations/main.go {{ .CLI_ARGS }}
-
- ui:watch:
- desc: Starts the vitest test runner in watch mode
- dir: frontend
- cmds:
- - pnpm run test:watch
-
- ui:dev:
- desc: Run frontend development server
- dir: frontend
- cmds:
- - pnpm dev
-
- ui:fix:
- desc: Runs prettier and eslint on the frontend
- dir: frontend
- cmds:
- - pnpm run lint:fix
-
- ui:check:
- desc: Runs type checking
- dir: frontend
- cmds:
- - pnpm run typecheck
-
- test:ci:
- desc: Runs end-to-end test on a live server (only for use in CI)
- cmds:
- - cd backend && go build ./app/api
- - backend/api &
- - sleep 5
- - cd frontend && pnpm run test:ci
- silent: true
-
- pr:
- desc: Runs all tasks required for a PR
- cmds:
- - task: generate
- - task: go:all
- - task: ui:check
- - task: ui:fix
- - task: test:ci
diff --git a/docs/docs/api/openapi-2.0.json b/api/openapi-2.0.json
similarity index 95%
rename from docs/docs/api/openapi-2.0.json
rename to api/openapi-2.0.json
index b10c93a..837c889 100644
--- a/docs/docs/api/openapi-2.0.json
+++ b/api/openapi-2.0.json
@@ -143,25 +143,6 @@
}
}
},
- "/v1/currency": {
- "get": {
- "produces": [
- "application/json"
- ],
- "tags": [
- "Base"
- ],
- "summary": "Currency",
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "$ref": "#/definitions/currencies.Currency"
- }
- }
- }
- }
- },
"/v1/groups": {
"get": {
"security": [
@@ -422,16 +403,6 @@
"description": "location Ids",
"name": "locations",
"in": "query"
- },
- {
- "type": "array",
- "items": {
- "type": "string"
- },
- "collectionFormat": "multi",
- "description": "parent Ids",
- "name": "parentIds",
- "in": "query"
}
],
"responses": {
@@ -1010,42 +981,6 @@
}
}
},
- "/v1/items/{id}/path": {
- "get": {
- "security": [
- {
- "Bearer": []
- }
- ],
- "produces": [
- "application/json"
- ],
- "tags": [
- "Items"
- ],
- "summary": "Get the full path of an item",
- "parameters": [
- {
- "type": "string",
- "description": "Item ID",
- "name": "id",
- "in": "path",
- "required": true
- }
- ],
- "responses": {
- "200": {
- "description": "OK",
- "schema": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/repo.ItemPath"
- }
- }
- }
- }
- }
- },
"/v1/labels": {
"get": {
"security": [
@@ -1632,7 +1567,7 @@
"200": {
"description": "OK",
"schema": {
- "$ref": "#/definitions/v1.APISummary"
+ "$ref": "#/definitions/v1.ApiSummary"
}
}
}
@@ -1703,12 +1638,6 @@
"schema": {
"$ref": "#/definitions/v1.LoginForm"
}
- },
- {
- "type": "string",
- "description": "auth provider",
- "name": "provider",
- "in": "query"
}
],
"responses": {
@@ -1887,23 +1816,6 @@
}
},
"definitions": {
- "currencies.Currency": {
- "type": "object",
- "properties": {
- "code": {
- "type": "string"
- },
- "local": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "symbol": {
- "type": "string"
- }
- }
- },
"repo.DocumentOut": {
"type": "object",
"properties": {
@@ -2079,6 +1991,12 @@
"$ref": "#/definitions/repo.ItemAttachment"
}
},
+ "children": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/repo.ItemSummary"
+ }
+ },
"createdAt": {
"type": "string"
},
@@ -2112,13 +2030,9 @@
},
"location": {
"description": "Edges",
- "allOf": [
- {
- "$ref": "#/definitions/repo.LocationSummary"
- }
- ],
"x-nullable": true,
- "x-omitempty": true
+ "x-omitempty": true,
+ "$ref": "#/definitions/repo.LocationSummary"
},
"manufacturer": {
"type": "string"
@@ -2134,13 +2048,9 @@
"type": "string"
},
"parent": {
- "allOf": [
- {
- "$ref": "#/definitions/repo.ItemSummary"
- }
- ],
"x-nullable": true,
- "x-omitempty": true
+ "x-omitempty": true,
+ "$ref": "#/definitions/repo.ItemSummary"
},
"purchaseFrom": {
"type": "string"
@@ -2197,20 +2107,6 @@
}
}
},
- "repo.ItemPath": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "$ref": "#/definitions/repo.ItemType"
- }
- }
- },
"repo.ItemSummary": {
"type": "object",
"properties": {
@@ -2240,13 +2136,9 @@
},
"location": {
"description": "Edges",
- "allOf": [
- {
- "$ref": "#/definitions/repo.LocationSummary"
- }
- ],
"x-nullable": true,
- "x-omitempty": true
+ "x-omitempty": true,
+ "$ref": "#/definitions/repo.LocationSummary"
},
"name": {
"type": "string"
@@ -2263,17 +2155,6 @@
}
}
},
- "repo.ItemType": {
- "type": "string",
- "enum": [
- "location",
- "item"
- ],
- "x-enum-varnames": [
- "ItemTypeLocation",
- "ItemTypeItem"
- ]
- },
"repo.ItemUpdate": {
"type": "object",
"properties": {
@@ -2366,6 +2247,7 @@
"type": "string"
},
"warrantyExpires": {
+ "description": "Sold",
"type": "string"
}
}
@@ -2539,6 +2421,7 @@
"type": "object",
"properties": {
"completedDate": {
+ "description": "Sold",
"type": "string"
},
"cost": {
@@ -2555,6 +2438,7 @@
"type": "string"
},
"scheduledDate": {
+ "description": "Sold",
"type": "string"
}
}
@@ -2566,6 +2450,7 @@
],
"properties": {
"completedDate": {
+ "description": "Sold",
"type": "string"
},
"cost": {
@@ -2579,6 +2464,7 @@
"type": "string"
},
"scheduledDate": {
+ "description": "Sold",
"type": "string"
}
}
@@ -2587,6 +2473,7 @@
"type": "object",
"properties": {
"completedDate": {
+ "description": "Sold",
"type": "string"
},
"cost": {
@@ -2600,6 +2487,7 @@
"type": "string"
},
"scheduledDate": {
+ "description": "Sold",
"type": "string"
}
}
@@ -2835,7 +2723,15 @@
}
}
},
- "v1.APISummary": {
+ "v1.ActionAmountResult": {
+ "type": "object",
+ "properties": {
+ "completed": {
+ "type": "integer"
+ }
+ }
+ },
+ "v1.ApiSummary": {
"type": "object",
"properties": {
"allowRegistration": {
@@ -2864,14 +2760,6 @@
}
}
},
- "v1.ActionAmountResult": {
- "type": "object",
- "properties": {
- "completed": {
- "type": "integer"
- }
- }
- },
"v1.Build": {
"type": "object",
"properties": {
diff --git a/assets/images/favicon.png b/assets/images/favicon.png
new file mode 100644
index 0000000..1cf13b9
Binary files /dev/null and b/assets/images/favicon.png differ
diff --git a/docs/docs/assets/img/favicon.svg b/assets/img/favicon.svg
similarity index 100%
rename from docs/docs/assets/img/favicon.svg
rename to assets/img/favicon.svg
diff --git a/docs/docs/assets/img/lilbox.svg b/assets/img/lilbox.svg
similarity index 100%
rename from docs/docs/assets/img/lilbox.svg
rename to assets/img/lilbox.svg
diff --git a/assets/javascripts/bundle.51d95adb.min.js b/assets/javascripts/bundle.51d95adb.min.js
new file mode 100644
index 0000000..b20ec68
--- /dev/null
+++ b/assets/javascripts/bundle.51d95adb.min.js
@@ -0,0 +1,29 @@
+"use strict";(()=>{var Hi=Object.create;var xr=Object.defineProperty;var Pi=Object.getOwnPropertyDescriptor;var $i=Object.getOwnPropertyNames,kt=Object.getOwnPropertySymbols,Ii=Object.getPrototypeOf,Er=Object.prototype.hasOwnProperty,an=Object.prototype.propertyIsEnumerable;var on=(e,t,r)=>t in e?xr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))Er.call(t,r)&&on(e,r,t[r]);if(kt)for(var r of kt(t))an.call(t,r)&&on(e,r,t[r]);return e};var sn=(e,t)=>{var r={};for(var n in e)Er.call(e,n)&&t.indexOf(n)<0&&(r[n]=e[n]);if(e!=null&&kt)for(var n of kt(e))t.indexOf(n)<0&&an.call(e,n)&&(r[n]=e[n]);return r};var Ht=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Fi=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of $i(t))!Er.call(e,o)&&o!==r&&xr(e,o,{get:()=>t[o],enumerable:!(n=Pi(t,o))||n.enumerable});return e};var yt=(e,t,r)=>(r=e!=null?Hi(Ii(e)):{},Fi(t||!e||!e.__esModule?xr(r,"default",{value:e,enumerable:!0}):r,e));var fn=Ht((wr,cn)=>{(function(e,t){typeof wr=="object"&&typeof cn!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(wr,function(){"use strict";function e(r){var n=!0,o=!1,i=null,a={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function s(T){return!!(T&&T!==document&&T.nodeName!=="HTML"&&T.nodeName!=="BODY"&&"classList"in T&&"contains"in T.classList)}function f(T){var Ke=T.type,We=T.tagName;return!!(We==="INPUT"&&a[Ke]&&!T.readOnly||We==="TEXTAREA"&&!T.readOnly||T.isContentEditable)}function c(T){T.classList.contains("focus-visible")||(T.classList.add("focus-visible"),T.setAttribute("data-focus-visible-added",""))}function u(T){T.hasAttribute("data-focus-visible-added")&&(T.classList.remove("focus-visible"),T.removeAttribute("data-focus-visible-added"))}function p(T){T.metaKey||T.altKey||T.ctrlKey||(s(r.activeElement)&&c(r.activeElement),n=!0)}function m(T){n=!1}function d(T){s(T.target)&&(n||f(T.target))&&c(T.target)}function h(T){s(T.target)&&(T.target.classList.contains("focus-visible")||T.target.hasAttribute("data-focus-visible-added"))&&(o=!0,window.clearTimeout(i),i=window.setTimeout(function(){o=!1},100),u(T.target))}function v(T){document.visibilityState==="hidden"&&(o&&(n=!0),B())}function B(){document.addEventListener("mousemove",z),document.addEventListener("mousedown",z),document.addEventListener("mouseup",z),document.addEventListener("pointermove",z),document.addEventListener("pointerdown",z),document.addEventListener("pointerup",z),document.addEventListener("touchmove",z),document.addEventListener("touchstart",z),document.addEventListener("touchend",z)}function re(){document.removeEventListener("mousemove",z),document.removeEventListener("mousedown",z),document.removeEventListener("mouseup",z),document.removeEventListener("pointermove",z),document.removeEventListener("pointerdown",z),document.removeEventListener("pointerup",z),document.removeEventListener("touchmove",z),document.removeEventListener("touchstart",z),document.removeEventListener("touchend",z)}function z(T){T.target.nodeName&&T.target.nodeName.toLowerCase()==="html"||(n=!1,re())}document.addEventListener("keydown",p,!0),document.addEventListener("mousedown",m,!0),document.addEventListener("pointerdown",m,!0),document.addEventListener("touchstart",m,!0),document.addEventListener("visibilitychange",v,!0),B(),r.addEventListener("focus",d,!0),r.addEventListener("blur",h,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var un=Ht(Sr=>{(function(e){var t=function(){try{return!!Symbol.iterator}catch(c){return!1}},r=t(),n=function(c){var u={next:function(){var p=c.shift();return{done:p===void 0,value:p}}};return r&&(u[Symbol.iterator]=function(){return u}),u},o=function(c){return encodeURIComponent(c).replace(/%20/g,"+")},i=function(c){return decodeURIComponent(String(c).replace(/\+/g," "))},a=function(){var c=function(p){Object.defineProperty(this,"_entries",{writable:!0,value:{}});var m=typeof p;if(m!=="undefined")if(m==="string")p!==""&&this._fromString(p);else if(p instanceof c){var d=this;p.forEach(function(re,z){d.append(z,re)})}else if(p!==null&&m==="object")if(Object.prototype.toString.call(p)==="[object Array]")for(var h=0;hThis document describes how to build the project from source code.
+TODO
+TODO
+TODO
+ + + + + + +
- - Docs - | - Demo - | - Discord -
- - - -Homebox is the inventory and organization system built for the Home User! With a focus on simplicity and ease of use, Homebox is the perfect solution for your home inventory, organization, and management needs. While developing this project, I've tried to keep the following principles in mind: - -- _Simple_ - Homebox is designed to be simple and easy to use. No complicated setup or configuration required. Use either a single docker container, or deploy yourself by compiling the binary for your platform of choice. -- _Blazingly Fast_ - Homebox is written in Go, which makes it extremely fast and requires minimal resources to deploy. In general idle memory usage is less than 50MB for the whole container. -- _Portable_ - Homebox is designed to be portable and run on anywhere. We use SQLite and an embedded Web UI to make it easy to deploy, use, and backup. - -## Project Status - -Homebox is currently in early active development and is currently in **beta** stage. This means that the project may still be unstable and clunky. Overall, we are striving to not introduce any breaking changes and have checks in place to ensure migrations and upgrades are smooth. However, we do not guarantee that there will be no breaking changes. We will try to keep the documentation up to date as we make changes. - -## Features - -- Create and Manage _Items_ by providing a name and a description - That's it! Homebox requires only a few details to be provided to create an item, after that you can specify as much detail as you want, or hide away some of the things you won't ever need. -- Optional Details for Items include - - Warranty Information - - Sold To Information - - Purchased From Information - - Item Identifications (Serial, Model, etc) - - Categorized Attachments (Images, Manuals, General) - - Arbitrary/Custom Fields -- CSV Import/Export for quickly creating and managing items -- Custom Reporting - - Bill of Materials Export - - QR Code Label Generator -- Organize _Items_ by creating _Labels_ and _Locations_ and assigning them to items. -- Multi-Tenant Support - All users are placed in a group and can only see items in their group. Invite family members to your group, or share an instance among friends! - - -## Why Not Use Something Else? - -There are a lot of great inventory management systems out there, but none of them _really_ fit my needs as a home user. Snipe-IT is a fantastic product that has so many robust features and management options which makes it easy to become overwhelmed and confused. I wanted something that was simple and easy to use that didn't require a lot of cognitive overhead to manage. I primarily built this to organize my IOT devices and save my warranty and documentation information in a central, searchable location. - -### Spreadsheet - -That's a fair point. If your needs can be fulfilled by a Spreadsheet, I'd suggest using that instead. I've found spreadsheets get pretty unwieldy when you have a lot of data, and it's hard to keep track of what's where. I also wanted to be able to search and filter my data in a more robust way than a spreadsheet can provide. I also wanted to leave the door open for more advanced features in the future like maintenance logs, moving label generators, and more. - -### Snipe-It? - -Snipe-It is the gold standard for IT management. If your use-case is to manage consumables and IT physical infrastructure, I highly suggest you look at Snipe-It over Homebox, it's just more purpose built for that use case. Homebox is, in contrast, purpose built for the home user, which means that we try to focus on keeping things simple and easy to use. Lowering the friction for creating items and managing them is a key goal of Homebox which means you lose out on some of the more advanced features. In most cases, this is a good trade-off. \ No newline at end of file diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md deleted file mode 100644 index 278b442..0000000 --- a/docs/docs/quick-start.md +++ /dev/null @@ -1,109 +0,0 @@ -# Quick Start - -## Docker Run - -Great for testing out the application, but not recommended for stable use. Checkout the docker-compose for the recommended deployment. - -For each image there are two tags, respectively the regular tag and $TAG-rootless, which uses a non-root image. - -```sh -# If using the rootless image, ensure data -# folder has correct permissions -$ mkdir -p /path/to/data/folder -$ chown 65532:65532 -R /path/to/data/folder -# --------------------------------------- -# Run the image -$ docker run -d \ - --name homebox \ - --restart unless-stopped \ - --publish 3100:7745 \ - --env TZ=Europe/Bucharest \ - --volume /path/to/data/folder/:/data \ - ghcr.io/hay-kot/homebox:latest -# ghcr.io/hay-kot/homebox:latest-rootless - -``` - -## Docker-Compose - -```yaml -services: - homebox: - image: ghcr.io/hay-kot/homebox:latest -# image: ghcr.io/hay-kot/homebox:latest-rootless - container_name: homebox - restart: always - environment: - - HBOX_LOG_LEVEL=info - - HBOX_LOG_FORMAT=text - - HBOX_WEB_MAX_UPLOAD_SIZE=10 - volumes: - - homebox-data:/data/ - ports: - - 3100:7745 - -volumes: - homebox-data: - driver: local -``` - -!!! note - If you use the `rootless` image, and instead of using named volumes you would prefer using a hostMount directly (e.g., `volumes: [ /path/to/data/folder:/data ]`) you need to `chown` the chosen directory in advance to the `65532` user (as shown in the Docker example above). - -## Env Variables & Configuration - -| Variable | Default | Description | -| ------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------- | -| HBOX_MODE | production | application mode used for runtime behavior can be one of: development, production | -| HBOX_WEB_PORT | 7745 | port to run the web server on, if you're using docker do not change this | -| HBOX_WEB_HOST | | host to run the web server on, if you're using docker do not change this | -| HBOX_OPTIONS_ALLOW_REGISTRATION | true | allow users to register themselves | -| HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID | true | auto increments the asset_id field for new items | -| HBOX_OPTIONS_CURRENCY_CONFIG | | json configuration file containing additional currencie | -| HBOX_WEB_MAX_UPLOAD_SIZE | 10 | maximum file upload size supported in MB | -| HBOX_WEB_READ_TIMEOUT | 10 | Read timeout of HTTP sever | -| HBOX_WEB_WRITE_TIMEOUT | 10 | Write timeout of HTTP server | -| HBOX_WEB_IDLE_TIMEOUT | 30 | Idle timeout of HTTP server | -| HBOX_STORAGE_DATA | /data/ | path to the data directory, do not change this if you're using docker | -| HBOX_STORAGE_SQLITE_URL | /data/homebox.db?_fk=1 | sqlite database url, if you're using docker do not change this | -| HBOX_LOG_LEVEL | info | log level to use, can be one of: trace, debug, info, warn, error, critical | -| HBOX_LOG_FORMAT | text | log format to use, can be one of: text, json | -| HBOX_MAILER_HOST | | email host to use, if not set no email provider will be used | -| HBOX_MAILER_PORT | 587 | email port to use | -| HBOX_MAILER_USERNAME | | email user to use | -| HBOX_MAILER_PASSWORD | | email password to use | -| HBOX_MAILER_FROM | | email from address to use | -| HBOX_SWAGGER_HOST | 7745 | swagger host to use, if not set swagger will be disabled | -| HBOX_SWAGGER_SCHEMA | http | swagger schema to use, can be one of: http, https | - -!!! tip "CLI Arguments" - If you're deploying without docker you can use command line arguments to configure the application. Run `homebox --help` for more information. - - ```sh - Usage: api [options] [arguments] - - OPTIONS - --mode/$HBOX_MODE- Import a CSV file containing your items, labels, and locations. See documentation for more information on the - required format. -
-
-
-
-
- use Shift + Enter to create and add another -
-|
-
- {{ h }}
- {{ h.text }}
-
-
-
-
- |
-
|---|
|
-
- |
-
- use Shift + Enter to create and add another -
-- use Shift + Enter to create and add another -
-{{ text }}
-Password Strength: {{ message }}
- -| - {{ h }} - {{ h.text }} - | -
|---|
|
- |
-
Welcome, {{ username }}
-No attachments found
-- Primary Photo - This options is only available for photos. Only one photo can be primary. If you select this option, the - current primary photo, if any will be unselected. -
-Changes to attachments will be saved immediately
-- {{ attachment.document.title }} -
-- {{ capitalize(attachment.type) }} -
-Querying Asset ID Number: {{ parsedAssetId }}
-Search Tips
-Custom Fields
-- {{ total }} Results - Page {{ page }} of {{ totalPages }} -
- -Page {{ page }} of {{ totalPages }}
-{{ n.name }}
-- Active - Inactive -
-
- Created
-
Example: {{ currencyExample }}
- -- The Homebox Label Generator is a tool to help you print labels for your Homebox inventory. These are intended to - be print-ahead labels so you can print many labels and have them ready to apply -
-- As such, these labels work by printing a URL QR Code and AssetID information on a label. If you've disabled - AssetID's in your Homebox settings, you can still use this tool, but the AssetID's won't reference any item -
-- This feature is in early development stages and may change in future releases, if you have feedback please - provide it in the GitHub Discussion -
-QR Code Example {{ displayProperties.baseURL }}/a/{asset_id}
-Using the CSV import is the recommended way for adding items to the database. It is always going to be the fastest way to import any large amount of items and provides the most flexibility when it comes to adding items.
+Current Limitations
+Home / Office / Desk) and will only export the Items direct parent, (though imports do support nested paths)Item A is a child of Item B)File Formats
+The CSV import supports both CSV and TSV files. The only difference is the delimiter used. CSV files use a comma , as the delimiter and TSV files use a tab \t as the delimiter. The file extension does not matter.
Below are the supported columns. They are case sensitive, can be in any ordered or can be omitted unless otherwise specified.
+HB.import_refImport Refs are unique strings that can be used to deduplicate imports. Before an item is imported, we check the database for a matching ref. If the ref exists, we skip creation of that item.
+Import Refs are used to de-duplicate imports. It is HIGHLY recommended that you use them to manage your items if you intend to manage your inventory via CSV import/export. If you do not use import refs, you will end up with duplicate items in your database on subsequent imports.
+Tip
+Specifying import refs also allows you to update existing items via the CSV import. If you specify an import ref that already exists in the database, we will update the existing item instead of creating a new one.
+HB.locationThis is the location of the item that will be created. These are de-duplicated and won't create another instance when reused.
+Home / Office / Desk)HB.labelsList of labels to apply to the item separated by a ; can be existing or new labels.
HB.field.{field_name} (e.g. HB.field.Serial Number)This is a special column that allows you to add custom fields to the item. The column name must start with HB.field. followed by the name of the field. The value of the column will be the value of the field.
| Column | +Type | +Description | +
|---|---|---|
| HB.quantity | +Integer | +The quantity of items to create | +
| HB.name | +String | +Name of the item | +
| HB.asset_id | +AssetID | +Asset ID for the item | +
| HB.description | +String | +Description of the item | +
| HB.insured | +Boolean | +Whether or not the item is insured | +
| HB.serial_number | +String | +Serial number of the item | +
| HB.model_number | +String | +Model of the item | +
| HB.manufacturer | +String | +Manufacturer of the item | +
| HB.notes | +String (1000) | +General notes about the product | +
| HB.purchase_from | +String | +Name of the place the item was purchased from | +
| HB.purchase_price | +Float64 | ++ |
| HB.purchase_time | +Date | +Date the item was purchased | +
| HB.lifetime_warranty | +Boolean | +true or false - case insensitive | +
| HB.warranty_expires | +Date | +Date in the format | +
| HB.warranty_details | +String | +Details about the warranty | +
| HB.sold_to | +String | +Name of the person the item was sold to | +
| HB.sold_time | +Date | +Date the item was sold | +
| HB.sold_price | +Float64 | ++ |
| HB.sold_notes | +String (1000) | ++ |
Type Key
+| Type | +Format | +
|---|---|
| String | +Max 255 Characters unless otherwise specified | +
| Date | +YYYY-MM-DD | +
| Boolean | +true or false, yes or no, 1 or 0 - case insensitive | +
| AssetID | +000-000 | +
+ + Docs + | + Demo + | + Discord +
+ +Homebox is the inventory and organization system built for the Home User! With a focus on simplicity and ease of use, Homebox is the perfect solution for your home inventory, organization, and management needs. While developing this project I've tried to keep the following principles in mind:
+Homebox is currently in early-active development and is currently in beta stage. This means that the project may still be unstable and clunky. Overall we are striving to not introduce any breaking changes and have checks in place to ensure migrations and upgrades are smooth. However, we do not guarantee that there will be no breaking changes. We will try to keep the documentation up to date as we make changes.
+There are a lot of great inventory management systems out there, but none of them really fit my needs as a home user. Snipe-IT is a fantastic product that has so many robust features and management options that it's easy to become overwhelmed and confused. I wanted something that was simple and easy to use that didn't require a lot of cognitive overhead to manage. I primarily built this to organize my IOT devices and save my warranty and documentation information in a central, searchable location.
+That's a fair point. If your needs can be fulfilled by a Spreadsheet, I'd suggest using that instead. I've found spreadsheets get pretty unwieldy when you have a lot of data and it's hard to keep track of what's where. I also wanted to be able to search and filter my data in a more robust way than a spreadsheet can provide. I also wanted to leave to door open for more advanced features in the future like maintenance logs, moving label generators, and more.
+Snipe-It is the gold standard for IT management. If your use-case is to manage consumables and IT physical infrastructure I highly suggest you look at Snipe-It over Homebox, it's just more purpose built for that use case. Homebox is, in contrast, purpose built for the home user, which means that we try to focus on keeping things simple and easy to use. Lowering the friction for creating items and managing them is a key goal of Homebox which means you lose out on some of the more advanced features. In most cases this is a good trade-off.
+ + + + + + +Great for testing out the application, but not recommended for stable use. Checkout the docker-compose for the recommended deployment.
+For each image there are two tags, respectively the regular tag and $TAG-rootless, which uses a non-root image.
+# If using the rootless image, ensure data
+# folder has correct permissions
+$ mkdir -p /path/to/data/folder
+$ chown 65532:65532 -R /path/to/data/folder
+# ---------------------------------------
+# Run the image
+$ docker run -d \
+ --name homebox \
+ --restart unless-stopped \
+ --publish 3100:7745 \
+ --env TZ=Europe/Bucharest \
+ --volume /path/to/data/folder/:/data \
+ ghcr.io/hay-kot/homebox:latest
+# ghcr.io/hay-kot/homebox:latest-rootless
+version: "3.4"
+
+services:
+ homebox:
+ image: ghcr.io/hay-kot/homebox:latest
+# image: ghcr.io/hay-kot/homebox:latest-rootless
+ container_name: homebox
+ restart: always
+ environment:
+ - HBOX_LOG_LEVEL=info
+ - HBOX_LOG_FORMAT=text
+ - HBOX_WEB_MAX_UPLOAD_SIZE=10
+ volumes:
+ - homebox-data:/data/
+ ports:
+ - 3100:7745
+
+volumes:
+ homebox-data:
+ driver: local
+Note
+If you use the rootless image, and instead of using named volumes you would prefer using a hostMount directly (e.g., volumes: [ /path/to/data/folder:/data ]) you need to chown the chosen directory in advance to the 65532 user (as shown in the Docker example above).
| Variable | +Default | +Description | +
|---|---|---|
| HBOX_MODE | +production | +application mode used for runtime behavior can be one of: development, production | +
| HBOX_WEB_PORT | +7745 | +port to run the web server on, if you're using docker do not change this | +
| HBOX_WEB_HOST | ++ | host to run the web server on, if you're using docker do not change this | +
| HBOX_OPTIONS_ALLOW_REGISTRATION | +true | +allow users to register themselves | +
| HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID | +true | +auto increments the asset_id field for new items | +
| HBOX_WEB_MAX_UPLOAD_SIZE | +10 | +maximum file upload size supported in MB | +
| HBOX_STORAGE_DATA | +/data/ | +path to the data directory, do not change this if you're using docker | +
| HBOX_STORAGE_SQLITE_URL | +/data/homebox.db?_fk=1 | +sqlite database url, if you're using docker do not change this | +
| HBOX_LOG_LEVEL | +info | +log level to use, can be one of: trace, debug, info, warn, error, critical | +
| HBOX_LOG_FORMAT | +text | +log format to use, can be one of: text, json | +
| HBOX_MAILER_HOST | ++ | email host to use, if not set no email provider will be used | +
| HBOX_MAILER_PORT | +587 | +email port to use | +
| HBOX_MAILER_USERNAME | ++ | email user to use | +
| HBOX_MAILER_PASSWORD | ++ | email password to use | +
| HBOX_MAILER_FROM | ++ | email from address to use | +
| HBOX_SWAGGER_HOST | +7745 | +swagger host to use, if not set swagger will be disabled | +
| HBOX_SWAGGER_SCHEMA | +http | +swagger schema to use, can be one of: http, https | +
CLI Arguments
+If you're deploying without docker you can use command line arguments to configure the application. Run homebox --help for more information.
Usage: api [options] [arguments]
+
+OPTIONS
+ --mode/$HBOX_MODE <string> (default: development)
+ --web-port/$HBOX_WEB_PORT <string> (default: 7745)
+ --web-host/$HBOX_WEB_HOST <string>
+ --web-max-upload-size/$HBOX_WEB_MAX_UPLOAD_SIZE <int> (default: 10)
+ --storage-data/$HBOX_STORAGE_DATA <string> (default: ./.data)
+ --storage-sqlite-url/$HBOX_STORAGE_SQLITE_URL <string> (default: ./.data/homebox.db?_fk=1)
+ --log-level/$HBOX_LOG_LEVEL <string> (default: info)
+ --log-format/$HBOX_LOG_FORMAT <string> (default: text)
+ --mailer-host/$HBOX_MAILER_HOST <string>
+ --mailer-port/$HBOX_MAILER_PORT <int>
+ --mailer-username/$HBOX_MAILER_USERNAME <string>
+ --mailer-password/$HBOX_MAILER_PASSWORD <string>
+ --mailer-from/$HBOX_MAILER_FROM <string>
+ --swagger-host/$HBOX_SWAGGER_HOST <string> (default: localhost:7745)
+ --swagger-scheme/$HBOX_SWAGGER_SCHEME <string> (default: http)
+ --demo/$HBOX_DEMO <bool>
+ --debug-enabled/$HBOX_DEBUG_ENABLED <bool> (default: false)
+ --debug-port/$HBOX_DEBUG_PORT <string> (default: 4000)
+ --options-allow-registration/$HBOX_OPTIONS_ALLOW_REGISTRATION <bool> (default: true)
+ --options-auto-increment-asset-id/$HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID <bool> (default: true)
+ --help/-h
+ display this help message
+Custom fields are a great way to add any extra information to your item. The following types are supported:
+Custom fields are appended to the main details section of your item.
+Tip
+Homebox Custom Fields also have special support for URLs. Provide a URL (https://google.com) and it will be automatically converted to a clickable link in the UI. Optionally, you can also use markdown syntax to add a custom text to the button. [Google](https://google.com)
Homebox provides the option to auto-set asset IDs, this is the default behavior. These can be used for tracking assets with printable tags or labels. You can disable this behavior via a command line flag or ENV variable. See configuration for more details.
+Example ID: 000-001
Asset IDs are partially managed by Homebox, but have a flexible implementation to allow for unique use cases. ID's are non-unique at the database level so there is nothing stopping a user from manually setting duplicate IDs for various items. There are two recommended approaches to manage Asset IDs
+This is the default behavior and likely to one to experience the most consistent behavior. Whenever creating or importing an item, that items receives the next available ID. This is the most consistent approach and is recommended for most users.
+In some cases you may want to skip some items such as consumables, or items that are loosely tracked. In this case, we recommend that you leave auto-incrementing ID's enabled however when you create a new item that you want to skip, you can go to that item and reset the ID to 0. This will remove it from the auto-incrementing sequence and the next item will receive the next available ID.
+Tip
+If you're migrating from an older version there is a action on the users profile page to assign IDs to all items. This will assign the next available ID to all items in the order of creation. You should only do this once during the migration process. You should be especially cautious of this action if you're using the reset feature described in option number 2
+0.7.0
+Homebox has a built-in QR code generator that can be used to generate QR codes for your items. This is useful for tracking items with a mobile device. You can generate a QR code for any item by clicking the QR code icon in the top right of the item details page. The same can be done for the Labels and Locations page. Currently support is limited to generating one off QR Codes.
+However, the API endpoint is available for generating QR codes on the fly for any item (or any other data) if you provide a valid API key in the query parameters. An example url would look like /api/v1/qrcode?data=https://homebox.fly.dev/item/{uuid}. Currently the easiest way to get an API token is to use one from an existing URL of the QR Code in the API key, but this will be improved in the future.
v0.8.0
+In version 0.8.0 We've added a custom label generation. On the tools page, there is now a link to the label-generator page where you can generate labels based on Asset ID for your inventory. These are still in early development, so please provide feedback. There's also more information on the implementation on the label generator page.
+ +v0.9.0
+Homebox uses shoutrrr to send notifications. This allows you to send notifications to a variety of services. On your profile page, you can add notification URLs to your profile which will be used to send notifications when a maintenance event is scheduled.
+Notifications are sent on the day the maintenance is scheduled at or around 8am.
+As of v0.9.0 we have limited support for complex scheduling of maintenance events. If you have requests for extended functionality, please open an issue on GitHub or reach out on Discord. We're still gauging the demand for this feature.