diff --git a/docs/.vitepress/menus/en.mts b/docs/.vitepress/menus/en.mts
index ca1fb40a3..21d5855a6 100644
--- a/docs/.vitepress/menus/en.mts
+++ b/docs/.vitepress/menus/en.mts
@@ -20,7 +20,8 @@ export default [
{
text: 'Advanced',
items: [
- {text: 'Import CSV', link: '/en/import-csv'},
+ {text: 'Import CSV', link: '/en/advanced/import-csv'},
+ {text: 'External Label Service', link: '/en/advanced/external-label-service'},
]
},
{
diff --git a/docs/en/advanced/external-label-service.md b/docs/en/advanced/external-label-service.md
new file mode 100644
index 000000000..55bdd451e
--- /dev/null
+++ b/docs/en/advanced/external-label-service.md
@@ -0,0 +1,53 @@
+# External Label Service
+
+You can use an external web service to generate asset and location labels in homebox. This is useful if you have custom requirements for your labels and are happy to spin up a web service that can accept incoming requests and return an image file for homebox to use.
+
+::: info "Note"
+
+This service is not called to generate sheets of labels accessed via the label generator function. It is used when creating labels from an item or location.
+
+:::
+
+## Configuration
+
+The extenal service is configured using the `HBOX_LABEL_MAKER_LABEL_SERVICE_URL` enviroment variable.
+
+## Request
+
+The service is called using an **HTTP `GET` request**. All parameters are passed as part of the **query string**.
+
+#### Headers
+
+- **User-Agent**: Homebox-LabelMaker/1.0
+
+- **Accept**: image/*
+
+#### Parameters
+
+| Parameter | Type | Description | Value |
+| --------------------- | ------ | -------------------------------------------- | --------------------------------------------------------------------- |
+| AdditionalInformation | string | Extra free text to include on the label. | `HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION` |
+| ComponentPadding | int | Padding around label components (pixels). | `HBOX_LABEL_MAKER_PADDING` |
+| DescriptionFontSize | float | Font size for the description text. | |
+| DescriptionText | string | Descriptive text, can be multi-line. | Item name or "Homebox Location" |
+| Dpi | float | Rendering resolution (dots per inch). | |
+| DynamicLength | bool | Whether the label length should auto-adjust. | `HBOX_LABEL_MAKER_DYNAMIC_LENGTH` |
+| Height | int | Label height in pixels. | `HBOX_LABEL_MAKER_HEIGHT` |
+| Margin | int | Margin around the label in pixels. | `HBOX_LABEL_MAKER_MARGIN` |
+| QrSize | int | Size of the QR code element in pixels. | |
+| TitleFontSize | float | Font size for the title text. | |
+| TitleText | string | Main label title (e.g. product code). | Asset ID or Location Name |
+| URL | string | URL to be encoded into the QR code. | Generated based on the configured homebox URL and Asset / Location ID |
+| Width | int | Label width in pixels. | `HBOX_LABEL_MAKER_WIDTH` |
+
+## Response
+
+The external service should respond with the following specifications;
+
+- **Size:** Less than or equal to `HBOX_WEB_MAX_UPLOAD_SIZE` (Default: 10Mb)
+
+- **Content-Type**: Specified in the response header should be of the type image/*
+
+- **Time**: Within the time specified in `HBOX_LABEL_MAKER_LABEL_SERVICE_TIMEOUT` (Default 30s)
+
+
diff --git a/docs/en/import-csv.md b/docs/en/advanced/import-csv.md
similarity index 100%
rename from docs/en/import-csv.md
rename to docs/en/advanced/import-csv.md
diff --git a/docs/en/configure/index.md b/docs/en/configure/index.md
index f1878b09f..65e77af0d 100644
--- a/docs/en/configure/index.md
+++ b/docs/en/configure/index.md
@@ -7,55 +7,57 @@ aside: false
## 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. see below for examples |
-| 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_OPTIONS_ALLOW_ANALYTICS | false | Allows the homebox team to view extremely basic information about the system that your running on. This helps make decisions regarding builds and other general decisions. |
-| HBOX_WEB_MAX_UPLOAD_SIZE | 10 | maximum file upload size supported in MB |
-| HBOX_WEB_READ_TIMEOUT | 10s | Read timeout of HTTP sever |
-| HBOX_WEB_WRITE_TIMEOUT | 10s | Write timeout of HTTP server |
-| HBOX_WEB_IDLE_TIMEOUT | 30s | Idle timeout of HTTP server |
-| HBOX_STORAGE_CONN_STRING | file:///./ | path to the data directory, do not change this if you're using docker |
-| HBOX_STORAGE_PREFIX_PATH | .data | prefix path for the storage, if not set the storage will be used as is |
-| 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_DATABASE_DRIVER | sqlite3 | sets the correct database type (`sqlite3` or `postgres`) |
-| HBOX_DATABASE_SQLITE_PATH | ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite | sets the directory path for Sqlite |
-| HBOX_DATABASE_HOST | | sets the hostname for a postgres database |
-| HBOX_DATABASE_PORT | | sets the port for a postgres database |
-| HBOX_DATABASE_USERNAME | | sets the username for a postgres connection (optional if using cert auth) |
-| HBOX_DATABASE_PASSWORD | | sets the password for a postgres connection (optional if using cert auth) |
-| HBOX_DATABASE_DATABASE | | sets the database for a postgres connection |
-| HBOX_DATABASE_SSL_MODE | prefer | sets the sslmode for a postgres connection |
-| HBOX_DATABASE_SSL_CERT | | sets the sslcert for a postgres connection (should be a path) |
-| HBOX_DATABASE_SSL_KEY | | sets the sslkey for a postgres connection (should be a path) |
-| HBOX_DATABASE_SSL_ROOT_CERT | | sets the sslrootcert for a postgres connection (should be a path) |
-| HBOX_OPTIONS_GITHUB_RELEASE_CHECK | true | check for new github releases |
-| HBOX_LABEL_MAKER_WIDTH | 526 | width for generated labels in pixels |
-| HBOX_LABEL_MAKER_HEIGHT | 200 | height for generated labels in pixels |
-| HBOX_LABEL_MAKER_PADDING | 32 | space between elements on label |
-| HBOX_LABEL_MAKER_FONT_SIZE | 32.0 | font size for label text |
-| HBOX_LABEL_MAKER_PRINT_COMMAND | | the command to use for printing labels. if empty, label printing is disabled. `{{.FileName}}` in the command will be replaced with the png filename of the label |
-| HBOX_LABEL_MAKER_DYNAMIC_LENGTH | true | allow label generation with open length. `HBOX_LABEL_MAKER_HEIGHT` is still used for layout and minimal height. If not used, long text may be cut off, but all labels have the same size. |
-| HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION | | Additional information added to the label like name or phone number |
-| HBOX_THUMBNAIL_ENABLED | true | enable thumbnail generation for images, supports PNG, JPEG, AVIF, WEBP, GIF file types |
-| HBOX_THUMBNAIL_WIDTH | 500 | width for generated thumbnails in pixels |
-| HBOX_THUMBNAIL_HEIGHT | 500 | height for generated thumbnails in pixels |
+| Variable | Description | Default |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| HBOX_MODE | application mode used for runtime behavior can be one of: `development`, `production` | `production` |
+| HBOX_WEB_PORT | port to run the web server on, if you're using docker do not change this | 7745 |
+| HBOX_WEB_HOST | host to run the web server on, if you're using docker do not change this. see below for examples | |
+| HBOX_OPTIONS_ALLOW_REGISTRATION | allow users to register themselves | true |
+| HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID | auto-increments the asset_id field for new items | true |
+| HBOX_OPTIONS_CURRENCY_CONFIG | json configuration file containing additional currencie | |
+| HBOX_OPTIONS_ALLOW_ANALYTICS | Allows the homebox team to view extremely basic information about the system that your running on. This helps make decisions regarding builds and other general decisions. | false |
+| HBOX_WEB_MAX_UPLOAD_SIZE | maximum file upload size supported in MB | 10 |
+| HBOX_WEB_READ_TIMEOUT | Read timeout of HTTP sever | 10s |
+| HBOX_WEB_WRITE_TIMEOUT | Write timeout of HTTP server | 10s |
+| HBOX_WEB_IDLE_TIMEOUT | Idle timeout of HTTP server | 30s |
+| HBOX_STORAGE_CONN_STRING | path to the data directory, do not change this if you're using docker | file:///./ |
+| HBOX_STORAGE_PREFIX_PATH | prefix path for the storage, if not set the storage will be used as is | .data |
+| HBOX_LOG_LEVEL | log level to use, can be one of `trace`, `debug`, `info`, `warn`, `error`, `critical` | `info` |
+| HBOX_LOG_FORMAT | log format to use, can be one of: `text`, `json` | `text` |
+| HBOX_MAILER_HOST | email host to use, if not set no email provider will be used | |
+| HBOX_MAILER_PORT | email port to use | 587 |
+| HBOX_MAILER_USERNAME | email user to use | |
+| HBOX_MAILER_PASSWORD | email password to use | |
+| HBOX_MAILER_FROM | email from address to use | |
+| HBOX_DATABASE_DRIVER | sets the correct database type (`sqlite3` or `postgres`) | sqlite3 |
+| HBOX_DATABASE_SQLITE_PATH | sets the directory path for Sqlite | ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite |
+| HBOX_DATABASE_HOST | sets the hostname for a postgres database | |
+| HBOX_DATABASE_PORT | sets the port for a postgres database | |
+| HBOX_DATABASE_USERNAME | sets the username for a postgres connection (optional if using cert auth) | |
+| HBOX_DATABASE_PASSWORD | sets the password for a postgres connection (optional if using cert auth) | |
+| HBOX_DATABASE_DATABASE | sets the database for a postgres connection | |
+| HBOX_DATABASE_SSL_MODE | sets the sslmode for a postgres connection | prefer |
+| HBOX_DATABASE_SSL_CERT | sets the sslcert for a postgres connection (should be a path) | |
+| HBOX_DATABASE_SSL_KEY | sets the sslkey for a postgres connection (should be a path) | |
+| HBOX_DATABASE_SSL_ROOT_CERT | sets the sslrootcert for a postgres connection (should be a path) | |
+| HBOX_OPTIONS_GITHUB_RELEASE_CHECK | check for new github releases | true |
+| HBOX_LABEL_MAKER_WIDTH | width for generated labels in pixels | 526 |
+| HBOX_LABEL_MAKER_HEIGHT | height for generated labels in pixels | 200 |
+| HBOX_LABEL_MAKER_PADDING | space between elements on label | 32 |
+| HBOX_LABEL_MAKER_FONT_SIZE | font size for label text | 32.0 |
+| HBOX_LABEL_MAKER_PRINT_COMMAND | the command to use for printing labels. if empty, label printing is disabled. `{{.FileName}}` in the command will be replaced with the png filename of the label | |
+| HBOX_LABEL_MAKER_DYNAMIC_LENGTH | allow label generation with open length. `HBOX_LABEL_MAKER_HEIGHT` is still used for layout and minimal height. If not used, long text may be cut off, but all labels have the same size. | true |
+| HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION | Additional information added to the label like name or phone number | |
+| HBOX_LABEL_MAKER_LABEL_SERVICE_URL | URL to an external service to generate and return a label. Expected to return an image (e.g., PNG). See [External Label Service](/en/advanced/external-label-service) for more information | |
+| HBOX_LABEL_MAKER_LABEL_SERVICE_TIMEOUT | Number of seconds to wait for the label generation service to respond | 30s |
+| HBOX_THUMBNAIL_ENABLED | enable thumbnail generation for images, supports PNG, JPEG, AVIF, WEBP, GIF file types | true |
+| HBOX_THUMBNAIL_WIDTH | width for generated thumbnails in pixels | 500 |
+| HBOX_THUMBNAIL_HEIGHT | height for generated thumbnails in pixels | 500 |
### HBOX_WEB_HOST examples
| Value | Notes |
-|-----------------------------|------------------------------------------------------------|
+| --------------------------- | ---------------------------------------------------------- |
| 0.0.0.0 | Visible all interfaces (default behaviour) |
| 127.0.0.1 | Only visible on same host |
| 100.64.0.1 | Only visible on a specific interface (e.g., VPN in a VPS). |
@@ -89,6 +91,7 @@ the webserver (Caddy) can access it. Other processes/containers on the host
cannot connect to Homebox directly, bypassing the webserver.
File: homebox.socket
+
```systemd
# /usr/local/lib/systemd/system/homebox.socket
[Unit]
@@ -104,6 +107,7 @@ WantedBy=sockets.target
```
File: homebox.service
+
```systemd
# /usr/local/lib/systemd/system/homebox.service
[Unit]
@@ -124,6 +128,7 @@ CapabilityBoundingSet=
RestrictNamespaces=true
SystemCallFilter=@system-service
```
+
Usage:
```bash