# Project pack: Dashy @ 93a33d9

Facts about **Dashy** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Dashy is a self-hosted start page for your home server and favourite links. You describe your sections, apps and widgets in a single YAML file or the built-in editor, then get a good-looking dashboard with status checks, search, themes, icons and many widgets. It has an extensive documentation and a large community.

## Version and source
- Repository: https://github.com/Lissy93/dashy
- Pinned commit: `93a33d945c8b84e5dd37c8bef103770d4701d175`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/Lissy93/dashy/archive/93a33d945c8b84e5dd37c8bef103770d4701d175.zip
- Official docs: https://dashy.to/docs
- Live demo: https://demo.dashy.to. Official demo dashboard.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/Lissy93/dashy bespoke-dashy
  cd bespoke-dashy
  git checkout --detach 93a33d945c8b84e5dd37c8bef103770d4701d175
  # Prepare development requirements and local configuration first.
  yarn install
  yarn dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name dashy -p 4000:8080 -v dashy-config:/app/user-data lissy93/dashy
  # then open http://localhost:4000
  ```

- Needs: Docker for a trial, Node 20 and Yarn for development
- Develop: `yarn dev`
- Test: `yarn test`
- Check/lint: `yarn lint`
- Build: `yarn build`
- Stack: javascript, vue (Vue, Vite, Node.js). Difficulty for a non-developer with an AI: **easy**. A Vue single-page app served by a small Node server. Almost all customisation is in conf.yml, themes and widgets.

## Customisation points (settings → extend → code)
- **sections-and-items** [settings]: Your apps and links, grouped your way. → `user-data/conf.yml (sections, items) or the built-in editor`
- **themes-and-layout** [settings]: Colours, fonts and layout. → `conf.yml appConfig.theme and the Theme picker`
- **widgets** [settings]: Weather, clocks, feeds, status and more. → `conf.yml widgets and docs/widgets.md`
- **status-checks** [settings]: Show whether each service is up. → `conf.yml statusCheck options`
- **custom-css** [extend]: Fine-tune the look. → `user-data/custom CSS in the config`
- **vue-components** [code]: New widgets and views. → `src/components`

## Must keep working
- Config file compatibility, since users hand-edit conf.yml.
- Authentication options in the config.
- Status check proxying, which must not open internal addresses to outsiders.

## Staying updatable
Prefer conf.yml and custom CSS. Keep new widgets in separate component files.

## Data, costs and safety
- Personal data: **no**. Stored in: A YAML file in the user-data folder. The config may list private service addresses. Keep it out of public repos.
- Service: Widget data sources (weather, RSS, stocks) (optional, mostly free): Content for the widgets.
- Setting `NODE_ENV`: Set to production in Docker. Already set in the official image.
- Enable authentication if the dashboard is reachable beyond your home network.
- Do not put secrets in conf.yml in a public repository.

---

# Customising Dashy

Dashy is mostly customised through conf.yml. The source is a Vue app.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Your configuration | user-data/conf.yml |
| Vue components and views | src/components/ and src/views/ |
| Themes and styles | src/styles/ and public/ |
| Server and API endpoints | server.js and services/ |
| Docs | docs/ |

## Use the gentlest change first

1. **Settings (no code):** sections, items, themes, widgets and status checks.
2. **Extend:** custom CSS and external widgets.
3. **Code:** Vue components.

## Recipes

- **Add a service:** add an item under a section in `conf.yml` with a title, URL and icon.
- **New theme:** add CSS variables in the styles folder and register the theme name.

## Running and checking your changes

- `yarn dev` and reload after each change.
- `yarn lint` and `yarn test`.
- Check the layout on a phone and tablet.

## Pitfalls

- YAML indentation errors break the page. Validate your file.
- Use the Docker user-data volume so your config survives upgrades.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/dashy/93a33d9/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/dashy/93a33d9/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/dashy/93a33d9/r2/SKILL.md)