Skip to content

Commit

Permalink
Updated all the docs from master
Browse files Browse the repository at this point in the history
  • Loading branch information
Lissy93 committed Jun 10, 2023
1 parent c827934 commit bb62cc7
Show file tree
Hide file tree
Showing 26 changed files with 2,875 additions and 1,124 deletions.
8 changes: 6 additions & 2 deletions docs/alternate-views.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,15 @@
## Views

Dashy has three different views:

- Default View - This is the main homepage with sections in a grid layout
- Workspace View - Items displayed on the side, and are launched within Dashy
- Minimal View - A clean + simple tabbed view

You can switch between views using the dropdown in the top-right corner. Set your chosen Starting View with `appConfig.startingView`. Click the page title at any time to go back to your selected starting view.

### Default

This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout.

<p align="center">
Expand All @@ -18,6 +20,7 @@ This is the main page that you will land on when you first launch the applicatio
</p>

### Workspace

The workspace view displays your links in a sidebar on the left-hand side, and apps are launched inside an iframe without having to leave Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy.

You can specify a default app to be opened when you land on the workspace, by setting `appConfig.workspaceLandingUrl: https://app-to-open/`. If this app exists within your sections.items, then the corresponding section will also be expanded.
Expand All @@ -30,6 +33,7 @@ You can also opt to keep previously opened websites/ apps open in the background
</p>

### Minimal View

The minimal view aims to be super fast and simple, and can be used as a browser startpage. Items are grouped into a tab view, and the last opened tab will be remembered. Similar to the main view, you can search and launch items just by typing, and right-clicking will show more options (like open in modal, workspace or new tab).

<p align="center">
Expand All @@ -49,12 +53,12 @@ Dashy supports several different ways to launch your apps. The primary opening m

You can also set a default opening method, which will be applied to all items that don't have a specified target, using `appConfig.defaultOpeningMethod`, to one of the above values.

Even if the target is not set (or is set to `sametab`), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab.
Even if the target is not set (or is set to `sametab`), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab.

<p align="center">
<img width="500" src="https://i.ibb.co/vmZdSRt/dashy-context-menu-2.png" />
</p>

If you don't like the custom context menu, it can be disabled by setting `appConfig.disableContextMenu: true`.

If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshooting#refused-to-connect-in-modal-or-workspace-view).
If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshootingrefused-to-connect-in-modal-or-workspace-view).
243 changes: 201 additions & 42 deletions docs/assets/CONTRIBUTORS.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/assets/repo-visualization.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
657 changes: 350 additions & 307 deletions docs/authentication.md

Large diffs are not rendered by default.

51 changes: 26 additions & 25 deletions docs/backup-restore.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
### Cloud Backup and Restore
# Cloud Backup and Restore

Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests.

Expand All @@ -8,43 +8,43 @@ This is useful not only for backing up your configuration off-site, but it also
<img src="https://i.ibb.co/p4pxSqX/dashy-backup-restore.png" width="600" />
</p>

### How it Works
## How it Works

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.

## Creating a Backup

### Creating a Backup
Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'.

### Restoring a Backup
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.
## Restoring a Backup

### Privacy & Security
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.

## Privacy & Security

Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password.

Because the data is encrypted on the client-side (before being sent to the cloud), it is not possible for a man-in-the-middle, government entity, website owner, or even Cloudflare to be able read any of your data. The biggest risk to your data, would be a weak password, or a compromised system.

Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind.


### Fair Use Policy
## Fair Use Policy

Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare.

---

### Self-Hosting the Backup Server
## Self-Hosting the Backup Server

### Quick Start

#### Quick Start
- Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler`
- Log into Cloudflare account: `wrangler login`
- Create a new project: ` wrangler generate my-project`
- Create a new project: `wrangler generate my-project`
- Install dependencies: `cd my-project` && `npm i`

### Populate `wrangler.toml`

#### Populate `wrangler.toml`
- Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard)
- Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare)
- Add your `route`, which should be a domain or host, supporting a wildcard
Expand All @@ -63,10 +63,11 @@ kv_namespaces = [
]
```

#### Complete `index.js`
### Complete `index.js`

- Write code to handle your requests, and interact with any other data sources in this file
- Generally, this is done within an event listener for 'fetch', and returns a promise
- For Example:
- For Example:

```javascript
addEventListener('fetch', event => {
Expand All @@ -82,28 +83,28 @@ async function handleRequest(request) {

- For the code used for Dashy's cloud service, see [here](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js)

### Commands

#### Commands
- `wrangler dev` - To start the wrangler development server
- `wrangler publish` - To publish to your cloudflare account (first run `wrangler login`)

### API
## API

There are four endpoints, and to keep things simple, they all use the same base URL/ route.

- **`GET`** - Get config for a given user
- `backupId` - The ID of the desired encrypted object
- `subHash` - The latter half of the password hash, to verify ownership
- `backupId` - The ID of the desired encrypted object
- `subHash` - The latter half of the password hash, to verify ownership
- **`POST`** - Save a new config object, and returns `backupId`
- `userData` - The encrypted, compressed and stringified user config
- `subHash` - The latter half of the password hash, to verify ownership
- `userData` - The encrypted, compressed and stringified user config
- `subHash` - The latter half of the password hash, to verify ownership
- **`PUT`** - Update an existing config object
- `backupId` - The ID of the object to update
- `subHash` - Part of the hash, to verify ownership of said object
- `userData` - The new data to store
- `backupId` - The ID of the object to update
- `subHash` - Part of the hash, to verify ownership of said object
- `userData` - The new data to store
- **`DELETE`** - Delete a specified config object
- `backupId` - The ID of the object to be deleted
- `subHash` - Part of the password hash, to verify ownership of the object
- `backupId` - The ID of the object to be deleted
- `subHash` - Part of the password hash, to verify ownership of the object

For more info, see the [API Docs](https://documenter.getpostman.com/view/2142819/TzXumzce).

Expand Down
Loading

0 comments on commit bb62cc7

Please sign in to comment.