From 17af865356772933f753ad405140d62367ba27e3 Mon Sep 17 00:00:00 2001 From: Matt Kilgore Date: Wed, 9 Oct 2024 21:52:51 -0400 Subject: [PATCH] chore: add documentation of new feature --- docs/en/configure-homebox.md | 48 +++++++++++++++++++----------------- docs/en/installation.md | 6 +++++ 2 files changed, 31 insertions(+), 23 deletions(-) diff --git a/docs/en/configure-homebox.md b/docs/en/configure-homebox.md index 138193e8..8d112bc0 100644 --- a/docs/en/configure-homebox.md +++ b/docs/en/configure-homebox.md @@ -2,29 +2,31 @@ ## 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 | 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_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` | +| 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 | 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_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` | +| HBOX_ALLOW_ANALYTICS | `false` | Opt-In basic non-identifiable analytics to assist with optimizing Homebox. | + ::: 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. diff --git a/docs/en/installation.md b/docs/en/installation.md index 29239197..0e1a3fce 100644 --- a/docs/en/installation.md +++ b/docs/en/installation.md @@ -29,6 +29,7 @@ $ docker run -d \ --restart unless-stopped \ --publish 3100:7745 \ --env TZ=Europe/Bucharest \ + --env HBOX_ALLOW_ANALYTICS=false \ --volume /path/to/data/folder/:/data \ ghcr.io/sysadminsmedia/homebox:latest # ghcr.io/sysadminsmedia/homebox:latest-rootless @@ -49,6 +50,7 @@ services: - HBOX_LOG_LEVEL=info - HBOX_LOG_FORMAT=text - HBOX_WEB_MAX_UPLOAD_SIZE=10 + - HBOX_ALLOW_ANALYTICS=false volumes: - homebox-data:/data/ ports: @@ -67,6 +69,10 @@ If you use the `rootless` image, and instead of using named volumes you would pr If you have previously set up docker compose with the `HBOX_WEB_READ_TIMEOUT`, `HBOX_WEB_WRITE_TIMEOUT`, or `HBOX_IDLE_TIMEOUT` options, and you were previously using the hay-kot image, please note that you will have to add an `s` for seconds or `m` for minutes to the end of the integers. A dependency update removed the defaultation to seconds and it now requires an explicit duration time. ::: +::: info +Please consider setting the `HBOX_ALLOW_ANALYTICS` environment variable to `true` to help us improve Homebox. It's a strictly opt-in feature, and we do not collect any personal information or sensitive information. +::: + 2. While in the same folder as docker-compose.yml, start the container by running: ```bash