### Running Dashy from Source

Source: https://github.com/lissy93/dashy/wiki/quick-start

These commands show how to clone the Dashy repository, install dependencies, build the application, and start it. Configuration is done by editing the `./user-data/conf.yml` file.

```bash
git clone https://github.com/Lissy93/dashy.git && cd dashy
yarn # Install dependencies
yarn build # Build the app
yarn start # Start the app
```

--------------------------------

### Example Dashy Configuration

Source: https://github.com/lissy93/dashy/wiki/configuring

A comprehensive example of a Dashy configuration file in YAML format, demonstrating sections and items.

```yaml
---
pageInfo:
  title: Home Lab
sections: # An array of sections
- name: Section 1 - Getting Started
  items: # An array of items
  - title: GitHub
    description: Source code and documentation on GitHub
    icon: fab fa-github
    url: https://github.com/Lissy93/dashy
  - title: Issues
    description: View currently open issues, or raise a new one
    icon: fas fa-bug
    url: https://github.com/Lissy93/dashy/issues
  - title: Demo
    description: A live demo
    icon: far fa-rocket
    url: https://dashy-demo-1.netlify.app
- name: Section 2 - Local Services
  items:
  - title: Firewall
    icon: favicon
    url: http://192.168.1.1/
  - title: Game Server
    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
    url: http://192.168.130.1/

```

--------------------------------

### Clone and Install Dashy Dependencies

Source: https://github.com/lissy93/dashy/blob/master/README.md

Clone the Dashy repository and install its dependencies using Yarn. This is the initial setup step for development.

```bash
git clone https://github.com/Lissy93/dashy.git
cd dashy
yarn
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/lissy93/dashy/wiki/developing

Builds the application for production and then starts the Node.js server. This is a manual way to run a production-style instance on bare metal.

```bash
yarn build && yarn start
```

--------------------------------

### Build and Start Dashy Production App

Source: https://github.com/lissy93/dashy/blob/master/README.md

Build the production-ready version of Dashy and then start the application. These commands are used after development is complete.

```bash
yarn build
yarn start
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/lissy93/dashy/wiki/developing

Install all the necessary project dependencies using Yarn. If using NPM, replace 'yarn' with 'npm install'.

```bash
yarn
```

--------------------------------

### Start Production Server

Source: https://github.com/lissy93/dashy/wiki/developing

Starts the Node.js server to serve the built site from './dist' and the live configuration from 'user-data/'. Ensure 'yarn build' is run first.

```bash
yarn start
```

--------------------------------

### Quick Start Dashy with Docker

Source: https://github.com/lissy93/dashy/wiki/deployment

Run a Dashy instance quickly using Docker. This command starts a container and maps port 8080.

```bash
docker run -p 8080:8080 lissy93/dashy
```

--------------------------------

### Start Development Server

Source: https://github.com/lissy93/dashy/wiki/developing

Start the development server with hot reloading enabled. Changes to files will trigger automatic rebuilds and page refreshes.

```bash
yarn dev
```

--------------------------------

### Basic Dashy Configuration Example

Source: https://github.com/lissy93/dashy/wiki/quick-start

This is a minimal example of a Dashy configuration file. It sets the dashboard title and defines two sections with various items.

```yaml
pageInfo:
  title: Home Lab
sections: # An array of sections
- name: Example Section
  icon: far fa-rocket
  items:
  - title: GitHub
    description: Dashy source code and docs
    icon: fab fa-github
    url: https://github.com/Lissy93/dashy
  - title: Issues
    description: View open issues, or raise a new one
    icon: fas fa-bug
    url: https://github.com/Lissy93/dashy/issues
- name: Local Services
  items:
  - title: Firewall
    icon: favicon
    url: http://192.168.1.1/
  - title: Game Server
    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
    url: http://192.168.130.1/
```

--------------------------------

### Tailscale Serve Configuration Example

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/tailscale.md

Example configuration for Tailscale's 'serve' command, which handles HTTPS and authentication for Dashy. Ensure the hostname matches your Tailscale domain or is hardcoded if using older images.

