diff --git a/README.md b/README.md index c92f9369..a5f710fa 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@
+**[⬆️ Back to Top](#dashy)** + --- ## Getting Started 🛫 @@ -76,8 +78,11 @@ After making changes to your configuration file, you will need to run: `yarn bui Dashy supports 1-Click deployments on several popular cloud platforms (with more on the way!). To get started, just click a link below: - [Deploy to Netlify](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) - [Deploy to Heroku](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy) +- [Deploy with Vercel](https://vercel.com/new/project?template=https://github.com/lissy93/dashy) - [Deploy with PWD](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) +**[⬆️ Back to Top](#dashy)** + --- ## Configuring 🔧 @@ -92,6 +97,8 @@ You can check that your config matches Dashy's [schema](https://github.com/Lissy You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) helpful for getting you started +**[⬆️ Back to Top](#dashy)** + --- ## Theming 🎨 @@ -108,6 +115,8 @@ The app comes with a number of built-in themes, but it's also easy to write you' You can also apply custom CSS overrides directly through the UI (Under Config menu --> Custom CSS), or specify it in your config file under `appConfig.customCss`. If you have a lot of custom styles, you can pass in the path to a stylesheet, in `appConfig.externalStyleSheet`. +**[⬆️ Back to Top](#dashy)** + --- ## Cloud Backup & Sync ☁ @@ -120,6 +129,8 @@ This is useful not only for backing up your configuration off-site, but it also All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store. +**[⬆️ Back to Top](#dashy)** + --- ## Developing 🧱 @@ -134,6 +145,8 @@ Hot reload is enabled, so changes will be detected automatically, triggering the If you are new to Vue.js or web development and want to learn more, [here are some resources](docs/developing.md#resources-for-beginners) to help get you started. Dashy is a pretty straight-forward application, so would make an ideal candidate for your first PR! +**[⬆️ Back to Top](#dashy)** + --- ## Contributing 😇 @@ -151,6 +164,8 @@ Before you submit your pull request, please ensure the following: - 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 +**[⬆️ Back to Top](#dashy)** + --- ## Support 🙋♀️ @@ -170,6 +185,8 @@ For more general questions about any of the technologies used, [StackOverflow](h - **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) +**[⬆️ Back to Top](#dashy)** + --- ## Documentation 📘 @@ -183,15 +200,15 @@ For more general questions about any of the technologies used, [StackOverflow](h - [Backup & Restore](/docs/backup-restore.md) - [Theming](/docs/theming.md) +**[⬆️ Back to Top](#dashy)** + --- ## Credits 🏆 ### Contributors 👥 -![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/03fbaf35ff4653d16a622cfce00a1347c13d0192/docs/assets/CONTRIBUTORS.svg) - -_(^^ It's lonely here all by myself - submit a PR to become listed as a contributor!)_ +![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg) ### Dependencies 🔗 @@ -226,6 +243,8 @@ The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.co 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`) +**[⬆️ Back to Top](#dashy)** + --- ## License 📜 @@ -249,6 +268,8 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWAREOR THE OR OTHER DEALINGS IN THE SOFTWARE. ``` +**[⬆️ Back to Top](#dashy)** + --- diff --git a/docs/configuring.md b/docs/configuring.md index e6d4474c..addbb4a6 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -13,7 +13,6 @@ There's a couple of things to remember, before getting started: All fields are optional, unless otherwise stated. - #### Top-Level Fields **Field** | **Type** | **Required**| **Description** @@ -22,6 +21,8 @@ All fields are optional, unless otherwise stated. **`appConfig`** | `object` | _Optional_ | Settings related to how the app functions, including API keys and global styles. See [`appConfig`](#appconfig-optional) **`sections`** | `array` | Required | An array of sections, each containing an array of items, which will be displayed as links. See [`section`](#section) +**[⬆️ Back to Top](#configuring)** + #### `PageInfo` **Field** | **Type** | **Required**| **Description** @@ -31,6 +32,8 @@ All fields are optional, unless otherwise stated. **`navLinks`** | `array` | _Optional_ | Optional list of a maximum of 6 links, which will be displayed in the navigation bar. See [`navLinks`](#pageinfonavlinks-optional) **`footerText`** | `string` | _Optional_ | Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS +**[⬆️ Back to Top](#configuring)** + #### `pageInfo.navLinks` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -38,6 +41,8 @@ All fields are optional, unless otherwise stated. **`title`** | `string` | Required | The text to display on the link button **`path`** | `string` | Required | The URL to navigate to when clicked. Can be relative (e.g. `/about`) or absolute (e.g. `https://example.com` or `http://192.168.1.1`) +**[⬆️ Back to Top](#configuring)** + #### `appConfig` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -51,6 +56,8 @@ All fields are optional, unless otherwise stated. **`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 +**[⬆️ Back to Top](#configuring)** + #### `section` **Field** | **Type** | **Required**| **Description** @@ -60,6 +67,8 @@ All fields are optional, unless otherwise stated. **`items`** | `array` | Required | An array of items to be displayed within the section. See [`item`](#sectionitem) **`displayData`** | `object` | _Optional_ | Meta-data to optionally overide display settings for a given section. See [`displayData`](#sectiondisplaydata-optional) +**[⬆️ Back to Top](#configuring)** + #### `section.item` **Field** | **Type** | **Required**| **Description** @@ -72,6 +81,8 @@ All fields are optional, unless otherwise stated. **`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well **`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background +**[⬆️ Back to Top](#configuring)** + #### `section.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -86,12 +97,15 @@ All fields are optional, unless otherwise stated. **`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` **`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` +**[⬆️ Back to Top](#configuring)** + #### `section.icon` and `section.item.icon` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- **`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised. +**[⬆️ Back to Top](#configuring)** #### Example @@ -125,3 +139,6 @@ sections: # An array of sections ``` For more example config files, see: [this gist](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) + +**[⬆️ Back to Top](#configuring)** + diff --git a/docs/getting-started.md b/docs/getting-started.md index 0cf405e2..15b1ae40 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -13,6 +13,9 @@ - [Updating Docker Container](#updating-docker-container) - [Automating Docker Updates](#automatic-docker-updates) - [Updating from Source](#updating-dashy-from-source) +- [Web Server Configuration](#web-server-configuration) + - [NGINX](#nginx) + - [Apache](#apache) ## Deployment @@ -63,7 +66,7 @@ Dashy supports 1-Click deployments on several popular cloud platforms. #### Netlify [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) -[Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. +[Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup. To deploy Dashy to Netlify, use the following link ``` @@ -73,13 +76,62 @@ https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy #### Heroku [![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy) -[Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps. +[Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while To deploy Dashy to Heroku, use the following link ``` https://heroku.com/deploy?template=https://github.com/Lissy93/dashy ``` +#### Cloudflare Workers +[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare) + +[Cloudflare Workers](https://workers.cloudflare.com/) is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on [Worker Sites](https://developers.cloudflare.com/workers/platform/sites) + +To deploy Dashy to Cloudflare, use the following link +``` +https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare +``` + +#### Deploy to Vercel +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy) + +[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits. + +To deploy Dashy to Vercel, use the following link +``` +https://vercel.com/new/project?template=https://github.com/lissy93/dashy +``` + +#### Deploy to DigitalOcean +[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79) + +[DigitalOcan](https://www.digitalocean.com/) is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use. + +``` +https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean +``` + +#### Platform.sh +[![Deploy to Platform.sh](https://platform.sh/images/deploy/deploy-button-lg-blue.svg)](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy) + +[Platform.sh](https://platform.sh) is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method + +To deploy Dashy to Platform.sh, use the following link +``` +https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy +``` + +#### Deploy to Scalingo +[![Deploy on Scalingo](https://cdn.scalingo.com/deploy/button.svg)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master) + +[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method + +To deploy Dashy to Scalingo, use the following link +``` +https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master +``` + #### Play-with-Docker [![Try in PWD](https://raw.githubusercontent.com/play-with-docker/stacks/cff22438/assets/images/button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) @@ -89,6 +141,19 @@ To run Dashy in PWD, use the following URL: ``` https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml ``` + +#### Surge.sh +[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps. + +Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl) + +To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands +``` +yarn add -g surge +yarn build +surge ./dist +``` + **[⬆️ Back to Top](#getting-started)** --- @@ -121,9 +186,9 @@ To restart unhealthy containers automatically, check out [Autoheal](https://hub. ### Logs and Performance -You can view logs for a given Docker container with `docker logs [container-id]`, add the `--follow` flag to stream the logs. For more info, see the [Logging Documentation](https://docs.docker.com/config/containers/logging/). [Dozzle](https://dozzle.dev/) is a useful tool, that provides a web interface where you can stream and query logs from all your running containers from a single web app. +You can view logs for a given Docker container with `docker logs [container-id]`, add the `--follow` flag to stream the logs. For more info, see the [Logging Documentation](https://docs.docker.com/config/containers/logging/). There's also [Dozzle](https://dozzle.dev/), a useful tool, that provides a web interface where you can stream and query logs from all your running containers from a single web app. -You can check the resource usage for your running Docker containers with `docker stats` or `docker stats [container-id]`. For more info, see the [Stats Documentation](https://docs.docker.com/engine/reference/commandline/stats/). [cAdvisor](https://github.com/google/cadvisor) is a useful web app for viewing and analyzing resource usage and performance of your running containers. +You can check the resource usage for your running Docker containers with `docker stats` or `docker stats [container-id]`. For more info, see the [Stats Documentation](https://docs.docker.com/engine/reference/commandline/stats/). There's also [cAdvisor](https://github.com/google/cadvisor), a useful web app for viewing and analyzing resource usage and performance of all your running containers. You can also view logs, resource usage and other info as well as manage your Docker workflow in third-party Docker management apps. For example [Portainer](https://github.com/portainer/portainer) an all-in-one management web UI for Docker and Kubernetes, or [LazyDocker](https://github.com/jesseduffield/lazydocker) a terminal UI for Docker container management and monitoring. @@ -166,4 +231,74 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe 5. Start: `yarn start` -**[⬆️ Back to Top](#getting-started)** \ No newline at end of file +**[⬆️ Back to Top](#getting-started)** + +--- + +## Web Server Configuration + +_The following section only applies if you are not using Docker, and would like to use your own web server_ + +Dashy ships with a pre-configured Node.js server, in [`server.js`](https://github.com/Lissy93/dashy/blob/master/server.js) which serves up the contents of the `./dist` directory on a given port. You can start the server by running `node server`. Note that the app must have been build (run `yarn build`), and you need [Node.js](https://nodejs.org) installed. + +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. + +### NGINX + +Create a new file in `/etc/nginx/sites-enabled/dashy` + +``` +server { + listen 80; + listen [::]:80; + + root /var/www/dashy/html; + index index.html; + + server_name your-domain.com www.your-domain.com; + + location / { + try_files $uri $uri/ =404; + } +} +``` +Then upload the build contents of Dashy's dist directory to that location. +For example: `scp -r ./dist/* [username]@[server_ip]:/var/www/dashy/html` + +### Apache + +Copy Dashy's dist folder to your apache server, `sudo cp -r ./dashy/dist /var/www/html/dashy`. + +In your Apache config, `/etc/apche2/apache2.conf` add: +``` +