Add documentation

.dockerignore

@@ -53,3 +53,5 @@
 **/*.sw?
 
 # Development components
+labs-docs-builder
+docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create an issue to inform of a bug
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Device Type:**
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/deploy-docs.yml

@@ -0,0 +1,24 @@
+name: "Deploy Docs"
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "docs/**"
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: "Deploy-Docs"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v3
+
+      - name: Build and deploy the docs
+        uses: "balena-io-experimental/labs-docs-builder@main"
+        with:
+          git_pass: ${{ secrets.github_token }}

.github/workflows/electron-test-build.yml

@@ -5,6 +5,8 @@ name: "Build Test Electron App"
 
 on:
   push:
+    paths-ignore:
+      - "docs/**"
 
 env:
   ELECTRON_OUTPUT_PATH: "ui/dist/electron/Packaged"

.gitignore

@@ -45,3 +45,4 @@ yarn-error.log*
 *.sln
 
 # Development components
+labs-docs-builder

README.md

@@ -1,45 +1,43 @@
 # Balena Starter Interface
 
-This project is still under heavy development and subject to significant changes. Apologies if the documentation is out of date in places, we are moving quickly and will try and keep up as best as possible.
+A community-built device interface for using balena devices. It can be used to interact with your device, or as a starter project to create your own interface.
 
----
+_On-device Interface_
 
-A community-built device interface for using Balena devices. It can be used to interact with your device, or as a starter project to create your own interface.
+<img src="https://user-images.githubusercontent.com/64841595/191008762-ea97f42c-a7bb-4ecb-abe8-5d57874da9b3.png" alt="wifi" width="500"/>
 
-[![balena deploy button](https://www.balena.io/deploy.svg)](https://dashboard.balena-cloud.com/deploy?repoUrl=https://github.com/balena-labs-research/starter-interface)
+This project contains the ability to build:
 
-# Description
+- An ExpressJS web application framework providing a Quasar (Vue) interface to users
+- An Electron Application for communicating with devices on your network
+- A Progressive Web App alternative.
 
-This project contains an ExpressJS web application framework which provides a Quasar (Vue) interface to users. It also includes an optional Wi-Fi connect component allowing users to connect devices to nearby networks.
+_Electron App_
 
-It is modular allowing contributions from the community and ease of tracking of changes in your own projects.
+<img width="500" alt="electron" src="https://user-images.githubusercontent.com/64841595/213165616-73bc762b-0073-4407-a10d-52c8daa21333.png"/>
 
-Some of the features include:
+Some of the core features include:
 
 - Online and offline use
+- Customisable Electron and Progressive Web applications for interaction with your devices
 - Pre-built endpoints for interacting with the Balena SDK or Supervisor
-- Connect the device to nearby Wi-Fi networks
+- Connect your device to nearby Wi-Fi networks
 - Container manager (list, stop, start, restart)
 - File manager (create folders, upload, delete, etc...)
 - Set, edit and remove environment variables on the device
 - Configure the device hostname
 - Configure the device SSID and password
 - Captive portal
+- Automatic mounting of USB devices into the File Manager
 - System info and stats
 - I18n language translations
 
-# Screenshots
-
-<b>User friendly dashboard:</b>
-
-![demo](https://user-images.githubusercontent.com/64841595/191008762-ea97f42c-a7bb-4ecb-abe8-5d57874da9b3.png)
-
-<b>Connect to nearby Wi-Fi networks:</b>
-
-<img width="569" alt="141763447-534ddcd6-5939-4f14-970e-ccf8b7a106c6" src="https://user-images.githubusercontent.com/64841595/157092424-561961e5-6914-4e42-955f-fe8a02e9c370.png">
+These components are optional, and easily removed or edited. The project also includes the ability to add your own components, branding and anything else you desire to get started with building a user interface for your balena devices.
 
 # Documentation
 
-Use of the UI and technical details can be found on the [wiki](https://github.com/balena-labs-research/starter-interface/wiki).
+Use of the UI and technical details can be found in the [documentation](https://balena-labs-research.github.io/starter-interface).
+
+# One-click deploy
 
-The [Getting Started](https://github.com/balena-labs-research/starter-interface/wiki/Getting-Started) guide is a good place to start.
+[![balena deploy button](https://balena.io/deploy.svg)](https://hub.balena.io/organizations/bdi/apps/starter-interface)

docs/00-Introduction.md

@@ -0,0 +1,45 @@
+---
+slug: /
+breadcrumbs: true
+title: Introduction
+---
+
+# Balena Starter Interface
+
+A community-built device interface for using balena devices. It can be used to interact with your device, or as a starter project to create your own interface.
+
+_On-device Interface_
+
+<img src="https://user-images.githubusercontent.com/64841595/191008762-ea97f42c-a7bb-4ecb-abe8-5d57874da9b3.png" alt="wifi" width="500"/>
+
+This project contains the ability to build:
+
+- An ExpressJS web application framework providing a Quasar (Vue) interface to users
+- An Electron Application for communicating with devices on your network
+- A Progressive Web App alternative.
+
+_Electron App_
+
+<img width="500" alt="electron" src="https://user-images.githubusercontent.com/64841595/213165616-73bc762b-0073-4407-a10d-52c8daa21333.png"/>
+
+Some of the core features include:
+
+- Online and offline use
+- Customisable Electron and Progressive Web applications for interaction with your devices
+- Pre-built endpoints for interacting with the Balena SDK or Supervisor
+- Connect your device to nearby Wi-Fi networks
+- Container manager (list, stop, start, restart)
+- File manager (create folders, upload, delete, etc...)
+- Set, edit and remove environment variables on the device
+- Configure the device hostname
+- Configure the device SSID and password
+- Captive portal
+- Automatic mounting of USB devices into the File Manager
+- System info and stats
+- I18n language translations
+
+These components are optional, and easily removed or edited. The project also includes the ability to add your own components, branding and anything else you desire to get started with building a user interface for your balena devices.
+
+# One-click deploy
+
+[![balena deploy button](https://balena.io/deploy.svg)](https://hub.balena.io/organizations/bdi/apps/starter-interface)

docs/01-Developing Locally.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 1
+---
+
+## Requisites
+
+- Node ^18
+- Yarn Classic
+
+## Install the dependencies
+
+```bash
+yarn
+```
+
+### Development modes
+
+#### SPA (Single Page Application)
+
+```bash
+yarn dev
+```
+
+#### Electron
+
+```bash
+yarn dev-electron
+```
+
+#### PWA (Progressive Web App)
+
+```bash
+yarn dev-pwa
+```
+
+### Build the app for production
+
+#### SPA (Single Page Application)
+
+```bash
+yarn build
+```
+
+#### Electron
+
+```bash
+yarn build-electron
+```
+
+#### PWA (Progressive Web App)
+
+```bash
+yarn build-pwa
+```
+
+### Linting and formatting
+
+#### Lint the code
+
+```bash
+yarn lint
+```
+
+#### User [Prettier](https://prettier.io) to format the code
+
+```bash
+yarn format
+```

docs/02-Continuous Integration.md

@@ -0,0 +1,63 @@
+## GitHub Workflows
+
+GitHub workflow files can be found in `.github/workflows` and are triggered automatically based on their configuration.
+
+Secrets are required in your GitHub repository for the workflows.
+
+### Required GitHub Secrets
+
+#### Balena secrets:
+
+A balenaCloud API token with access to the application. Refer to the docs [here](https://github.com/balena-community/community-cli-action) for more info.
+
+`BALENA_TOKEN`
+
+#### Apple and Windows signing secrets:
+
+More information on how to generate these can be found [here](https://gist.github.com/maggie0002/a689fc01737f6a5fd72868f0f07e3d3e).
+
+_Apple:_
+
+```
+BUILD_CERTIFICATE_BASE64
+BUILD_PROVISION_PROFILE_BASE64
+KEYCHAIN_PASSWORD
+P12_PASSWORD
+XCODE_APP_LOADER_EMAIL
+XCODE_APP_LOADER_PASSWORD
+```
+
+_Windows:_
+
+```
+CSC_LINK
+CSC_KEY_PASSWORD
+```
+
+### Test Builds and Deploys
+
+`deploy-testing.yml` triggers when a pull request is raised against the branch `main`. It deploys the code to the fleets specified in the file. It is recommended to use the same fleet names (i.e. `bdi-rpi`) as code deployed to these fleet names for testing will automatically provide verbose logging for debugging.
+
+`electron-test-build.yml` builds the Electron apps on each pull request and attaches them as assets to the workflow action found in the `Actions` tab of the repository.
+
+They will not be signed, and the Mac ARM app will not work as unsigned apps for that platform will not open your system. It is kept to test the build process. To test the app on Mac ARM, you will need to build it locally.
+
+### Production Builds and Deploys
+
+`deploy-production.yml` triggers when [a tag is pushed](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-commits/managing-tags) and performs the following functions:
+
+1. Updates the balena Hub README to match the GitHub README.
+2. Deploys the code to the production fleet specified in the file.
+3. Preloads the specified balenaOS images with the application.
+4. Builds and signs the Electron app for Linux, Windows, Mac AMD64 and ARM.
+5. Signs the Mac and Windows apps with the Apple Developer and Microsoft Developer certificates.
+6. Deploys the app as Docker images to GitHub container registry.
+7. Creates a release on GitHub with the images and Electron apps attached.
+
+### Linting and Code Security
+
+`codeql-analysis.yml` and `eslint.yml` are triggered on each pull request and merge. They perform code security and linting checks. Ensure `node-version: "x.x.x"` matches the version in your Dockerfiles to ensure it lints with the correct version.
+
+### Documentation
+
+`deploy-docs.yml` is used to build and deploy the documentation you are viewing. It is also free to use for your own projects by editing the documentation in the `./docs` folder. More info including how to use hot-reload can be found in the documentation for the docs project [here](https://github.com/balena-io-experimental/labs-docs-builder).

docs/Built-in components/Backend Endpoints.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 2
+---
+
+A backend for performing functions on the device is included. This is used to interact with the Balena Supervisor, SDK and other endpoints. You can however, also add your own backend endpoints to interact with other peripherals or software. An example can be found in `expressjs/src/routes/v1/Examples.ts`

docs/Built-in components/Cache Timeouts and Queuing.md

@@ -0,0 +1,41 @@
+In the ExpressJS backend there is middleware available for caching and queueing requests. This prevents unnecessary calls to the Supervisor or SDK and also prevents multiple requests to the same endpoint from being made at the same time to speed up responses and reduce traffic. It follows a number of general rules:
+
+1. Each endpoint has its own queue. For example, a request to `/ping` will not wait for a request from `/v1/device`, it will only wait for other requests to finish on `/ping`.
+2. When two requests are made on the same endpoint - and the middleware is applied to the endpoints - it will wait for the first response to return before the second is executed.
+3. If caching is enabled on the endpoint and the last request was returned in less than the passed timeout integer it will return the cached content on the second request, instead of making a new request.
+4. Caching can only be enabled for endpoints with the `type: 'GET'` parameter passed or those requested as an Axios `GET` request. Caching `POST` or `PATCH` requests would defeat the object of requesting a change on the device if it was cached.
+
+To use the middleware, include it in your route as follows:
+
+```typescript
+router.post('/v1/filemanager/delete', queueCache, (async (req: Request, res: Response) => {
+...
+}) as RequestHandler)
+```
+
+Configure the endpoints as follows, which will return the response from the cache if the last response was returned in less than the number of milliseconds specified in `cacheTimeout`:
+
+```typescript
+device_name() {
+  return expressApi.post(apiPath + supervisorPath, {
+    type: 'GET',
+    path: 'v2/device/name',
+    params: false,
+    cacheTimeout: 5000
+  })
+},
+```
+
+## Examples
+
+Using default cache expiry set in `expressjs/src/index.js`:
+
+```typescript
+cacheTimeout: 0;
+```
+
+Return previously fetched content if less than 2 seconds old:
+
+```typescript
+cacheTimeout: 2000;
+```