```json
{
  "cert-domain": "dashy.tail123abc.ts.net",
  "auth-key": "tskey-auth-xxxxxxxxxxxxxxxxxxxxxx",
  "users": [
    {
      "type": "admin",
      "user": "your-email@example.com"
    }
  ]
}
```

--------------------------------

### Install Dependencies and Build Dashy

Source: https://github.com/lissy93/dashy/blob/master/README.md

Commands to install project dependencies using yarn and build the application for production.

```bash
yarn
yarn build
```

--------------------------------

### Install Dashy Sandbox App with Saltbox

Source: https://github.com/lissy93/dashy/wiki/deployment

Use this command to install Dashy as a sandbox application within a Saltbox environment.

```bash
sb install sandbox-dashy
```

--------------------------------

### Run Remote.it Installer Script

Source: https://github.com/lissy93/dashy/wiki/management

Execute the Remote.it auto-install script with sudo privileges. This command installs the necessary components for the Remote.it service on your device.

```bash
sudo ./auto-install.sh
```

--------------------------------

### Reset Pocket ID Data Directory

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/pocketid.md

If the first admin user cannot sign in and no setup page appears, it may be due to existing user data. Wipe the 'data/' directory and restart the containers to start fresh. You may need sudo or a throwaway container to clean up the directory if it's owned by the container user.

```bash
docker compose down && rm -rf data && docker compose up -d
```

--------------------------------

### Glances Docker Installation

Source: https://github.com/lissy93/dashy/wiki/widgets

Example command to run Glances using Docker. Ensure the TZ environment variable is set correctly for accurate time display in graphs.

```bash
docker run -d \
    --name glances \
    --restart unless-stopped \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -p 61208:61208 \
    --pid host \
    --privileged \
    -e GLANCES_OPT=-w \
    -e PUID=1000 \
    -e PGID=1000 \
    -e TZ=Europe/Zurich \
    nicolargo/glances:latest
```

--------------------------------

### WireGuard Server Configuration Example

Source: https://github.com/lissy93/dashy/wiki/management

This is an example of a WireGuard server configuration file (wg0.conf). It defines the server's interface, private key, listening port, and peer configurations including public keys and allowed IP addresses for clients.

```ini
# Server file
[Interface]
# Which networks does my interface belong to? Notice: /24 and /64
Address = 10.5.0.1/24, 2001:470:xxxx:xxxx::1/64
PrivateKey = xxx
ListenPort = 51820

# Peer 1
[Peer]
PublicKey = xxx
# Which source IPs can I expect from that peer? Notice: /32 and /128
AllowedIps = 10.5.0.35/32, 2001:470:xxxx:xxxx::746f:786f/128

# Peer 2
[Peer]
PublicKey = xxx
# Which source IPs can I expect from that peer? This one has a LAN which can
# access hosts/jails without NAT.
# Peer 2 has a single IP address inside the VPN: it's 10.5.0.25/32
AllowedIps = 10.5.0.25/32,10.21.10.0/24,10.21.20.0/24,10.21.30.0/24,10.31.0.0/24,2001:470:xxxx:xxxx::ca:571e/128

```

--------------------------------

### Start Dashy with Dynamic User

Source: https://github.com/lissy93/dashy/blob/master/docs/management.md

Set the CURRENT_UID environment variable to the current user's ID and group ID, then start the Docker Compose services.

```bash
CURRENT_UID=$(id -u):$(id -g) docker-compose up
```

--------------------------------

### Start Node Server with PM2

Source: https://github.com/lissy93/dashy/wiki/developing

Starts the Node.js server using PM2, a process manager that helps keep applications running. Recommended for bare metal deployments.

```bash
yarn pm2-start
```

--------------------------------

### Deploy Dashy to Netlify

Source: https://github.com/lissy93/dashy/wiki/deployment

One-click deployment link for Dashy on Netlify. Utilizes the provided netlify.toml for automatic setup.

```bash
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
```

--------------------------------

### WireGuard Client Configuration Example

Source: https://github.com/lissy93/dashy/wiki/management

This is an example of a WireGuard client configuration file. It specifies the client's interface address, private key, the server's public key and endpoint, and defines which IP addresses should be routed through the VPN. PersistentKeepalive is used to maintain the connection.

