From baf7ca18e2e930d10e80c38973e59c233f941ec7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafa=C5=82=20Ch=C5=82odnicki?= Date: Tue, 23 Nov 2021 16:54:52 +0100 Subject: [PATCH] docs: update how to use instructions (#795) --- README.md | 39 ++++++++++++++++++++++++--------------- docker/README.md | 14 +++++++++----- 2 files changed, 33 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d2f772ec..f4b00b70 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,6 @@ Should you have any ideas or questions please post them on the home-assistant fo * [Discussion on Home Assistant Community](https://community.home-assistant.io/t/new-dashboard-for-ha/57173) * [Demo Video](https://youtu.be/L8JwzWNAPr8) - -## :warning: Migrate from pre-1.0.0 version - -The project structure has changed in the first versioned (v1.0.0) release. Instead of checking out the repo, consider grabbing latest release from https://github.com/resoai/TileBoard/releases. For full setup instructions, see [How to use](#how-to-use) section. - - ## Screenshots ![screen](./images/screenshots/default.png) @@ -23,18 +17,33 @@ The project structure has changed in the first versioned (v1.0.0) release. Inste ## How to use -* Make sure that you have Home Assistant 0.77 or greater installed as only new authentication system is supported from now on -* Download the latest release zip file (`Tileboard.zip`) from https://github.com/resoai/TileBoard/releases and unpack to a directory of your choice -* In chosen directory rename `config.example.js` to `config.js` and adjust it for your needs -* Optionally create an empty `styles/custom.css` file. Everything will work without it but there will be a network request error logged in the console which can be annoying to some. -* Create a directory called `tileboard` inside `www` directory in HA's config path and copy all unpacked files there. -* TileBoard will be available at `http://HASS_IP:8123/local/tileboard/index.html` and will prompt you for your login credentials after restarting Home Assistant. +There are a couple of alternative ways of running TileBoard. The options are listed in the recommended order. First being the easiest and the most user friendly. + +### Run as a Home Assistant addon + +By far the easiest option that also provides auto-update through Home Assistant Supervisor. + +Installation instructions: refer to https://github.com/resoai/TileBoard-addon/blob/main/README.md#installation + +Check the instructions within the addon on how to edit and customize the configuration. + +### Run within a standalone server through Docker + +Runs a standalone local HTTP server, independently from the Home Assistant itself. + +Setup instructions: refer to https://github.com/resoai/TileBoard/blob/master/docker/README.md + +### Run within the public Home Assistant www directory -Alternatively you can checkout the repo and build the app manually. Check [CONTRIBUTING](./CONTRIBUTING.md) for more info. +1. Download the latest release zip file (`Tileboard.zip`) from https://github.com/resoai/TileBoard/releases and unpack to a directory of your choice. (Alternatively you can checkout the repo and build the app manually. Check [CONTRIBUTING](./CONTRIBUTING.md) for more info.) +2. In chosen directory rename `config.example.js` to `config.js` and adjust it for your needs +3. Optionally create an empty `styles/custom.css` file. Everything will work without it but there will be a network request error logged in the console which can be annoying to some. +4. Create a directory called `tileboard` inside `www` directory in HA's config path and copy all unpacked files there. +5. TileBoard will be available at `http://HASS_IP:8123/local/tileboard/index.html` and will prompt you for your login credentials after restarting Home Assistant. -## WARNING +#### !!!WARNING!!! -Files served from the www folder (/local/ url), aren’t protected by the Home Assistant authentication. Files stored in this folder, if the URL is known, can be accessed by anybody without authentication. Please make sure that your HA instance is not exposed via inetrnet or at least that long-lived token is not hardcoded in the config. +Files served from the `www` folder (`/local/` url), aren't protected by the Home Assistant authentication. Files stored in this folder, if the URL is known, can be accessed by anybody without authentication. Please make sure that your HA instance is not exposed via Internet or at least that long-lived token is not hardcoded in the config. ## Configure diff --git a/docker/README.md b/docker/README.md index 8319802f..204419be 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,15 +1,19 @@ -# Running with Docker +# The official TileBoard container -1. Download the [sample -config](https://raw.githubusercontent.com/resoai/TileBoard/master/config.example.js) -file to `config.js` and edit it. +A container for running [TileBoard](https://github.com/resoai/TileBoard) in a standalone web server. + +Runs in a minimal nginx server, serving the content on port 9000 by default. + +## Running with Docker + +1. Download the [sample config](https://raw.githubusercontent.com/resoai/TileBoard/master/config.example.js) file as `config.js` and configure it (see [configure](https://github.com/resoai/TileBoard/blob/master/README.md#configure) for more info). ```sh wget -O config.js https://raw.githubusercontent.com/resoai/TileBoard/master/config.example.js vim config.js ``` -2. Copy the following to `docker-compose.yml`: +2. Create a `docker-compose.yml` file with content: ```yaml version: '2'