Improved docker deployments

Dockerfile

@@ -24,4 +24,7 @@ RUN yarn build
 EXPOSE ${PORT}
 
 # Finally, run start command to serve up the built application
-CMD [ "yarn", "build-and-start"]
+CMD [ "yarn", "build-and-start"]
+
+# Run simple healthchecks every 5 mins, to check the Dashy's everythings great
+HEALTHCHECK --interval=5m --timeout=2s --start-period=30s CMD yarn health-check

README.md

@@ -29,6 +29,8 @@
 
 **Live Demos**: [Demo 1](https://dashy-demo-1.as93.net) ┆ [Demo 2](https://dashy-demo-2.as93.net) ┆ [Demo 3](https://dashy-demo-3.as93.net)
 
+**Spin up your own demo**: [![One-Click Deploy with PWD](https://img.shields.io/badge/Play--with--Docker-Deploy-2496ed?style=flat-square&logo=docker)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
+
 **Screenshots**
 ![Screenshots](https://i.ibb.co/r5T3MwM/dashy-screenshots.png)
 
@@ -42,19 +44,20 @@
 ## Getting Started 🛫
 
 > For full setup instructions, see: [**Getting Started**](./docs/getting-started.md)
+
 #### Deploying from Docker Hub 🐳
 
 You will need [Docker](https://docs.docker.com/get-docker/) installed on your system
 
 ```docker
 docker run -d \
-  -p 8080:80 \
+  -p 4000:80 \
   -v /root/my-local-conf.yml:/app/public/conf.yml \
   --name my-dashboard \
   --restart=always \
   lissy93/dashy:latest
 ```
-After making changes to your configuration file, you will need to run: `docker exec -it [container-id] yarn build` to rebuild. You can also run other commands, such as `yarn validate-config` this way too. Container ID can be found by running `docker ps`. 
+After making changes to your configuration file, you will need to run: `docker exec -it [container-id] yarn build` to rebuild. You can also run other commands, such as `yarn validate-config` this way too. Container ID can be found by running `docker ps`. Healthchecks are pre-configured to monitor the uptime and response times of Dashy, and the status of which can be seen in the container logs, e.g. `docker inspect --format "{{json .State.Health }}" [container-id]`.
 
 #### Deploying from Source 🚀
 
@@ -76,7 +79,9 @@ After making changes to your configuration file, you will need to run: `yarn bui
 
 Dashy is configured with a single [YAML](https://yaml.org/) file, located at `./public/conf.yml` (or `./app/public/conf.yml` for Docker). Any other optional user-customizable assets are also located in the `./public/` directory, e.g. `favicon.ico`, `manifest.json`, `robots.txt` and `web-icons/*`. If you are using Docker, the easiest way to method is to mount a Docker volume (e.g. `-v /root/my-local-conf.yml:/app/public/conf.yml`)
 
-In the production environment, the app needs to be rebuilt in order for changes to take effect. This can be done with `yarn build`, or `docker exec -it [container-id] yarn build` if you are using Docker (where container ID can be found by running `docker ps`). You can check that your config matches Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json) before deploying, by running `yarn validate-config.`
+In the production environment, the app needs to be rebuilt in order for changes to take effect. This can be done with `yarn build`, or `docker exec -it [container-id] yarn build` if you are using Docker (where container ID can be found by running `docker ps`).
+
+You can check that your config matches Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json) before deploying, by running `yarn validate-config.`
 
 You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) helpful for getting you started
 
@@ -86,7 +91,11 @@ You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce9
 
 > For full configuration documentation, see: [**Theming**](./docs/theming.md)
 
-<p align="right"><img src="https://i.ibb.co/BVSHV1v/dashy-themes-slideshow.gif" width="400"></p>
+<p align="center">
+  <a href="https://i.ibb.co/BVSHV1v/dashy-themes-slideshow.gif">
+    <img alt="Example Themes" src="/docs/assets/theme-slideshow.gif" width="400">
+  </a>
+</p>
 
 The app comes with a number of built-in themes, but it's also easy to write you're own. All colors, and most other CSS properties make use of CSS variables, which makes customizing the look and feel of Dashy very easy.
 
@@ -131,24 +140,26 @@ Some ideas for PRs include: bug fixes, improve the docs, add new themes, impleme
 Before you submit your pull request, please ensure the following:
 - Must be backwards compatible
 - All lint checks and tests must pass
-- If a new option in the the config file is added, it needs to be added into the schema, and documented in the configuring guide
+- If a new option in the the config file is added, it needs to be added into the [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json), and documented in the [configuring](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md) guide
 - If a new dependency is required, it must be essential, and it must be thoroughly checked out for security or efficiency issues
 - Your pull request will need to be up-to-date with master, and the PR template must be filled in
 
 ---
 
 ## Support 🙋‍♀️
 
-If you've found a bug, or something that isn't working as you'd expect, please raise an issue, so that it can be resolved. Similarly, if you're having trouble getting things up and running, feel free to ask a question. Feature requests and feedback are also welcome, as it helps Dashy improve.
+> For general discussions, the [Discussions Board](https://github.com/Lissy93/dashy/discussions) is now active!
+
+If you've found a bug, or something that isn't working as you'd expect, please raise an issue, so that it can be resolved. Similarly, if you're having trouble getting things up and running, feel free to ask a question. Feature requests and feedback are also welcome, as it helps Dashy improve. 
 
 - [Raise a Bug 🐛](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D)
 - [Submit a Feature Request 🦄](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A6%84+Feature+Request&template=feature-request---.md&title=%5BFEATURE_REQUEST%5D)
 - [Ask a Question 🤷‍♀️](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question------.md&title=%5BQUESTION%5D)
 - [Share Feedback 🌈](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%8C%88+Feedback&template=share-feedback---.md&title=%5BFEEDBACK%5D)
 
-For general questions about any of the technologies used, you should search the [web](https://duckduckgo.com), or open a question on [StackOverflow](https://stackoverflow.com/questions/)
+For more general questions about any of the technologies used, [StackOverflow](https://stackoverflow.com/questions/) may be more helpful first port of info
 
- If you need to get in touch securely with the author me, you can send any messages to me at:
+ If you need to get in touch securely with the author (me, Alicia Sykes), drop me a message at:
 - **Email**: `alicia at omg dot lol`
 - **Public Key** [`0688 F8D3 4587 D954 E9E5  1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7)
 
@@ -201,6 +212,9 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
 ##### Backup & Sync Server
 Although the app is purely frontend, there is an optional cloud backup and restore feature. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto)
 
+##### External Services
+The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker image is hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
+
 ### Alternatives 🙌
 
 There are a few self-hosted web apps, that serve a similar purpose to Dashy. If you're looking for a dashboard, and Dashy doesn't meet your needs, I highly recommend you check these projects out! Including, but not limited to: [HomeDash2](https://lamarios.github.io/Homedash2), [Homer](https://github.com/bastienwirtz/homer) (`Apache License 2.0`), [Organizr](https://organizr.app/) (`GPL-3.0 License`) and  [Heimdall](https://github.com/linuxserver/Heimdall) (`MIT License`)

bin/healthcheck.js

@@ -0,0 +1,37 @@
+/**
+ * An endpoint for confirming that the application is up and running
+ * Used for better Docker healthcheck results
+ * Note that exiting with code 1 indicates failure, and 0 is success
+ */
+
+const http = require('http');
+
+/* Location of the server to test */
+const port = process.env.PORT || !!process.env.IS_DOCKER ? 80 : 4000;
+const host = process.env.HOST || '0.0.0.0';
+const timeout = 2000;
+
+const requestOptions = { host, port, timeout };
+
+const startTime = new Date();
+
+console.log(`[${startTime}] Running health check...`);
+
+/* Starts quick HTTP server, attempts to send GET to app, then exists with appropriate exit code */
+const healthCheck = http.request(requestOptions, (response) => {
+  const totalTime = (new Date() - startTime) / 1000;
+  const status = response.statusCode;
+  const color = status === 200 ? '\x1b[32m' : '\x1b[31m';
+  const message = `${color}Status: ${status}\nRequest took ${totalTime} seconds\n\x1b[0m---`;
+  console.log(message);
+  if (status == 200) { process.exit(0); }
+  else { process.exit(1); }
+});
+
+/* If the server is not running, then print the error code, and exit with 1 */
+healthCheck.on('error', (err) => {
+  console.error(`\x1b[31mHealthceck Failed, Error: ${'\033[4m'}${err.code}\x1b[0m`);
+  process.exit(1);
+});
+
+healthCheck.end();

docker-compose.yml

@@ -1,14 +1,25 @@
 ---
-version: "3"
+# Welcome to Dashy! To get started, run `docker compose up`
+version: "3.8"
 services:
   dashy:
+    # To build from source, replace 'image: lissy93/dashy' with 'build: .'
+    # build: .
     image: lissy93/dashy
-    container_name: dashy
-    volumes:
-      - /root/my-config.yml:/app/public/conf.yml
+    container_name: Dashy
+    # Pass in your config file below, by specifying the path on your host machine
+    # volumes:
+      # - /root/my-config.yml:/app/public/conf.yml
     ports:
-      - 8080:80
-    environment:
-     - UID=1000
-     - GID=1000
-    restart: unless-stopped
+      - 4000:80
+    # Specify your user ID and group ID. You can find this by running `id -u` and `id -g`
+    # environment:
+    #  - UID=1000
+    #  - GID=1000
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'node', '/app/bin/healthcheck']
+      interval: 1m30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s

docs/configuring.md

@@ -49,6 +49,7 @@ All fields are optional, unless otherwise stated.
 **`cssThemes`** | `string[]` | _Optional_ | An array of custom theme names which can be used in the theme switcher dropdown
 **`externalStyleSheet`** | `string`  or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
 **`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
+**`showSplashScreen`** | `boolean` | _Optional_ | Should display a splash screen while the app is loading. Defaults to false, except on first load
 
 #### `section`
 

docs/contributing.md

@@ -64,7 +64,12 @@ on how to create a pull request..
 
 4. Make sure to update, or add to the tests when appropriate. Patches and
    features will not be accepted without tests. Run `yarn test` to check that
-   all tests pass after you've made changes.
+   all tests pass after you've made changes, and `yarn lint` for linting.
+
+   ```bash
+   git add ./path/to/modified/files
+   git commit -m "Fixed #xx by doing xyz"
+   ```
 
 5. If you added or changed a feature, make sure to document it accordingly in
    the docs and if applicable, in the `README.md` file.
@@ -97,6 +102,8 @@ Please also ensure that running the following scripts return no errors:
 
 A good resource for testing the Docker image on a totally fresh system, is by using [Play with Docker](https://labs.play-with-docker.com/). This will let you clone or pull your image, and spin up a container. This is useful for checking that everything behaves as it should on an independent system, and should get around the _'works on my computer'_ issue.
 
+All required checks will be run as a git-hook after doing a git commit. If you have any issues wit this, it can be disabled with the `--no-verify` flag
+
 #### Merging a PR
 
 Only maintainers can merge a PR. A pull request can only be merged if:

docs/developing.md

@@ -38,6 +38,11 @@ There is also:
 - `yarn build-and-start` will run `yarn build` and `yarn start`
 - `yarn build-watch` will output contents to `./dist` and recompile when anything in `./src` is modified, you can then use either `yarn start` or your own server, to have a production environment that watches for changes.
 
+Using the Vue CLI:
+- The app is build with Vue, and uses the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html) for basic commands.
+- If you have [NPX](https://github.com/npm/npx) installed, then you can invoke the Vue CLI binary using `npx vue-cli-service [command]`
+- Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running `vue ui`, and opening up `http://localhost:8000`
+
 Note:
 - If you are using NPM, replace `yarn` with `npm run`
 - If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
@@ -59,7 +64,7 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/
 
 ### Style Guide
 
-Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically. Any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged.
+Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically. Any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
 
 The most significant things to note are:
 - Indentation should be done with two spaces
@@ -108,6 +113,15 @@ Checklist:
 - Document the new value in [`configuring.md`](./configuring.md)
 - Test that the reading of the new attribute is properly handled, and will not cause any errors when it is missing or populated with an unexpected value
 
+#### Updating Dependencies
+
+Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). It is important to thoroughly test after any big dependency updates.
+
+### Development Tools
+
+#### Performance - Lighthouse
+The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.
+
 ### Directory Structure
 
 #### Files in the Root: `./`
@@ -215,3 +229,16 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
 
 - [`connect`](https://github.com/senchalabs/connect) - Minimilistic middleware layer for chaining together Node.js requests handled by the server file `MIT`
 - [`serve-static`](https://github.com/expressjs/serve-static) - Lightweight static Node file server `MIT`
+
+##### External Services
+The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker image is hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
+
+### Notes
+
+#### Known Warnings
+
+When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update
+
+`WARN  A new version of sass-loader is available. Please upgrade for best experience.` - Currently we're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI's webpack configuration.
+
+`WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).` - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.