Skip to main content

Developing

This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture. If you're adding new features, you may want to check out the Development Guides docs, for tutorials covering basic tasks.

Setting up the Dev Environment#

Prerequisites#

You will need either the latest or LTS version of Node.js to build and serve the application and Git to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need Docker. To avoid any unexpected issues, ensure you've got at least NPM V 7.5 or Yarn 1.22 (you may find NVM helpful for switching/ managing versions).

Running the Project#

  1. Get Code: git clone https://github.com/Lissy93/dashy.git
  2. Navigate into the directory: cd dashy
  3. Install dependencies: yarn
  4. Start dev server: yarn dev

Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.

Project Commands#

Basics#

  • yarn build - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run yarn build or docker exec -it [container-id] yarn build
  • yarn start - Starts a web server, and serves up the production site from ./dist (must run build command first)

Development#

  • yarn dev - Starts the development server with hot reloading
  • yarn lint - Lints code to ensure it follows a consistent, neat style
  • yarn test - Runs tests, and outputs results

Utils and Checks#

  • yarn validate-config - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with yarn validate-config or docker exec -it [container-id] yarn validate-config. Your config file needs to be in /public/conf.yml (or within your Docker container at /app/public/conf.yml). This will first check that your YAML is valid, and then validates it against Dashy's schema.
  • yarn health-check - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability

Alternate Start Commands#

  • yarn build-and-start - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the yarn build and yarn start commands
  • yarn build-watch - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then yarn dev would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
  • yarn pm2-start - Starts the Node server using PM2, a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional management solution. If you are running the app on bare metal, it is recommended to use this start command

Notes#

  • 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
  • You can manage the app using the Vue-CLI Service, with npx vue-cli-service [command]. Or to start the Vue Management UI, run npx vue ui, and open http://localhost:8000

Environmental Variables#

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.

You can set variables either in your environment, or using the .env file.

  • NODE_ENV - Current environment, can be either development, production or test
  • PORT - The port to expose the running application on
  • HOST - The host that Dashy is running on, domain or IP
  • BASE_URL - The default base path for serving up static assets
  • VUE_APP_DOMAIN - Usually the same as BASE_URL, but accessible in frontend
  • INTEGRITY - Should enable SRI for build script and link resources
  • IS_DOCKER - Computed automatically on build. Indicates if running in container
  • VUE_APP_VERSION - Again, set automatically using package.json during build time

Environment Modes#

You can set the environment using the NODE_ENV variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: production, development and test. For more info, see Vue CLI Environment Modes.


Git Strategy#

Git Flow#