```ini
[Interface]
# Which networks does my interface belong to? Notice: /24 and /64
Address = 10.5.0.35/24, 2001:470:xxxx:xxxx::746f:786f/64
PrivateKey = xxx

# Server
[Peer]
PublicKey = xxx
# I want to route everything through the server, both IPv4 and IPv6. All IPs are
# thus available through the Server, and I can expect packets from any IP to
# come from that peer.
AllowedIPs = 0.0.0.0/0, ::0/0
# Where is the server on the internet? This is a public address. The port
# (:51820) is the same as ListenPort in the [Interface] of the Server file above
Endpoint = 1.2.3.4:51820
# Usually, clients are behind NAT. to keep the connection running, keep alive.
PersistentKeepalive = 15

```

--------------------------------

### Configure Remote.it Device

Source: https://github.com/lissy93/dashy/wiki/management

Run the connectd_installer command with sudo to configure your device for Remote.it. Follow the on-screen prompts to complete the setup.

```bash
sudo connectd_installer
```

--------------------------------

### Weather Widget Configuration

Source: https://github.com/lissy93/dashy/wiki/widgets

Example of how to configure the Weather widget, including API key, city, units, and detail visibility.

```yaml
- type: weather
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    city: London
    units: metric
    hideDetails: true
```

--------------------------------

### Clock Widget Configuration

Source: https://github.com/lissy93/dashy/wiki/widgets

Example of how to configure the Clock widget with specific time zone, format, and date visibility settings.

```yaml
- type: clock
  options:
    timeZone: Europe/London
    format: en-GB
    hideDate: false
```

--------------------------------

### Start Docker Compose

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/cloudflare-tunnel.md

Command to bring up the services defined in the `docker-compose.yml` file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Run Dashy with Docker

Source: https://github.com/lissy93/dashy/blob/master/README.md

Basic command to run Dashy using Docker. Ensure Docker is installed.

```bash
docker run -p 4000:8080 lissy93/dashy
```

--------------------------------

### Section Layout Configuration Example

Source: https://github.com/lissy93/dashy/wiki/pages-and-sections

Demonstrates how to configure a section's footprint using 'displayData.cols' and 'displayData.rows'. The 'rows' property is honored by the 'auto' layout.

```yaml
- name: Important Links
  displayData:
    cols: 2
    rows: 2
    collapsed: false
  items: [...]
```

--------------------------------

### Basic Example: Search Bar Translations (JSON)

Source: https://github.com/lissy93/dashy/wiki/multi-language-support

JSON object containing the English translations for the search bar label and placeholder.

```json
{
"search": {
    "search-label": "Search",
    "search-placeholder": "Start typing to filter",
  },
  ...
}
```

--------------------------------

### Emoji Icon Examples

Source: https://github.com/lissy93/dashy/wiki/icons

Demonstrates using emojis as icons via direct pasting, Unicode, or shortcodes. These methods all render the same emoji.

```yaml
icon: ':rocket:'
```

```yaml
icon: 'U+1F680'
```

```yaml
icon: 🚀
```

--------------------------------

### Make Installer Script Executable

Source: https://github.com/lissy93/dashy/wiki/management

Change the permissions of the downloaded auto-install script to make it executable. This is a necessary step before running the script.

```bash
chmod +x ./auto-install.sh
```

--------------------------------

### Insert Admin User via SQLite and Get One-Time Token

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/pocketid.md

Use this command to insert an initial admin user into Pocket ID's SQLite database and generate a one-time access token for initial login. This is useful if passkey registration is difficult during setup.

