Skip to content

Latest commit

 

History

History
299 lines (242 loc) · 8.02 KB

README.md

File metadata and controls

299 lines (242 loc) · 8.02 KB
Raw

Plugsy

Plugsy Logo

A simple dashboard used to show the status of various connected pieces of software.

The video below showcases a single docker socket connection (But it does much more than docker!)

Plugsy.mov

Why?

To display a simple status and list of all of my docker containers. I've been toying with making myself a proper home dashboard and I think think this is a good start.

I also wanted to play with GraphQL subscriptions and observables

And this has since grown into something that can give an up to date status on various different connectors.

Features

  • Links for every item on the dashboard!
  • Entirely customisable and themeable
    • Dark mode capable, Dracula example in theming doc
    • See theming
  • Websocket connections for speedy updates
  • Any icon supported in react-icons see icons
  • Show children items on your dashboard- Will also show the status of children containers
    • Got a docker container that relies on a website being available? Why not show both!?
    • See children
  • Docker
    • List all the containers with the given label
    • Display the status of the containers
  • Websites
    • Show the status and connectivity of a given website along with a link
    • Variable update interval
  • Raw
    • Have some links that don't have any status attached?
    • Use the included file configuration and show any ol' link that you'd like.
  • Agent Mode (New in V3): Use multiple plugsy containers to gather local states and push to a different instance to aggregate the statuses
    • Particularly useful if you have docker instances hosted on different machines or behind firewalls etc
    • See Agent Mode

Usage

Simplest usage using only a docker socket

docker-compose.yml:

version: "2.1"
services:
  plugsy:
    image: plugsy/core
    container_name: plugsy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 3000:3000
    restart: unless-stopped

  vikunjadb:
    image: mariadb:10
    labels:
      plugsy.name: "DB"
      plugsy.parents: "Todo"
      plugsy.icon: "@styled-icons/feather/Database"
    container_name: vikunjadb
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    restart: unless-stopped

  vikunjaapi:
    container_name: vikunjaapi
    image: vikunja/api
    restart: unless-stopped
    labels:
      plugsy.name: "API"
      plugsy.parents: "Todo"
      plugsy.icon: "@styled-icons/feather/Server"

  vikunjafrontend:
    image: vikunja/frontend
    container_name: vikunjafrontend
    restart: unless-stopped
    labels:
      plugsy.name: "Todo"
      plugsy.category: "Home"
      plugsy.icon: "@styled-icons/fa-solid/Horse"
      plugsy.link: https://my.vikunja.com

Configuration

There is now a configuration file that can be optionally added in order to include various connectors (Such as website connections or other arbitrary links). See connectors

This file should be mounted at /config.json in the container.

Note: Including the $schema field in the JSON file will help with auto complete in your preferred IDE.

config.json

{
  "$schema": "https://github.com/plugsy/core/releases/download/v7.0.0/core-config-schema.json",
  "connectors": [
    {
      "type": "DOCKER",
      "config": {}
    },
    {
      "type": "RAW",
      "config": {
        "id": "file",
        "items": [
          {
            "category": "Other",
            "name": "Beer Tab",
            "state": "GREEN",
            "icon": "@svg-icons/boxicons-regular/Beer"
          },
          {
            "name": "Beer Tab Dependency",
            "state": "GREEN",
            "icon": "@svg-icons/ionicons-solid/Beer",
            "parents": ["Beer Tab"]
          }
        ]
      }
    }
  ]
}

docker-compose.yml:

version: "2.1"
services:
  plugsy:
    image: plugsy/core
    container_name: plugsy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config.json:/config.json
    ports:
      - 3000:3000
    restart: unless-stopped

Icons

NEW IN V6

We've moved to styled-icons (In particular the svg-icons packages)

You can use any icons available in styled-icons. Super simple, go to the page above, click the icon you would like to use, and use it in your config or docker labels.

Example using docker labels: plugsy.icon: '@svg-icons/simple-icons/Plex' is to load the Plex icon in the simple-icons pack plugsy.icon: '@svg-icons/simple-icons/Homeassistant' is to load the Homeassistant icon in the simple-icons pack

Example using config.json:

"connectors": [
    {
      "type": "DOCKER",
      "config": {
        "containerMap": {
          "plugsy-container-name": {
            "category": "Home",
            "icon": "@svg-icons/boxicons-regular/Crown",
            "name": "Plugsy"
          }
        }
      }
    }
  ]
}
Icons using a URL

** NEW IN V6 **

You can now use icons using a URL!

Example using docker labels: plugsy.icon: 'https://symbols.getvecta.com/stencil_82/45_google-icon.d8d982f8a1.png'

Example using config.json:

"connectors": [
    {
      "type": "DOCKER",
      "config": {
        "containerMap": {
          "plugsy-container-name": {
            "category": "Home",
            "icon": "https://symbols.getvecta.com/stencil_82/45_google-icon.d8d982f8a1.png",
            "name": "Plugsy"
          }
        }
      }
    }
  ]
}

Children

In order to show dependent containers, you need only ensure that the item you wish to show has a parents label pointing at the same name as another item.

Example using the raw connector:

{
  "$schema": "https://github.com/plugsy/core/releases/download/v7.0.0/core-config-schema.json",
  "connectors": [
    {
      "type": "DOCKER",
      "config": {}
    },
    {
      "type": "RAW",
      "config": {
        "id": "file",
        "items": [
          {
            "category": "Other",
            "name": "Beer Tab",
            "state": "GREEN",
            "icon": "@svg-icons/boxicons-regular/Beer"
          },
          {
            "name": "Beer Tab Dependency",
            "state": "GREEN",
            "icon": "@svg-icons/ionicons-solid/Beer",
            "parents": ["Beer Tab"]
          }
        ]
      }
    }
  ]
}

An example of the same logic being applied using the docker connector docker-compose.yml can be shown below:

vikunjaapi:
  container_name: vikunjaapi
  image: vikunja/api
  restart: unless-stopped
  labels:
    plugsy.name: "API"
    plugsy.parents: "Todo"
    plugsy.icon: "@styled-icons/feather/Server"

vikunjafrontend:
  image: vikunja/frontend
  container_name: vikunjafrontend
  restart: unless-stopped
  labels:
    plugsy.name: "Todo"
    plugsy.category: "Home"
    plugsy.icon: "@styled-icons/fa-solid/Horse"
    plugsy.link: https://my.vikunja.com

Development

Simple enough:

docker-compose up --build

Notes

  • The development build will not include all of the icons, and will instead generate a static icon instead.
    • This is to reduce the build time. Webpack loading 18,000 dynamic icons is looooooong, any feedback on how to speed that up is appreciated!
  • Uses a custom Next.js server
    • This is in order for us to support websockets as Next.js doesn't by default.

CI

Based off of AsyncAPIs blog

FAQ

I can see the status of the connector, but I can't see my containers?

Ensure that a both a category and a name are defined, if you're using the default docker configuration and labels, that will require both the plugsy.category and plugsy.name labels on your container.

Category is required, you can only omit category when you want the container to appear as a child of another item on the dashboard.