diff --git a/README.md b/README.md index 7f760ea3..76e22f23 100644 --- a/README.md +++ b/README.md @@ -93,10 +93,12 @@ Dashy supports 1-Click deployments on several popular cloud platforms (with more 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`). +In the production environment, the app needs to be rebuilt in order for changes to take effect. This should happen automatically, but can also be triggered by running `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.` +It is now possible to update Dashy's config directly through the UI, and have changes written to disk. You can disable this feature by setting: `appConfig.allowConfigEdit: false`. If you are using users within Dashy, then you need to be logged in to a user of `type: admin` in order to modify the configuration globally. You can also trigger a rebuild of the app through the UI (Settings --> Rebuild). The current theme, and other visual preferences are only stored locally, unless otherwise specified in the config file. The option to only apply config changes locally is still available, and can be used in conjunction with the cloud backup feature to sync data between instances. + You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) helpful for getting you started **[⬆️ Back to Top](#dashy)** diff --git a/docs/configuring.md b/docs/configuring.md index 077682ec..7eab0206 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -7,9 +7,17 @@ If you're new to YAML, it's pretty straight-forward. The format is exactly the s You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10). There's a couple of things to remember, before getting started: -- After modifying your config, you will need to run `yarn build` to recompile the application +- After modifying your config, the app needs to be recompiled, run `yarn build` (this happens automatically in newer versions) - You can check that your config file fits the schema, by running `yarn validate-config` -- Any changes made locally through the UI need to be exported into this file, in order for them to persist across devices +- Any which are only saved locally through the UI need to be exported into this file, in order for them to persist across devices + +#### Config Saving Methods +When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**. Changes saved locally will only be applied to the current user through the browser, and to apply to other instances, you either need to use the cloud sync feature, or manually update the conf.yml file. On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. + +#### Preventing Changes being Written to Disk +To disallow any changes from being written to disk, then set `appConfig.allowConfigEdit: false`. If you are using users, and have setup `auth` within Dashy, then only users with `type: admin` will be able to write config changes to disk. + +It is recommended to make a backup of your config file. All fields are optional, unless otherwise stated. diff --git a/docs/contributing.md b/docs/contributing.md index d5dbf358..b3393ca2 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -83,6 +83,9 @@ on how to create a pull request.. 8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description. +You can use emojis in your commit message, to indicate the category of the task. +For a reference of what each emoji means in the context of commits, see [gitmoji.dev](https://gitmoji.dev/). + #### Testing the Production App For larger pull requests, please also check that it works as expected in a production environment. diff --git a/docs/deployment.md b/docs/deployment.md index fb9388ad..c867d7a6 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -269,6 +269,12 @@ Dashy ships with a pre-configured Node.js server, in [`server.js`](https://githu If you wish to run Dashy from a sub page (e.g. `example.com/dashy`), then just set the `BASE_URL` environmental variable to that page name (in this example, `/dashy`), before building the app, and the path to all assets will then resolve to the new path, instead of `./`. However, since Dashy is just a static web application, it can be served with whatever server you like. The following section outlines how you can configure a web server. + +Note, that if you choose not to use `server.js` to serve up the app, you will loose access to the following features: +- Loading page, while the app is building +- Writing config file to disk from the UI +- Website status indicators, and ping checks + ### NGINX Create a new file in `/etc/nginx/sites-enabled/dashy` diff --git a/docs/developing.md b/docs/developing.md index be11bff8..de600bfd 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -48,8 +48,8 @@ Note: - If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps` ### Environmental Variables - - `PORT` - The port in which the application will run (defaults to `4000` for the Node.js server, and `80` within the Docker container) +- `NODE_ENV` - Which environment to use, either `production`, `development` or `test` - `VUE_APP_DOMAIN` - The URL where Dashy is going to be accessible from. This should include the protocol, hostname and (if not 80 or 443), then the port too, e.g. `https://localhost:3000`, `http://192.168.1.2:4002` or `https://dashy.mydomain.com` All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file. @@ -58,6 +58,15 @@ If you do add new variables, ensure that there is always a fallback (define it i Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file. +### Environment Modes +Both the Node app and Vue app supports several environments: `production`, `development` and `test`. You can set the environment using the `NODE_ENV` variable (either with your OS, in the Docker script or in an `.env` file - see [Environmental Variables](#environmental-variables) above). + +The production environment will build the app in full, minifying and streamlining all assets. This means that building takes longer, but the app will then run faster. Whereas the dev environment creates a webpack configuration which enables HMR, doesn't hash assets or create vendor bundles in order to allow for fast re-builds when running a dev server. It supports sourcemaps and other debugging tools, re-compiles and reloads quickly but is not optimized, and so the app will not be as snappy as it could be. The test environment is intended for test running servers, it ignores assets that aren't needed for testing, and focuses on running all the E2E, regression and unit tests. For more information, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes). + +By default: +- `production` is used by `yarn build` (or `vue-cli-service build`) and `yarn build-and-start` and `yarn pm2-start` +- `development` is used by `yarn dev` (or `vue-cli-service serve`) +- `test` is used by `yarn test` (or `vue-cli-service test:unit`) ### Resources for Beginners New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project: - [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)