```bash
docker compose exec pocket-id sh -c '
  apk add --no-cache sqlite >/dev/null 2>&1
  sqlite3 /data/pocket-id.db "
    INSERT INTO users (id, created_at, updated_at, username, email, first_name, last_name, display_name, is_admin, email_verified)
    VALUES ("admin-uuid-001", datetime("now"), datetime("now"), "pocketid-admin", "admin@example.com", "Pocket ID", "Admin", "Admin", 1, 1);
  "
'

docker compose exec pocket-id /app/pocket-id one-time-access-token pocketid-admin
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/lissy93/dashy/blob/master/docs/backup-restore.md

Installs the Node.js dependencies for the Cloudflare Worker project. This should be run after generating the project.

```bash
cd my-project && npm i
```

--------------------------------

### Item Configuration with Hotkey and Tags

Source: https://github.com/lissy93/dashy/blob/master/README.md

Example of configuring an item with a hotkey for quick launch and tags for easier searching. The 'hotkey' attribute allows direct launching with a numeric key.

```yaml
items:
  - title: Plex
    hotkey: 8
    icon: favicon
    description: Media library
    url: https://plex.lab.local
    tags: [ movies, videos, music ]
```

--------------------------------

### Build and Run Dashy from Source

Source: https://github.com/lissy93/dashy/wiki/deployment

Steps to clone the Dashy repository, install dependencies, build the project, and run it directly on your host system. Requires Node.js and optionally Yarn.

```bash
git clone https://github.com/Lissy93/dashy.git
cd dashy
yarn
yarn build
yarn start
```

--------------------------------

### Yarn Installation Steps (Debian)

Source: https://github.com/lissy93/dashy/wiki/troubleshooting

Commands to uninstall an incorrect Yarn version and install the correct one on Debian-based systems.

```bash
sudo apt remove yarn
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
```

--------------------------------

### Install Wrangler CLI Tool

Source: https://github.com/lissy93/dashy/blob/master/docs/backup-restore.md

Installs the Cloudflare Wrangler CLI tool globally. This is required for managing Cloudflare Workers.

```bash
npm i -g @cloudflare/wrangler
```

--------------------------------

### Build and Run Dashy with NPM

Source: https://github.com/lissy93/dashy/wiki/troubleshooting

Alternative build and run commands using NPM instead of Yarn.

```bash
npm install
npm run build
npm start
```

--------------------------------

### Install Docker Login Dependencies on Ubuntu

Source: https://github.com/lissy93/dashy/wiki/troubleshooting

If Docker login fails on Ubuntu, install the necessary dependencies using apt and gpg2.

```bash
sudo apt install gnupg2 pass && gpg2 -k
```

--------------------------------

### Build and Run Dashy with Docker

Source: https://github.com/lissy93/dashy/wiki/troubleshooting

Commands to build and run the Dashy Docker image.

```bash
docker build -t lissy93/dashy .
docker run -it -p 8080:8080 lissy93/dashy
```

--------------------------------

### Basic Example: Search Bar Translations (Vue Template)

Source: https://github.com/lissy93/dashy/wiki/multi-language-support

Example of using the $t function to bind translated strings to a label and placeholder in a Vue template.

```vue
<template>
  <form>
    <label for="search-input">{{ $t('search.search-label') }}</label>
    <input
      v-model="searchValue"
      :placeholder="$t('search.search-placeholder')"
    />
  </form>
</template>
```

--------------------------------

### Apache Basic Auth Configuration

Source: https://github.com/lissy93/dashy/wiki/authentication

Set up Apache for HTTP basic authentication with Dashy. Ensure the `.htpasswd` file is correctly specified and generated.

```apache
AuthType Basic
AuthName "Dashy"
AuthUserFile /path/to/.htpasswd
Require valid-user
```

--------------------------------

### Basic Widget Usage in Sections

Source: https://github.com/lissy93/dashy/wiki/widgets

Demonstrates how to add widgets like clock and weather to a section in the YAML configuration file.

```yaml
sections:
- name: Today
  icon: far fa-calendar-day
  widgets:
  - type: clock
    options:
      format: en-GB
  - type: weather
    options:
      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      city: London
      units: metric
```

--------------------------------

### Building Dashy with Docker

Source: https://github.com/lissy93/dashy/blob/master/docs/troubleshooting.md

To build the Dashy Docker image, navigate to the project directory and run the `docker build` command. This command creates an image tagged `lissy93/dashy`.

```bash
docker build -t lissy93/dashy .
```

--------------------------------

### GET /config

Source: https://github.com/lissy93/dashy/wiki/backup-restore

Retrieves the configuration for a given user. Requires the backup ID and a sub-hash for ownership verification.

```APIDOC
## GET /config

