Skip to content

A continuation of HomeBox the inventory and organization system built for the Home User

docs: add installation page

Gabrinator8ef1b8b6ceaf
diff --git a/docs/en/installation.md b/docs/en/installation.md
new file mode 100644
index 00000000..29239197
--- /dev/null
+++ b/docs/en/installation.md
@@ -0,0 +1,99 @@
+# Installation
+
+There are two main ways to run the application.
+
+1. As a [Docker](https://www.docker.com/) container.
+2. Using the correct executable for your platform by downloading it from the [Releases](https://github.com/sysadminsmedia/homebox/releases).
+
+
+## Docker
+
+The following instructions assume Docker is already installed on your system. See [(Docker's official installation guide)](https://docs.docker.com/engine/install/)
+
+The official image is `ghcr.io/sysadminsmedia/homebox:latest`. For each image there are two tags, respectively the regular tag and $TAG-rootless, which uses a non-root image.
+
+### Docker Run
+
+Great for testing out the application, but not recommended for stable use. Checkout the docker-compose below for the recommended deployment.
+
+
+```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/sysadminsmedia/homebox:latest
+# ghcr.io/sysadminsmedia/homebox:latest-rootless
+```
+
+### Docker Compose
+
+1. Create a `docker-compose.yml` file.
+
+```yaml
+services:
+ homebox:
+ image: ghcr.io/sysadminsmedia/homebox:latest
+# image: ghcr.io/sysadminsmedia/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
+```
+
+::: info
+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).
+:::
+
+::: warning
+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.
+:::
+
+2. While in the same folder as docker-compose.yml, start the container by running:
+
+```bash
+docker compose up --detach
+```
+
+3. Navigate to `http://server.local.ip.address:3100/` to access the web interface. (replace with the right IP address).
+
+You can learn more about Docker by [reading the official Docker documentation.](https://docs.docker.com/)
+
+## Windows
+
+1. Download the appropriate release for your CPU architecture from the [releases page on GitHub](https://github.com/sysadminsmedia/homebox/releases).
+2. Extract the archive.
+3. Run `homebox.exe`. This will start the server on port 7745.
+4. You can test it by accessing http://localhost:7745.
+
+## Linux
+
+1. Download the appropriate release for your CPU architecture from the [releases page on GitHub](https://github.com/sysadminsmedia/homebox/releases).
+2. Extract the archive.
+3. Run the `homebox` executable.
+4. The web interface will be accessible on port 7745 by default. Access the page by navigating to `http://server.local.ip.address:7745/` (replace with the right ip address)
+
+## macOS
+
+1. Download the appropriate release for your CPU architecture from the [releases page on GitHub](https://github.com/sysadminsmedia/homebox/releases). (Use `homebox_Darwin_x86_64.tar.gz` for Intel-based macs and `homebox_Darwin_arm64.tar.gz` for Apple Silicon)
+2. Extract the archive.
+3. Run the `homebox` executable.
+4. The web interface will be accessible on port 7745 by default. Access the page by navigating to `http://local.ip.address:7745/` (replace with the right ip address)
\ No newline at end of file