Like most Git repos, we are following the Github Flow standard.

  1. Create a branch (or fork if you don'd have write access)
  2. Code some awesome stuff ๐Ÿง‘โ€๐Ÿ’ป
  3. Add, commit and push your changes to your branch/ fork
  4. Head over to GitHub and create a Pull Request
  5. Fill in the required sections in the template, and hit submit
  6. Follow up with any reviews on your code
  7. Merge ๐ŸŽ‰

Git Branch Naming#

The format of your branch name should be something similar to: [TYPE]/[TICKET]_[TITLE] For example, FEATURE/420_Awesome-feature or FIX/690_login-server-error

Commit Emojis#

Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.

  • ๐ŸŽจ :art: - Improve structure / format of the code.
  • โšก๏ธ :zap: - Improve performance.
  • ๐Ÿ”ฅ :fire: - Remove code or files.
  • ๐Ÿ› :bug: - Fix a bug.
  • ๐Ÿš‘๏ธ :ambulance: - Critical hotfix
  • โœจ :sparkles: - Introduce new features.
  • ๐Ÿ“ :memo: - Add or update documentation.
  • ๐Ÿš€ :rocket: - Deploy stuff.
  • ๐Ÿ’„ :lipstick: - Add or update the UI and style files.
  • ๐ŸŽ‰ :tada: - Begin a project.
  • โœ… :white_check_mark: - Add, update, or pass tests.
  • ๐Ÿ”’๏ธ :lock: - Fix security issues.
  • ๐Ÿ”– :bookmark: - Make a Release or Version tag.
  • ๐Ÿšจ :rotating_light: - Fix compiler / linter warnings.
  • ๐Ÿšง :construction: - Work in progress.
  • โฌ†๏ธ :arrow_up: - Upgrade dependencies.
  • ๐Ÿ‘ท :construction_worker: - Add or update CI build system.
  • โ™ป๏ธ :recycle: - Refactor code.
  • ๐Ÿฉน :adhesive_bandage: - Simple fix for a non-critical issue.
  • ๐Ÿ”ง :wrench: - Add or update configuration files.
  • ๐Ÿฑ :bento: - Add or update assets.
  • ๐Ÿ—ƒ๏ธ :card_file_box: - Perform database schema related changes.
  • โœ๏ธ :pencil2: - Fix typos.
  • ๐ŸŒ :globe_with_meridians: - Internationalization and translations.

For a full list of options, see gitmoji.dev

PR Guidelines#

Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!

For a pull request to be merged, it must:

  • Must be backwards compatible
  • The build, lint and tests (run by GH actions) must pass
  • There must not be any merge conflicts

When you submit your PR, include the required info, by filling out the PR template. Including:

  • A brief description of your changes
  • The issue, ticket or discussion number (if applicable)
  • For UI relate updates include a screenshot
  • If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
  • Finally, check the checkboxes, to confirm that the standards are met, and hit submit!

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:

As well as Node, Git and Docker- you'll also need an IDE (e.g. VS Code or Vim) and a terminal (Windows users may find WSL more convenient).


App Info#

Style Guide#

Linting is done using ESLint, and using the Vue.js Styleguide, which is very similar to the AirBnB Stylguide. You can run yarn lint to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and 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
  • Strings should use single quotes
  • All statements must end in a semi-colon
  • The final element in all objects must be preceded with a comma
  • Maximum line length is 100
  • There must be exactly one blank line between sections, before function names, and at the end of the file
  • With conditionals, put else on the same line as your if blockโ€™s closing brace
  • All multiline blocks must use braces
  • Avoid console statements in the frontend

Styleguides:


Application Structure#

Files in the Root: ./#

โ•ฎโ”œโ”€โ”€ package.json        # Project meta-data, dependencies and paths to scriptsโ”œโ”€โ”€ src/                # Project front-end source codeโ”œโ”€โ”€ server.js           # A Node.js server to serve up the /dist directoryโ”œโ”€โ”€ services/           # All server-side endpoints and utilitiesโ”œโ”€โ”€ vue.config.js       # Vue.js configurationโ”œโ”€โ”€ Dockerfile          # The blueprint for building the Docker containerโ”œโ”€โ”€ docker-compose.yml  # A Docker run commandโ”œโ”€โ”€ .env                # Location for any environmental variablesโ”œโ”€โ”€ yarn.lock           # Auto-generated list of current packages and version numbersโ”œโ”€โ”€ docs/               # Markdown documentationโ”œโ”€โ”€ README.md           # Readme, basic info for getting startedโ”œโ”€โ”€ LICENSE.md          # License for useโ•ฏ

Frontend Source: ./src/#

./srcโ”œโ”€โ”€ App.vue                       # Vue.js starting fileโ”œโ”€โ”€ assets                        # Static non-compiled assetsโ”‚  โ”œโ”€โ”€ fonts                      # .ttf font filesโ”‚  โ”œโ”€โ”€ locales                    # All app text, each language in a separate JSON fileโ”‚  โ•ฐโ”€โ”€ interface-icons            # SVG icons used in the app โ”œโ”€โ”€ components                    # All front-end Vue web componentsโ”‚  โ”œโ”€โ”€ Charts                     # Charting components for dynamically displaying widget dataโ”‚  โ”‚  โ”œโ”€โ”€ Gauge.vue               # A speed-dial style chart for showing 0 - 100 valuesโ”‚  โ”‚  โ•ฐโ”€โ”€ PercentageChart.vue     # A horizontal bar for showing percentage breakdownsโ”‚  โ”œโ”€โ”€ Configuration              # Components relating to the user config pop-upโ”‚  โ”‚  โ”œโ”€โ”€ AppInfoModal.vue        # A modal showing core app info, like version, language, etcโ”‚  โ”‚  โ”œโ”€โ”€ AppVersion.vue          # Shows current version from package.json, compares with GitHubโ”‚  โ”‚  โ”œโ”€โ”€ CloudBackupRestore.vue  # Form where the user manages cloud sync optionsโ”‚  โ”‚  โ”œโ”€โ”€ ConfigContainer.vue     # Main container, wrapping all other config componentsโ”‚  โ”‚  โ”œโ”€โ”€ CustomCss.vue           # Form where the user can input custom CSSโ”‚  โ”‚  โ”œโ”€โ”€ EditSiteMeta.vue        # Form where the user can edit site meta dataโ”‚  โ”‚  โ”œโ”€โ”€ JsonEditor.vue          # JSON editor, where the user can modify the main config fileโ”‚  โ”‚  โ•ฐโ”€โ”€ RebuildApp.vue          # A component allowing user to trigger a rebuild through the UIโ”‚  โ”œโ”€โ”€ FormElements               # Basic form elements used throughout the appโ”‚  โ”‚  โ”œโ”€โ”€ Button.vue              # Standard button componentโ”‚  โ”‚  โ”œโ”€โ”€ Radio.vue               # Standard radio button inputโ”‚  โ”‚  โ”œโ”€โ”€ Select.vue              # Standard dropdown input selectorโ”‚  โ”‚  โ”œโ”€โ”€ Input.vue               # Standard text field input componentโ”‚  โ”‚  โ•ฐโ”€โ”€ Toggle.vue              # Standard on / off toggle switchโ”‚  โ”œโ”€โ”€ InteractiveEditor          # Components for the interactive UI config editorโ”‚  โ”‚  โ”œโ”€โ”€ AddNewSectionLauncher   # Button that launches the EditSection form, used for adding new sectionโ”‚  โ”‚  โ”œโ”€โ”€ EditAppConfig.vue       # Form for editing appConfigโ”‚  โ”‚  โ”œโ”€โ”€ EditPageInfo.vue        # Form for editing pageInfoโ”‚  โ”‚  โ”œโ”€โ”€ EditSection.vue         # Form for adding / editing sectionsโ”‚  โ”‚  โ”œโ”€โ”€ EditItem.vue            # Form for adding or editing itemsโ”‚  โ”‚  โ”œโ”€โ”€ EditModeSaveMenu.vue    # The bar at the bottom of screen in edit mode, containing save buttonsโ”‚  โ”‚  โ”œโ”€โ”€ EditModeTopBanner.vue   # The bar at the top of screen in edit modeโ”‚  โ”‚  โ”œโ”€โ”€ ExportConfigMenu.vue    # Modal for viewing / exporting edited configโ”‚  โ”‚  โ”œโ”€โ”€ MoveItemTo.vue          # Form for moving / copying items to other sectionsโ”‚  โ”‚  โ•ฐโ”€โ”€ SaveCancelButtons.vue   # Buttons visible in all the edit menus, to save or cancel changesโ”‚  โ”œโ”€โ”€ LinkItems                  # Components for Sections and Link Itemsโ”‚  โ”‚  โ”œโ”€โ”€ Collapsable.vue         # The collapsible functionality of sectionsโ”‚  โ”‚  โ”œโ”€โ”€ IframeModal.vue         # Pop-up iframe modal, for viewing websites within the appโ”‚  โ”‚  โ”œโ”€โ”€ Item.vue                # Main link item, which is displayed within an item groupโ”‚  โ”‚  โ”œโ”€โ”€ ItemGroup.vue           # Item group is a section containing iconsโ”‚  โ”‚  โ”œโ”€โ”€ ItemIcon.vue            # The icon used by both items and sectionsโ”‚  โ”‚  โ”œโ”€โ”€ ItemOpenMethodIcon.vue  # A small icon, visible on hover, indicating opening method โ”‚  โ”‚  โ”œโ”€โ”€ ItemContextMenu.vue     # The right-click menu, for showing Item opening methods and infoโ”‚  โ”‚  โ”œโ”€โ”€ SectionContextMenu.vue  # The right-click menu, for showing Section edit/ open optionsโ”‚  โ”‚  โ•ฐโ”€โ”€ StatusIndicator.vue     # Traffic light dot, showing if app is online or downโ”‚  โ”œโ”€โ”€ Minimal View               # Components used for the startpage / minimal alternative viewโ”‚  โ”‚  โ”œโ”€โ”€ MinimalHeading.vue      # Title part of minimal viewโ”‚  โ”‚  โ”œโ”€โ”€ MinimalSearch.vue       # Search bar for minimal viewโ”‚  โ”‚  โ•ฐโ”€โ”€ MinimalSection.vue      # Tabbed-Item section for minimal viewโ”‚  โ”œโ”€โ”€ PageStrcture               # Components relating the main structure of the pageโ”‚  โ”‚  โ”œโ”€โ”€ Footer.vue              # Footer, visible at the bottom of all pagesโ”‚  โ”‚  โ”œโ”€โ”€ Header.vue              # Header, visible at the top of pages, and includes title and navโ”‚  โ”‚  โ”œโ”€โ”€ LoadingScreen.vue       # Splash screen shown on first loadโ”‚  โ”‚  โ”œโ”€โ”€ Nav.vue                 # Navigation bar, includes a list of linksโ”‚  โ”‚  โ•ฐโ”€โ”€ PageTitle.vue           # Page title and sub-title, visible within the Headerโ”‚  โ”œโ”€โ”€ Workspace                  # Components used for the multi-tasking/ Workspace viewโ”‚  โ”‚  โ”œโ”€โ”€ MultiTaskingWeb.vue     # When multi-tasking enabled, generates new iframeโ”‚  โ”‚  โ”œโ”€โ”€ SideBar.vue             # The left sidebar for the workspace viewโ”‚  โ”‚  โ”œโ”€โ”€ SideBarItem.vue         # App item for the sidebar viewโ”‚  โ”‚  โ”œโ”€โ”€ SideBarSection.vue      # Collapsible collection of items within workspace sidebarโ”‚  โ”‚  โ”œโ”€โ”€ WebContent.vue          # Workspace iframe view, displays content of current appโ”‚  โ”‚  โ•ฐโ”€โ”€ WidgetView.vue          # Workspace container for displaying widgets in main contentโ”‚  โ”œโ”€โ”€ Widgets                    # Directory contains all custom widget componentsโ”‚  โ”‚  โ•ฐโ”€โ”€ ....                    # Too many to list, see widget docs insteadโ”‚  โ•ฐโ”€โ”€ Settings                   # Components relating to the quick-settings, in the top-rightโ”‚     โ”œโ”€โ”€ AuthButtons.vue         # Logout button and other app infoโ”‚     โ”œโ”€โ”€ ConfigLauncher.vue      # Icon that when clicked will launch the Configuration componentโ”‚     โ”œโ”€โ”€ CustomThemeMaker.vue    # Color pickers for letting user build their own themeโ”‚     โ”œโ”€โ”€ ItemSizeSelector.vue    # Set of buttons used to set and save item sizeโ”‚     โ”œโ”€โ”€ KeyboardShortcutInfo.vue# Small pop-up displaying the available keyboard shortcutsโ”‚     โ”œโ”€โ”€ LanguageSwitcher.vue    # Dropdown in a modal for changing app languageโ”‚     โ”œโ”€โ”€ LayoutSelector.vue      # Set of buttons, letting the user select their desired layoutโ”‚     โ”œโ”€โ”€ SearchBar.vue           # The input field in the header, used for searching the appโ”‚     โ”œโ”€โ”€ SettingsContainer.vue   # Container that wraps all the quick-settings componentsโ”‚     โ•ฐโ”€โ”€ ThemeSelector.vue       # Drop-down menu enabling the user to select and change themesโ”œโ”€โ”€ main.js                       # Main front-end entry pointโ”œโ”€โ”€ registerServiceWorker.js      # Registers and manages service workers, for PWA appsโ”œโ”€โ”€ router.js                     # Defines all available application routesโ”œโ”€โ”€ styles                        # Directory of all globally used common SCSS stylesโ”‚  โ”œโ”€โ”€ color-palette.scss         # All color variable names and default valuesโ”‚  โ”œโ”€โ”€ color-themes.scss          # All variable values for built-in themesโ”‚  โ”œโ”€โ”€ dimensions.scss            # Dimensions and sizes as variablesโ”‚  โ”œโ”€โ”€ global-styles.scss         # Basics and style resets used globallyโ”‚  โ”œโ”€โ”€ media-queries.scss         # Screen sizes and media queriesโ”‚  โ”œโ”€โ”€ style-helpers.scss         # SCSS functions used for modifying valuesโ”‚  โ”œโ”€โ”€ typography.scss            # Font and text styles used globallyโ”‚  โ•ฐโ”€โ”€ user-defined-themes.scss   # Empty, put any custom styles or themes hereโ”œโ”€โ”€ mixins                        # Reusable component bases, extended by other views / componentsโ”‚  โ”œโ”€โ”€ ChartingMixin.js           # Functions for rendering charts in widget componentsโ”‚  โ”œโ”€โ”€ GlancesMixin.js            # Functions for fetching system info from Glances for widgetsโ”‚  โ”œโ”€โ”€ HomeMixin.js               # Functions for homepage, used by default, minimal and workspace viewsโ”‚  โ•ฐโ”€โ”€ WidgetMixin.js             # Functions for all widgets, like data fetching, updating and error handlingโ”œโ”€โ”€ utils                         # Directory of re-used helper functionsโ”‚  โ”œโ”€โ”€ ArrowKeyNavigation.js      # Functionality for arrow-key navigationโ”‚  โ”œโ”€โ”€ Auth.js                    # Handles all authentication related actionsโ”‚  โ”œโ”€โ”€ CheckSectionVisibility.js  # Checks which parts of the page should be visible/ hidden based on configโ”‚  โ”œโ”€โ”€ ClickOutside.js            # A directive for detecting click, used to hide dropdown, modal or context menuโ”‚  โ”œโ”€โ”€ ConfigHelpers.js           # Helper functions for managing configurationโ”‚  โ”œโ”€โ”€ CloudBackup.js             # Functionality for encrypting, processing and network callsโ”‚  โ”œโ”€โ”€ ConfigSchema.json          # The schema, used to validate the users conf.yml fileโ”‚  โ”œโ”€โ”€ ConfigAccumulator.js       # Central place for managing and combining configโ”‚  โ”œโ”€โ”€ ConfigHelpers.json         # Collection of helper functions to process config using accumulatorโ”‚  โ”œโ”€โ”€ ConfigValidator.js         # A helper script that validates the config file against schemaโ”‚  โ”œโ”€โ”€ CoolConsole.js             # Prints info, warning and error messages to browser console, with a cool styleโ”‚  โ”œโ”€โ”€ defaults.js                # Global constants and their default valuesโ”‚  โ”œโ”€โ”€ emojis.json                # List of emojis with unicode and shortcode, used for emoji icon featureโ”‚  โ”œโ”€โ”€ EmojiUnicodeRegex.js       # Regular expression to validate emoji unicode format, for emoji iconsโ”‚  โ”œโ”€โ”€ ErrorHandler.js            # Helper function called when an error is returnedโ”‚  โ”œโ”€โ”€ InitServiceWorker.js       # Initializes and manages service worker, if enabledโ”‚  โ”œโ”€โ”€ Search.js                  # Helper functions for searching/ filtering items in all viewsโ”‚  โ”œโ”€โ”€ JsonToYaml.js              # Function that parses and converts raw JSON into valid YAMLโ”‚  โ”œโ”€โ”€ KeycloakAuth.js            # Singleton class to manage Keycloak authenticationโ”‚  โ”œโ”€โ”€ languages.js               # Handles fetching, switching and validating languagesโ”‚  โ•ฐโ”€โ”€ ThemeHelper.js             # Function that handles the fetching and setting of user themesโ•ฐโ”€โ”€ views                         # Directory of available pages, corresponding to available routes   โ”œโ”€โ”€ Home.vue                   # The home page container   โ”œโ”€โ”€ About.vue                  # About page   โ”œโ”€โ”€ Login.vue                  # TAuthentication page   โ”œโ”€โ”€ Minimal.vue                # The minimal view   โ•ฐโ”€โ”€ Workspace.vue              # The workspace view with apps in sidebar

Visualisation of Source Directory#

File Breakdown


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.

Dependencies - BundlePhobia#

BundlePhobia is a really useful app that lets you analyze the cost of adding any particular dependency to an application


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.