### Description
Retrieves the configuration for a given user.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **backupId** (string) - Required - The ID of the desired encrypted object.
- **subHash** (string) - Required - The latter half of the password hash, to verify ownership.
```

--------------------------------

### Pull Specific Dashy Version

Source: https://github.com/lissy93/dashy/blob/master/docs/deployment.md

Download a specific version of the Dashy Docker image, for example, version 4.0.0.

```bash
docker pull lissy93/dashy:4.0.0
```

--------------------------------

### Section with Sub-Items Group

Source: https://github.com/lissy93/dashy/blob/master/docs/pages-and-sections.md

Example of a section containing grouped sub-items, including an optional title and icon for the group.

```yaml
- name: Coding
  icon: far fa-code
  items:
  - title: Normal Item 1
  - title: Normal Item 2
  - title: Languages
    subItems:
    - title: JavaScript
      url: https://developer.mozilla.org
      icon: si-javascript
    - title: TypeScript
      url: https://www.typescript.org/docs
      icon: si-typescript
    - title: Svelte
      url: https://svelte.dev/docs
      icon: si-svelte
    - title: Go
      url: https://go.dev/doc
      icon: si-go
```

--------------------------------

### Project File Structure

Source: https://github.com/lissy93/dashy/wiki/developing

Overview of the main files and directories in the project root. Useful for understanding the project layout.

```text
╮
├── 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
├── vite.config.mjs     # Vite (build tool) 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             # License for use
╯
```

--------------------------------

### Generate SHA-256 Password Hash

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/built-in.md

Example command to generate a SHA-256 hash for a password, which can be used in the conf.yml file.

```bash
echo -n "my-super-secure-password" | sha256sum
```

--------------------------------

### Serve Configuration File

Source: https://github.com/lissy93/dashy/blob/master/docs/authentication/authentik.md

Handles serving the configuration file, setting appropriate cache headers and potentially returning a bootstrapped configuration for unauthenticated users. It ensures private caching and no-store directives when authentication is active.

```javascript
app.get('/*.yml', protectConfig, (req, res, next) => {
  // Set Cache-Control for private, no-store when auth is configured
  if (this.oidcSettings) {
    res.set({
      'Cache-Control': 'private, no-store',
      'Vary': 'Authorization'
    });
  }

  // Call maybeBootstrapConfig to handle unauthenticated requests
  this.maybeBootstrapConfig(req, res, () => {
    // Serve the full file if not bootstrapped
    res.sendFile(path.join(__dirname, '../public/conf.yml'));
  });
});

```

--------------------------------

### Build Production Bundle

Source: https://github.com/lissy93/dashy/wiki/developing

Builds the production-ready bundle of the application into the './dist' directory. This command is typically used when preparing for deployment.

```bash
yarn build
```

--------------------------------

### RSS Feed Widget Configuration

Source: https://github.com/lissy93/dashy/wiki/widgets

Example configuration for displaying live data from an RSS-enabled service. Requires the `rssUrl` parameter.

```yaml
- type: rss-feed
  options:
    rssUrl: https://notes.aliciasykes.com/feed
```

--------------------------------

### Download Remote.it Installer Script

Source: https://github.com/lissy93/dashy/wiki/management

Use curl to download the auto-install script for Remote.it from their GitHub repository. This script is used to set up the Remote.it service on your local device.

```bash
curl -LkO https://raw.githubusercontent.com/remoteit/installer/master/scripts/auto-install.sh
```

--------------------------------

### IP Blacklist Widget Example

Source: https://github.com/lissy93/dashy/wiki/widgets

Checks an IP address against various blacklists using data from blacklistchecker.com. Requires an API key.

```yaml
- type: blacklist-check
  options:
    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ipAddress: 1.1.1.1
```

--------------------------------

### Configure Docker Auto-Start

Source: https://github.com/lissy93/dashy/wiki/management

Use Docker's restart policies to ensure the container automatically starts after a system reboot or crash. Add the `--restart=always` flag to your Docker run command or compose script.

```bash
docker run --restart=always [params] lissy93/dashy
```