kleypot

Home Assistant - Better Proxmox Monitoring with InfluxDB

Andrew Molina — Mon, 13 May 2024 17:35:16 GMT

The default Proxmox VE integration in Home Assistant basically only tells you which containers are running. But what if you want an automation to trigger if storage is running low, or if a specific VM's CPU is pegged?

Proxmox actually provides a way to expose its metrics to an external database. In this post I will show how I used the External Metric Server feature in Proxmox to set up the best possible integration between Proxmox and Home Assistant.

InfluxDB Setup

InfluxDB will serve as the database for Proxmox metrics which can be accessed by Home Assistant. The quickest way to get up and running with InfluxDB is to install it as an add-on in Home Assistant. The add-on comes bundled with Chronograf which makes this setup much easier to manage.

Install the InfluxDB add-on in Home Assistant.
Adjust the configuration if needed, then start the add-on.
Once the add-on is running, use the OPEN WEB UI button to ingress into the Chronograf web interface to confirm that it is up and running

Cronograf Web Interface

Now you need to add a database for Proxmox to write to. Go to the InfluxDB Admin panel and create a new database called proxmox. Adjust the duration of the default retention policy to a reasonable limit.

New database

Finally, you need a user with permissions to access the database. Go to the users tab and create a user called proxmox. On the next page toggle on the WRITE and READ permissions for the proxmox database.

User permissions

Proxmox Setup

Now that the database is in place, you can configure it as an External Metrics Server in Proxmox.

Log into your Proxmox web interface
Under Datacenter, go to Metric Server and Add a new InfluxDB connection.
Give the connection a meaningful name, like homeassistant. For the Server enter the IP of your Home Assistant installation. Set the port and protocol to match the configuration of the InfluxDB add-on.
Set the Token to username:password replacing username and password with the user you set up in InfluxDB.

Save the database connection, then return to the InfluxDB interface to test it out.
Go to the Explore tab and start a new Query. You should see the proxmox.autogen retention policy. Drill down into the proxmox.autogen and go to system > vmid and tick one of your VMs. Choose a field from the right and you should see some data.

vmid 100 cpu query

Try to familiarize yourself with the different measurements and fields available, and how the queries are constructed. In the next section will use these queries to build out sensors in Home Assistant.

Now that you have data flowing into InfluxDB, you can start setting up your sensors in Home Assistant.

Home Assistant Setup

As of when this guide was written, InfluxDB is still configured manually with YAML.

Optional step: Add another user in InfluxDB with read-only permissions on the proxmox database.
Add the InfluxDB integration to your configuration.yaml. This config simply enables the integration and blacklists all entities from being recorded.

influxdb:
  exclude:
    entity_globs: "*"

Add the sensor platform to your configuration.yaml. Change the values below to match your setup.

sensor:
  - platform: influxdb
    host: a0d7b954-influxdb
    username: someusername
    password: somepassword
    scan_interval:
      seconds: 15
    queries:
      - name: InfluxDB Proxmox VM 100 CPU
        unique_id: '42946dc7-c9ac-4f7d-abb0-198f9435b738'
        database: proxmox
        measurement: proxmox.autogen.system
        where: "vmid='100'"
        field: '"cpu"'
        group_function: last
        value_template: "{{ (value|float * 100) | round(1) }}"
        unit_of_measurement: '%'

Notes:

group_function decides how the data is aggregated. last simply chooses the latest value in the selection, which is appropriate for a real-time sensor.

value_template is handy for transforming the data. The template above multiplies fractional value by 100 to get a percentage.

scan_interval is set to be slightly longer than the update interval in InfluxDB which is 10 seconds.

Restart Home Assistant and locate the new entity

CPU usage sensor

If you do not see the new sensor, check your system logs and search for 'influxdb'

Advanced Sensors

Now you can start getting more creative with your sensors. If you are not yet familiar with the InfluxQL query language, I recommend using the query builder in the add-on to construct your query, then translate it over to your YAML config. I will walk through this process with an example below.

High CPU Usage Sensor

Suppose you want a sensor to drive an automation that notifies you when your CPU is pegged. It may not be unusual for the CPU to occassionally spike, so you should consider taking the mean value over a period of time.

Go to the Explore tab again in the InfluxDB add-on and start a new query.
Choose the proxmox.autogen retention policy.
Under Measurements, expand cpustat and tick your proxmox host.
Under Fields, tick cpu and apply the mean function.

Use the Group by dropdown to adjust the range of time over which the mean is computed. Notice that as you increase the duration of the mean, the resulting graph will smooth out the sharp peaks and valleys. This is exactly what we want to make sure those momentary CPU spikes don't trigger our automation.

Once the query is set up to your liking, you can translate it over to your configuration.yaml. Your code may differ from the below.

- name: InfluxDB Proxmox Host CPU 5m Average Usage
  unique_id: 'c9e2ca8b-48fa-4856-84ad-7a1f671735fa'
  database: proxmox
  measurement: proxmox.autogen.cpustat
  field: "cpu"
  group_function: mean
  where: "host='mini-neptune' AND time > now() - 5m AND time < now()"
  value_template: "{{ (value|float * 100) | round(1) }}"
  unit_of_measurement: '%'

Note that the home assistant yaml syntax does not provide an easy way to set the group-by interval and will therefore group by the entire selected range of values. We adjust for this by adding a 5 minute time window to the where clause.

Restart home assistant and check for the new sensor. Now you can trigger an automation if the sensor hits a certain while filtering out any momentary spikes!

High CPU notification

Conclusion

This InfluxDB integration gives you the best insight possible into the status of your Proxmox system by hooking directly into your system's metrics. This setup gives the most accurate real-time insight into your PVE host and all of your VMs and containers so that you can build meaningful automations and dashboards.

You can even take this a step further by installing the Grafana addon to build even more advanced visualizations.

Grafana visualization embeded in HA Dashboard

Thanks for reading!

Paperless-ngx Push Notifications

Andrew Molina — Thu, 18 Apr 2024 20:48:01 GMT

Here is a guide on how I set up mobile push notifications to my android phone whenever a document is consumed in paperless-ngx. This saves me the hassle of logging in to make sure documents were processed successfully, especially when those documents are coming from less-than-reliable clients like all-in-one printers.

For this setup I am using MQTT for messaging, Home Assistant for the push notifications, and Node-RED to glue it all together. You could easily substitute other protocols if needed (HTTP instead of MQTT, Telegram instead of Home Assistant, ...).

I have paperless-ngx hosted in docker on a Debian VM. This will not work for a bare-metal installation of paperless-ngx.

How it works

Paperless-ngx exposes hooks into the document consumption process. In particular, we will use the post-consumption hook to run a bash script. The process works like this:

Upload document to paperless-ngx
Document is queued and processed by paperless-ngx
Post-consumption script executes, publishes a JSON summary of the document to the MQTT broker.
Node-RED consumes the message from the MQTT broker and uses the Home Assistant notify service to push out the notification.

Set up MQTT Client

First, we need to add the MQTT client so that paperless-ngx can publish messages to our broker.

Create a new file Dockerfile at the same location as docker-compose.env. This allows us to build our own container with Mosquitto installed on top of the latest paperless-ngx image.

FROM ghcr.io/paperless-ngx/paperless-ngx:latest

RUN apt-get update && apt-get install -y mosquitto mosquitto-clients

Dockerfile

Now, edit docker-compose.yml so that it builds from the Dockerfile instead of using the paperless-ngx image.

version: "3.4"
services:

  webserver:
    build: .
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

Sample docker-compose.yml which builds from Dockerfile

Post-consumption Script

Now we can add our script to publish new document messages to the MQTT broker. Make a new scripts directory next to docker-compose.yml and add a new file post-consumption.sh. Replace the host, username, and password arguments according to your configuration.

#!/usr/bin/env bash

mosquitto_pub -h  --username  --pw  -t /paperless/post-consumption -m '{
    "id":"'"${DOCUMENT_ID}"'",
    "file_name":"'"${DOCUMENT_FILE_NAME}"'",
    "created":"'"${DOCUMENT_CREATED}"'",
    "modified":"'"${DOCUMENT_MODIFIED}"'",
    "added":"'"${DOCUMENT_ADDED}"'",
    "source_path":"'"${DOCUMENT_SOURCE_PATH}"'",
    "archive_path":"'"${DOCUMENT_ARCHIVE_PATH}"'",
    "thumbnail_path":"'"${DOCUMENT_THUMBNAIL_PATH}"'",
    "download_url":"'"${DOCUMENT_DOWNLOAD_URL}"'",
    "thumbnail_url":"'"${DOCUMENT_THUMBNAIL_URL}"'",
    "correspondent":"'"${DOCUMENT_CORRESPONDENT}"'",
    "tags":"'"${DOCUMENT_TAGS}"'",
    "original_filename":"'"${DOCUMENT_ORIGINAL_FILENAME}"'",
    "task_id":"'"${TASK_ID}"'"
}'

./scripts/post-consumption.sh

After saving the script, make sure to make the file executable.

$ chmod ug+x post-consumption.sh

Now, we need to mount the scripts folder so that the post-consumption script is available to the container. We do this by adding a new volume to docker-compose.env. Then we tell paperless about the script by setting the PAPERLESS_POST_CONSUME_SCRIPT environment variable.

version: "3.4"
services:

  webserver:
    build: .
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./scripts:/opt/scripts
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_POST_CONSUME_SCRIPT: /opt/scripts/post-consumption.sh

Sample docker-compose.yml with post-consumption script

Node-RED Subscriber

Next, we can jump over to Node-RED and see the messages flowing in on our new MQTT topic. Add a new mqtt in node and set the topic to /paperless/post-consumption, then run that node into a debug node.

Simple test flow

[{"id":"f1c99a4c36ff8e41","type":"mqtt in","z":"0b8e56ca785432e9","name":"","topic":"/paperless/post-consumption","qos":"2","datatype":"json","broker":"671331cca0db9c1a","nl":false,"rap":true,"rh":0,"inputs":0,"x":530,"y":220,"wires":[["a9fd6de7a6d58f9a"]]},{"id":"a9fd6de7a6d58f9a","type":"debug","z":"0b8e56ca785432e9","name":"debug 45","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":780,"y":220,"wires":[]},{"id":"671331cca0db9c1a","type":"mqtt-broker","name":"192.168.1.153","broker":"192.168.1.153","port":"1883","clientid":"","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true,"birthTopic":"","birthQos":"0","birthPayload":"","birthMsg":{},"closeTopic":"","closeQos":"0","closePayload":"","closeMsg":{},"willTopic":"","willQos":"0","willPayload":"","willMsg":{},"userProps":"","sessionExpiry":""}]

Simple test flow (JSON)

Now, try uploading a document to paperless and check the debug output. You should get a JSON payload populated with data from the new document.

MQTT payload

This payload should be all you need to set up all kinds of automations in Home Assistant. Note that you can also use the REST API to pull in even more details from paperless.

Mobile App Push Notifications

Here is how I automated push notifications to my Android device.

Push Notifications flow

[{"id":"f1c99a4c36ff8e41","type":"mqtt in","z":"0b8e56ca785432e9","name":"","topic":"/paperless/post-consumption","qos":"2","datatype":"json","broker":"671331cca0db9c1a","nl":false,"rap":true,"rh":0,"inputs":0,"x":180,"y":300,"wires":[["c0d020cf51bfbced"]]},{"id":"6c84dfb517eeebb8","type":"function","z":"0b8e56ca785432e9","name":"Build Notification Payload","func":"msg.payload = {\n    \"data\": {\n        \"title\": 'Paperless-ngx',\n        \"message\": 'New document: ' + msg.file_name,\n        \"data\": {\n            \"image\": \"/local/paperless/thumb.webp\",\n            \"when\": msg.added,\n            \"ttl\": 0,\n            \"priority\": \"high\",\n            \"channel\": \"Paperless\",\n            \"clickAction\": msg.paperless_url_base + \"/documents/\" + msg.id\n        }\n    }\n}\nreturn msg;","outputs":1,"timeout":"","noerr":0,"initialize":"","finalize":"","libs":[],"x":1230,"y":300,"wires":[["baa5324ed5b6970c"]]},{"id":"6f75de0eadaf83b4","type":"http request","z":"0b8e56ca785432e9","name":"GET thumbnail","method":"GET","ret":"bin","paytoqs":"ignore","url":"{{{paperless_url_base}}}/api/documents/{{{payload.id}}}/thumb/","tls":"","persist":false,"proxy":"","insecureHTTPParser":false,"authType":"basic","senderr":false,"headers":[{"keyType":"other","keyValue":"Content-Type","valueType":"other","valueValue":"image/png"}],"x":740,"y":300,"wires":[["9e97698091c19a1b"]]},{"id":"9e97698091c19a1b","type":"file","z":"0b8e56ca785432e9","name":"Write thumbnail to local storage","filename":"/homeassistant/www/paperless/thumb.webp","filenameType":"str","appendNewline":true,"createDir":false,"overwriteFile":"true","encoding":"none","x":970,"y":300,"wires":[["6c84dfb517eeebb8"]]},{"id":"c0d020cf51bfbced","type":"change","z":"0b8e56ca785432e9","name":"","rules":[{"t":"set","p":"when","pt":"msg","to":"payload.when","tot":"msg"},{"t":"set","p":"id","pt":"msg","to":"payload.id","tot":"msg"},{"t":"set","p":"file_name","pt":"msg","to":"payload.file_name","tot":"msg"}],"action":"","property":"","from":"","to":"","reg":false,"x":400,"y":300,"wires":[["ddd1fa4831958921"]]},{"id":"baa5324ed5b6970c","type":"api-call-service","z":"0b8e56ca785432e9","name":"","server":"d1ddf9d.c530808","version":5,"debugenabled":false,"domain":"notify","service":"mobile_app_galaxy_s10","areaId":[],"deviceId":[],"entityId":[],"data":"","dataType":"jsonata","mergeContext":"","mustacheAltTags":false,"outputProperties":[],"queue":"none","x":1490,"y":300,"wires":[[]]},{"id":"ddd1fa4831958921","type":"credentials","z":"0b8e56ca785432e9","name":"","props":[{"value":"paperless_url_base","type":"msg"}],"x":570,"y":300,"wires":[["6f75de0eadaf83b4"]]},{"id":"671331cca0db9c1a","type":"mqtt-broker","name":"192.168.1.153","broker":"192.168.1.153","port":"1883","clientid":"","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true,"birthTopic":"","birthQos":"0","birthPayload":"","birthMsg":{},"closeTopic":"","closeQos":"0","closePayload":"","closeMsg":{},"willTopic":"","willQos":"0","willPayload":"","willMsg":{},"userProps":"","sessionExpiry":""},{"id":"d1ddf9d.c530808","type":"server","name":"Home Assistant","addon":true}]

Push Notifications flow (JSON)

This works by subscribing to our new MQTT topic, downloading the thumbnail to Home Assistant local storage, then publishing the notification using the notify service.

Tapping the notification opens the document in the paperless-ngx web interface where I can quickly review the upload and set up the tags.

Thanks for reading!

Home Assistant: Add Camera Snapshots to Push Notifications

Andrew Molina — Fri, 26 Aug 2022 19:37:30 GMT

In this post I will share an easy way to add real-time camera snapshots to your Home Assistant push notifications. This is a great way to level up your push notifications, allowing you to actually see what is happening at the instant a notification was pushed. For example, you can send an image from your garage camera when the cover is opened, or from your wall mounted tablet when the security system is disarmed.

Home Assistant does allow you to send snapshots from a camera entity, but the advantage of my approach is that it reaches directly into the camera to get a snapshot. This eliminates the need to use camera entities, which are often plagued with latency, compression, and bandwidth issues. All you need to make this work is a camera with an HTTP endpoint for pulling the snapshots. I will show some specific examples using my Blue Iris cameras and my Fully Kiosk-enabled tablets, and I will share a reusable flow that you can plug in to your Node-RED config.

HTTP Endpoint

The first step is to figure out the HTTP endpoint to grab a snapshot from your camera. Most IP cameras and NVR systems will provide a way to pull a snapshot, so check with your manufacturer. Test the endpoint by opening it in a browser and ensure you get an image with the current timestamp.

The URL for a BlueIris camera looks something like this:

http://:/image/?s=50

And the URL for a Fully Kiosk-enabled Android tablet looks like this:

http://:2323/?cmd=getCamshot&password=

Note: you have to set up Remote Admin in Fully Kiosk and turn on a setting called "Enable Camshot on Remote Admin"

Example #1: Garage Notifications

The flow below triggers when my garage door starts to open, only when I am away from the house. Next, it calls my Blue Iris HTTP endpoint using the user and password stored by in the credentials node. If the HTTP request succeeds, the image is saved to local storage and sent out as a push notification. If the request fails, an error is logged and the request is sent out with no image. This way, I always get a notification even if the images are not working for some reason.

Garage Notification Flow

Below is a screenshot of the result. The notifications are impressively quick, and there is almost no latency between the trigger and the image. I actually use this same approach for my Video Doorbell and the images always line up with the moment that you press the chime button.

Android Notification

And here is the code:

[{"id":"da1e2737d73816ac","type":"trigger-state","z":"b0ef49e9e773bb6d","name":"When Garage Door Is Opening","server":"a86c4410.e2a568","version":2,"exposeToHomeAssistant":false,"haConfig":[{"property":"name","value":""},{"property":"icon","value":""}],"entityid":"cover.garage_door","entityidfiltertype":"exact","debugenabled":false,"constraints":[{"targetType":"this_entity","targetValue":"","propertyType":"current_state","propertyValue":"new_state.state","comparatorType":"is","comparatorValueDatatype":"str","comparatorValue":"opening"}],"inputs":0,"outputs":2,"customoutputs":[],"outputinitially":false,"state_type":"str","enableInput":false,"x":230,"y":200,"wires":[["b6a00b357813dc27"],[]]},{"id":"b6a00b357813dc27","type":"api-current-state","z":"b0ef49e9e773bb6d","name":"And Andrew Is Not Home","server":"a86c4410.e2a568","version":3,"outputs":2,"halt_if":"home","halt_if_type":"str","halt_if_compare":"is_not","entity_id":"person.andrew","state_type":"str","blockInputOverrides":false,"outputProperties":[{"property":"payload","propertyType":"msg","value":"","valueType":"entityState"},{"property":"data","propertyType":"msg","value":"","valueType":"entity"}],"for":"0","forType":"num","forUnits":"minutes","override_topic":false,"state_location":"payload","override_payload":"msg","entity_location":"data","override_data":"msg","x":510,"y":200,"wires":[["7523d56d77849f46"],[]]},{"id":"912b86806fded094","type":"inject","z":"b0ef49e9e773bb6d","name":"Send Now","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":180,"y":300,"wires":[["7523d56d77849f46"]]},{"id":"7074fde8ae85eb77","type":"comment","z":"b0ef49e9e773bb6d","name":"Trigger","info":"","x":150,"y":160,"wires":[]},{"id":"91d547e9b9e54664","type":"comment","z":"b0ef49e9e773bb6d","name":"Condition","info":"","x":460,"y":160,"wires":[]},{"id":"7523d56d77849f46","type":"credentials","z":"b0ef49e9e773bb6d","name":"","props":[{"value":"endpoint","type":"msg"},{"value":"user","type":"msg"},{"value":"password","type":"msg"},{"value":"local_storage_path","type":"msg"},{"value":"notify_service","type":"msg"}],"x":370,"y":300,"wires":[["3a65534795823a90"]]},{"id":"40a64f748838890e","type":"http request","z":"b0ef49e9e773bb6d","name":"GET Image","method":"GET","ret":"bin","paytoqs":"ignore","url":"","tls":"","persist":false,"proxy":"","insecureHTTPParser":false,"authType":"","senderr":false,"headers":[],"x":750,"y":300,"wires":[["b4da7befe3738159"]]},{"id":"f29e35e66db1823f","type":"file","z":"b0ef49e9e773bb6d","name":"Write File","filename":"\"/config/www/\" & $$.local_storage_path","filenameType":"jsonata","appendNewline":false,"createDir":false,"overwriteFile":"true","encoding":"none","x":1120,"y":280,"wires":[["83e1d989aa1b4855"]]},{"id":"3a65534795823a90","type":"change","z":"b0ef49e9e773bb6d","name":"Set Request Headers","rules":[{"t":"set","p":"url","pt":"msg","to":"endpoint","tot":"msg"},{"t":"set","p":"headers","pt":"msg","to":"{\t   \"Authorization\": 'Basic ' & $base64encode(\t      $$.user & ':' & $$.password\t   )\t}","tot":"jsonata"}],"action":"","property":"","from":"","to":"","reg":false,"x":560,"y":300,"wires":[["40a64f748838890e"]]},{"id":"b4da7befe3738159","type":"switch","z":"b0ef49e9e773bb6d","name":"Check Response","property":"statusCode","propertyType":"msg","rules":[{"t":"btwn","v":"200","vt":"num","v2":"299","v2t":"num"},{"t":"else"}],"checkall":"true","repair":false,"outputs":2,"x":930,"y":300,"wires":[["f29e35e66db1823f"],["6b04ee837f845b56"]]},{"id":"83e1d989aa1b4855","type":"change","z":"b0ef49e9e773bb6d","name":"","rules":[{"t":"set","p":"image_path","pt":"msg","to":"\"local/\" & $$.local_storage_path","tot":"jsonata"}],"action":"","property":"","from":"","to":"","reg":false,"x":1300,"y":280,"wires":[["4e5c2ea1dadbe317"]]},{"id":"77db453cf42002c8","type":"function","z":"b0ef49e9e773bb6d","name":"Throw Exception","func":"throw msg.statusCode + \" status returned from http request node.\"\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":1230,"y":360,"wires":[[]]},{"id":"f3fcf7e0d93aa899","type":"comment","z":"b0ef49e9e773bb6d","name":"Credentials (see example here)","info":"endpoint = http://1.2.3.4/snapshot\nuser = someuser (if needed)\npassword = secret (if needed)\nlocal_storage_path = images/snapshots/driveway.jpg\nnotify_service = mobile_app_galaxy_phone","x":430,"y":340,"wires":[]},{"id":"dd65180c2215a6bf","type":"debug","z":"b0ef49e9e773bb6d","name":"debug 3","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":1200,"y":400,"wires":[]},{"id":"4e5c2ea1dadbe317","type":"api-call-service","z":"b0ef49e9e773bb6d","name":"Notify","server":"a86c4410.e2a568","version":5,"debugenabled":false,"domain":"notify","service":"{{ flow.notify_service }}","areaId":[],"deviceId":[],"entityId":[],"data":"{\t   \"title\":\"Garage Door Opened\",\t   \"message\":\"The Garage Door was opened while you were away!\",\t   \"data\":{\t       \"clickAction\":\"/\",\t       \"tag\":\"garage_opened_while_away\",\t       \"image\":$$.image_path,\t       \"ttl\":0,\t       \"priority\":\"high\",\t       \"channel\":\"Doorbell\",\t       \"actions\":[\t           {\t               \"action\":\"snooze_alerts_1_hour\",\t               \"title\":\"Snooze 1hr\"\t           },\t           {\t               \"action\":\"close_garage_door\",\t               \"title\":\"Close Now\"\t           }\t       ]\t   }\t}","dataType":"jsonata","mergeContext":"","mustacheAltTags":false,"outputProperties":[],"queue":"none","x":1470,"y":320,"wires":[[]]},{"id":"6b04ee837f845b56","type":"junction","z":"b0ef49e9e773bb6d","x":1080,"y":320,"wires":[["77db453cf42002c8","dd65180c2215a6bf","4e5c2ea1dadbe317"]]},{"id":"a86c4410.e2a568","type":"server","name":"Home Assistant","version":4,"addon":true,"rejectUnauthorizedCerts":true,"ha_boolean":"y|yes|true|on|home|open","connectionDelay":true,"cacheJson":true,"heartbeat":false,"heartbeatInterval":30,"areaSelector":"friendlyName","deviceSelector":"friendlyName","entitySelector":"friendlyName","statusSeparator":"at: ","statusYear":"hidden","statusMonth":"short","statusDay":"numeric","statusHourCycle":"h23","statusTimeFormat":"h:m"}]

Garage Notification Code

Copy the flow above into your editor
Change the trigger and conditions to suit your needs
Fill out the credentials node with your endpoint, username, password, and so on
Set up your notification in the Notify node

Note: this code depends on the Credentials plugin. Make sure to install this plugin first.

Example #2: Alarm Panel Notifications

Here is another example where I enhanced the push notifications for my home alarm system. The flow is very similar to the previous example, all I had to do was change the settings as outlined in the previous example so that it pulls images from my kiosk tablet.

Conclusion

With this template you can now enhance all of your push notifications to pull images from relevant cameras in your home. You can even extend this concept to push images out to other services, like a file share or a Telegram channel. Real-time images add valuable context to your notifications and make your Home Assistant even more useful. Thanks for reading!

Laravel Development on Windows in 2022

Andrew Molina — Tue, 26 Jul 2022 14:26:16 GMT

Microsoft has come a long way in recent years with tech like Windows Subsystem for Linux (WSL) and Visual Studio Code. The official Laravel docs now even favor WSL over alternatives like Vagrant. But while the Laravel docs give you enough to get up and running, they do not give you any guidance on how to set up VS Code for the best possible experience. Without some very important extensions and packages, you will find yourself constantly flipping between your editor, doc pages, error stacks, and terminal windows. Trying to keep everything in your head – Laravel syntax, artisan commands, phpunit tests, project structure, and so on – can be a significant cognitive burden which slows you down and pulls you out of your dev flow.

In this post, I will show how I set up VS Code to streamline Laravel development. The goal is to reduce as much as possible the need to look things up, manually run commands, or parse through arcane error messages.

GitHub - akmolina28/laravel-vscode-example: Laravel starter project pre-configured for VSCode (WSL2)

Laravel starter project pre-configured for VSCode (WSL2) - GitHub - akmolina28/laravel-vscode-example: Laravel starter project pre-configured for VSCode (WSL2)

GitHubakmolina28

Some of the highlights:

Full intellisense and autocomplete for Laravel framework, including Facades, Eloquent, and custom model classes.
"Quick fixes" to automatically fix common syntax errors.
Automatic code formatting according to predefined standards.
Snippets to generate commonly used code blocks.
Code navigation, quickly jump from caller to declaration.
ESLint and Hot Module Reloading (HMR).
Integrated Bash shell.
Inline Git history/blame.
Shortcuts and palette commands for PHPUnit, Artisan, and more.

Installing WSL2

The first thing you should do is install Windows Subsystem for Linux (WSL). Even if this is the only advice you take from this post, just install WSL and start playing with it. WSL has completely changed the way I develop in Windows, as it finally provides a really fast and robust way to run Linux distributions.

What is Windows Subsystem for Linux

Learn about the Windows Subsystem for Linux, including the different versions and ways you can use them.

Microsoft Docscraigloewen-msft

I am using Ubuntu 20.04, but any distro that supports Docker would work. If you are new to WSL, here are two things to help get you started after you install your distro of choice:

You can start up a shell from the Start Menu by typing the name of your distro. From a Windows point-of-view, WSL looks like any other App. You may need to run as Administrator for all features to work properly.

Launching WSL2 from the Start Menu

2. The WSL file system is mounted as virtual drive which you can access with the file explorer at \\wsl$

Visual Studio Code Remote Development

Next, install VS Code if you haven't already, and make sure you have the Remote Development extension. Unlike Visual Studio which uses Solution files and Project files to organize projects, Visual Studio code uses workspace folders. You simply open a folder from your file system, and that becomes your workspace in VS Code.

Developing in the Windows Subsystem for Linux with Visual Studio Code

Using Visual Studio Code Remote Development with the Windows Subsystem for Linux (WSL)

MicrosoftMicrosoft

Remote Development is a very powerful, first-party extension which allows you to open workspaces on remote machines over SSH, or within WSL or Docker containers. VS Code will automatically run a server within your WSL instance, giving it full access to the Linux terminal and file system.

Docker Desktop and Laravel Sail

The next dependency is Docker Desktop for WSL2. Docker allows you to run Laravel Sail, a portable development environment which uses containers to run all of Laravel's dependencies like php, mysql, and redis. This saves you from having to manage all of those dependencies yourself, and it makes your development environment portable.

Install Docker Desktop on Windows

How to install Docker Desktop for Windows

Docker Documentation

Once Docker is installed and running, follow the Laravel documentation to set up Sail.

Laravel - The PHP Framework For Web Artisans

Laravel is a PHP web application framework with expressive, elegant syntax. We’ve already laid the foundation — freeing you to create without sweating the small things.

The PHP Framework For Web Artisans

$ curl -s https://laravel.build/laravel-vscode-example | bash

$ cd laravel-vscode-example

$ ./vendor/bin/sail up -d

$ code .

The final command above will start VS Code in your WSL workspace. You should also be able to view the website at http://localhost/.

Laravel application default page

This is the bare minimum to get started with Laravel development on Windows, and this is where you can start bringing in more extensions to make working in VS Code much more efficient.

Scaffolding with Laravel Breeze

Laravel - The PHP Framework For Web Artisans

Laravel is a PHP web application framework with expressive, elegant syntax. We’ve already laid the foundation — freeing you to create without sweating the small things.

The PHP Framework For Web Artisans

This is an optional step which I am including in order to have a more fully-fledged project to work with. Laravel Breeze will scaffold up a basic application with authentication and and user dashboard, plus it will install a front-end framework (I am using Vue.js in this example). Breeze will also configure Hot Module Reloading (HMR) which is critical for rapid front-end development.

Note that you can now use the WSL terminal in VS Code! Open the terminal with Ctrl+`.

Installing Laravel Breeze using the WSL terminal in VS Code

$ sail composer require laravel/breeze --dev

$ sail artisan breeze:install vue

$ sail artisan migrate

$ sail npm install

$ sail npm run dev

The final command above will start the Vite development server which serves up all of the client side assets. You should see some output in the console with links to where the site is running (Ctrl+click to open).

Laravel Vite

As of the time I am writing this, there are two issues that aren't addressed in the official documentation for Sail users on Windows.

The default APP_URL will not be accessible because Windows cannot resolve it. You can either edit the hosts file to point APP_URL to 127.0.0.1, or you can change the APP_URL setting in your .env file to http://localhost. I prefer the latter approach.
When using Sail, Vite will try to serve assets from 0.0.0.0, which will not resolve outside of the Docker containers. To fix this, manually configure the host for HMR in vite.config.js.

export default defineConfig({
    server: {
        hmr: {
            host: 'localhost',
        },
    },
    // ...
});

Vite should automatically restart after saving the files above, giving you a new link which should open now. Make sure you can also access the routes that were added by Breeze like /register and /login.

Laravel Breeze Register page

While the Register page is open, go to the file resources/js/Pages/Auth/Register.vue and make a small change. For example, change "Confirm Password" to "Re-type Password". As long as Vite is still running, you should see your changes instantly in the browser.

Test and Build Tasks

Now that Sail is up and running, we can configure the default Tasks for running Vite. While you can easily run these tasks manually in the terminal, I prefer the convenience of using hotkeys rather than switching to the terminal and running a sail command.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Laravel",
      "type": "shell",
      "command": "./vendor/bin/sail npm run dev",
      "group": {
        "kind": "test",
        "isDefault": true
      },
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "Build for Production",
      "type": "shell",
      "command": "./vendor/bin/sail npm run build",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ]
}

.vscode/tasks.json

After adding the tasks.json file to the project, you can open the command palette with ctrl+shift+P and...

Type "Run Test Task" to start Laravel test container, or
Type "Run Build Task" to build for production

You can also set up keyboard shortcuts to access these commands more quickly.

[
  {
    "key": "ctrl+shift+r",
    "command": "workbench.action.tasks.test"
  },
  {
    "key": "ctrl+shift+b",
    "command": "workbench.action.tasks.build"
  }
]

keybindings.json

Extensions for PHP and Laravel

Visual Studio code comes with very little PHP support out of the box. You get basic syntax highlighting and some auto-complete support. Open any PHP file and write some code, and you'll quickly see how limited these features are.

No autocomplete for basic Laravel library functions

PHP Intelephense

The first extension to grab is PHP Intelephense, a feature-rich PHP language server which juices up VS Code's syntax highlighting and code navigation.

Quick fix for missing use statement

Right away you should see that errors are highlighted in the editor and in the explorer. There are also many "Quick fixes" available for common issues like missing imports. Intelephense can also format your code according to the latest PSR standards. I recommend turning on Format on Save.

laravel-ide-helper

Now we have a good backbone for PHP, but we lack support for Laravel development. This problem is not unique to VS Code, and there is actually a composer package to fix it.

$ sail composer require --dev barryvdh/laravel-ide-helper

$ sail artisan ide-helper:generate

$ sail artisan ide-helper:models

These artisan commands will generate PHPDocs for everything in Laravel. Now, Intelephense should give you full autocomplete for almost everything you need to do in php.

Full intellisense for Laravel

Intellisense for User-generated code

If you want intellisense for your own code, you will need to correctly decorate your functions and classes with PHPDocs. This is not very well documented in the PHP Intelephense docs, but there is a snippet available to do most of the work for you. If you type /** and press enter above a declaration, Intelephense will set up the PHPDoc with blanks for you to fill in and tab through (use the tab key).

Example PHPDoc

Once your PHPDoc is filled out, you should the info reflected by intellisense.

Intellisense for user-generated code

Laravel Artisan

While you can use the terminal to run artisan commands (e.g. sail artisan make:model MyModel), the Laravel Artisan extension makes life easier by adding commands to the command palette. Each command's options are explicitly shown, for example when you create a model, the extension will ask if you also want to create a factory, a seeder, a controller, and so on. You can (and should) also assign keyboard shortcuts to frequently used commands, like migrate or cache:clear.

To make this extension work with Sail, add two settings to your workspace:

{
  "artisan.docker.command": "./vendor/bin/sail",
  "artisan.docker.enabled": true,
}

.vscode/settings.json

Laravel Extension Pack

Laravel Extension Pack is a package of several extensions which are useful for Laravel development. Along with Laravel Artisan, it includes several extensions for snippets and blade support. I recommend looking at the list of included extensions and manually installing whichever seem useful for your project. For example, I prefer Vue/React for my view layer, so I do not bother with Blade extensions.

Extensions for Vue and JavaScript

Now that PHP is set up, we need support for our JavaScript framework. If you open a Vue file, right away you will notice that VS Code has no out-of-the-box support for Vue.js. First we will grab an add-on for language support, followed by additional addons for snippets, code formatting, and linting.

Vue.js file with no language support (formatted as Plain Text)

Volar

Volar is the standard extension for vue 3 (for Vue 2, check out Vetur). The extension reads the jsconfig.json file that ships with Laravel 9, so no additional configuration should be needed. Once installed, you should have syntax highlighting and basic intellisense.

Vue.js file with Volar language support

Prettier and ESLint

Now that we have language support, we can bring in extensions for code formatting and style enforcement. Prettier is a code formatter with support for Vue.js, and ESLint is the standard tool for linting JavaScript code and enforcing code standards. Together, these plugins can detect syntax and style errors, and offer quick fixes for common issues. In my opinion, these are must-have plugins for Vue.js development.

Prettier and ESLint require a few additional dependencies:

$ sail npm install prettier@^2.5.1 --save-dev

$ sail npm install eslint@^8.7.0 --save-dev

$ sail npm install vue-eslint-parser@^8.0.0 --save-dev

$ sail npm install eslint-plugin-vue --save-dev

$ sail npm install eslint-config-prettier --save-dev

$ sail npm install vite-plugin-eslint --save-dev

$ echo {}> .prettierrc.json

$ touch .eslintrc.json

$ touch .eslintignore

Then, edit .eslintrc.json as follows:

{
  "root": true,
  "extends": [
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "prettier"
  ],
  "rules": {
    "vue/multi-word-component-names": "off"
  }
}

Next, edit .eslintignore to ignore vendor scripts and autogenerated files:

node_modules
public
vendor
**/dist
**/components.d.ts
!/docs/.vitepress
resources/js/ziggy.js

Finally, add ESLint to the Vite config so that lint errors are detected and displayed on the development server:

import eslint from "vite-plugin-eslint";

export default defineConfig({
  plugins: [
    eslint(),
  ],
});

Snippet from vite.config.js

Now, when you open a Vue or JavaScript file, VS Code should highlight syntax errors and warnings in your code. When you save the file, Prettier should automatically format it to comply with the lint rules. Any issues that cannot be fixed by the formatter can either be fixed by the "Quick fixes", or otherwise must be fixed by hand. ESLint will also run when the Vite build runs, and you will see any errors and warnings rendered in the browser as well as the terminal.

Vue VSCode Snippets

For Vue development, Vue VSCode Snippets is a must-have extension which offers tons of help when you can't remember syntax, and boilerplate templates to fill out new components.

PHPUnit Extensions

If you are doing Laravel right, you are writing tests for all of your new modules. Sail includes a solid implementation of PHPUnit, but you are still required to run your tests manually in the terminal. VS Code fortunately has several community extensions for running PHPUnit tests in a more seamless way. I prefer the extension PHPUnit for ease of configuration.

After installing, you will have to configure it to use Sail.

{
  "phpunit.command": "./vendor/bin/sail",
  "phpunit.paths": {
    "${workspaceFolder}": "/var/www/html"
  },
  "phpunit.phpunit": "test"
}

.vscode/settings.json

Now you can use the command palette to run your test suites. You can also run individual tests based on the position of your cursor. You should consider setting up keyboard shortcuts so you can easily run the test you are currently working on. These shortcuts will save you from having to manually run tests in the terminal, which can be very tedious and disruptive to your workflow.

[
  {
    "key": "ctrl+alt+t",
    "command": "phpunit.Test",
    "when": "editorFocus"
  },
  {
    "key": "ctrl+shift+alt+t",
    "command": "phpunit.TestSuite"
  }
]

keybindings.json

Unit test executed from editor focus hotkey

PHP Debugging

The latest version of Sail now includes Xdebug, making it easier than ever to set up native PHP debugging in VS Code. The PHP Debug extension allows you to set breakpoints and evaluate your variables and call stacks during runtime. The Debug Console also allows you to run PHP statements using the debugger's context.

Add new value to .env

SAIL_XDEBUG_MODE=develop,debug

.env

2. Add

Other Useful Extensions

If you are new to VS Code, make sure to check out other popular extensions on the marketplace. Here are some other recommendations which I use in all of my projects, not just Laravel:

Docker - manage Sail containers through the VS Code UI
Bracket Pair Colorizer - make it easier to match opening and closing brackets
Color Highlight - highlight hex codes and rgb colors
GitLens - inline blame and advanced Git features
Auto Close Tag - automatically create HTML close tags, e.g.
Auto Rename Tag - automatically rename HTML close tag when open tag changes
Font Awesome Auto-complete - search and preview icons
Format in context menus - add right click format option to file explorer

Thank you for reading! Feel free to post any questions or issues to Github.

Vue.js Single Page Application with ASP.NET MVC 5

Andrew Molina — Fri, 08 Jul 2022 15:09:24 GMT

In this post I will share how I set up an ASP.NET MVC 5 project as a SPA using Vue.js. I will walk through each step of constructing this template so you can see what each piece does and how you may need to modify it for your tastes. I will also include some tips on how to set up your environment for rapid development.

GitHub - akmolina28/mvc5-vuejs-template

Contribute to akmolina28/mvc5-vuejs-template development by creating an account on GitHub.

GitHubakmolina28

The completed template is available now on Github. If you're already comfortable with npm and webpack, feel free to jump straight to the source code.

Key Features:

Responsive design using Bulma (or the framework of your choice via npm).
True SPA with client-side routing.
Dependency injection using Ninject.
Hot module reloading for rapid development (browser is automatically refreshed when you change a file).
Browser-sync for testing in multiple browsers or viewports at once.
Bundling, minification, cache-busting, and source-maps for all static files.
MSBuild events to run the webpack build when building the MVC project or publishing the project manually or via CI/CD
ESLint integration for Vue and JS files.

Model-Vue-Controller

The basic idea is to have the MVC application function as a headless API for your basic CRUD operations. Then, instead of using Razor and jQuery for the View layer, we will use Vue. The routing is also handled on the client-side using Vue Router to create a true single-page application.

Strip Down

The first thing I did after creating a new MVC 5 application in VS2019 was to start stripping out all of the default client-side tooling.

Uninstall nuget packages: bootstrap, Microsoft.jQuery.Unobtrusive.Validation, jQuery.Validation, and jQuery.
Remove folders ~/Content, ~/fonts, and ~/Scripts
Remove BundleConfig.cs (bundling will be handled by webpack)
Remove entire Views folder (razor views will be replaced by Vue components)

This clears the way to begin pulling dependencies in via npm and setting up our SPA.

SPA Routing

Next, we need to set up our default route. Instead of the traditional routes for controller actions, we will create one catch-all route to return our single page. Start by removing the HomeController, and adding a new controller called SpaController.

public class SpaController : Controller
{
    public ActionResult Index()
    {
    	return File("~/dist/index.html", "text/html");
    }
}

~/Controllers/SpaController.cs

The SpaController has a single action which returns index.html, which will be our single page.

Finally we just need to update the routes so that all routes go to our new SPA action. Remove the default route and map a new route like this:

public class RouteConfig
{
    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        routes.MapRoute(
            name: "SPA",
            url: "{*catchall}",
            defaults: new { controller = "Spa", action = "Index" }
        );
    }
}

~/App_Start/RouteConfig.cs

Hello Vue

Now that the project has been stripped down, we can start fresh with npm. Our first goal is to get a simple hello world working with Vue.

Source Code

All of our client-side source code will go into a new folder called src. Let's start by adding three files there:

1. Create ~/src/index.html. This is the "single page" which is served up for our SPA. Vue will hook into the div in the body.




    
    MVC 5 Vue.js Template

index.html

2. Create ~/src/components/HelloWorld.vue. This is a simple Vue component with basic reactivity.

HelloWorld.vue

3. Create ~/src/js/app.js. This is the entry-point for the application which initializes the HelloWorld component into our div in index.html.

import Vue from 'vue';

import HelloWorld from "../components/HelloWorld";

new Vue({
  el: '#app',
  components: {
    HelloWorld
  }
});

app.js

Source code

Build Configuration

Next, we have to set up webpack to build the assets above into something that our web browser can understand. First we need to initialize our npm project and pull in our dependencies.

$ npm init
$ npm i -s vue vue-template-compiler
$ npm i -D webpack webpack-cli
$ npm i -D vue-loader css-loader postcss
$ npm i -D html-webpack-plugin

vue and vue-template-compiler are provided by Vue.js for processing Vue files
webpack and webpack-cli are used to set up our build process
vue-loader, css-loader, and postcss are to help webpack make sense of our source code
html-webpack-plugin is to inject the script tags into index.html. This is important because the script tags due to cache busting.

The final step is to add the file ~/webpack.config.js. If you are not familiar with webpack, this is the most overwhelming part of this setup. Here is a boilerplate config to start with, but note that this might need to be tweaked for your specific environment and/or package versions.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const { VueLoaderPlugin } = require('vue-loader');
const path = require('path');

module.exports = {
  mode: 'development',
  devtool: 'eval',
  entry: [
    './src/js/app.js',
  ],
  output: {
    clean: true,
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/dist',
    filename: '[name].bundle.[contenthash].js',
  },
  resolve: {
    // point bundler to the vue template compiler
    alias: {
      'vue$': 'vue/dist/vue.esm.js',
    },
    // allow imports to omit file exensions, 
    // e.g. "import foo from 'foobar'" instead of "import foo from 'foobar.js'"
    extensions: ['.js', '.vue'],
  },
  module: {
    rules: [
      // use vue-loader plugin for .vue files
      {
        test: /\.vue$/,
        use: 'vue-loader'
      },
    ],
  },
  plugins: [
    new VueLoaderPlugin(),
    new HtmlWebpackPlugin({
      template: 'src/index.html',
      inject: true,
      // favicon: 'src/images/favicon.ico',
      publicPath: '/dist'
    }),
  ],
};

webpack.config.js

Now we can execute our build by running wepback:

$ npx webpack --config=webpack.config.js

Succesful webpack build

The build emits two files into the output folder, the script bundle and the modified index.html file. If you open ~/dist/index.html you will see that webpack has inject the script tags.

Finally, if we run the debugger in Visual Studio, we should see the working hello world demo.

Styles and Layout

Now we have Vue and webpack working, but our app looks pretty ugly. Let's add some style by installing a CSS framework and setting up a layout. For this demo I will use Bulma, but at this point you could something else like Bootstrap or Tailwind.

Refer to the latest Bulma documentation for complete setup. This guide may be outdated.

Bulma + Webpack Setup

$ npm i -D bulma
$ npm i -D extract-text-webpack-plugin@next mini-css-extract-plugin node-sass sass-loader style-loader
$ npm i -s @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/vue-fontawesome@latest

bulma – responsive CSS framework
extract-text-webpack-plugin, mini-css-extract-plugin, node-sass, sass-loader, style-loader – webpack plugin for bundling the styles
fortawesome packages – free icon pack

Now we can hook up the styles by adding our application's main sass file, ~/src/sass/app.scss:

@charset "utf-8";
@import "~bulma/bulma";

app.scss

And we can import app.scss and the icon pack into our bundle.

Remember, app.js is the only defined entry point in our webpack configuration. We either need to import the styles into app.js, or add the styles as a separate entry point.

import Vue from 'vue';

// load all solid icons
// modify here to load individual icons as needed to reduce bundle size
import { fas } from '@fortawesome/free-solid-svg-icons';
import { library } from '@fortawesome/fontawesome-svg-core';
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';
library.add(fas);

import HelloWorld from "../components/HelloWorld";
import Layout from "../components/Layout";

// pull in main stylesheet
require('../sass/app.scss');

new Vue({
  el: '#app',
  components: {
    HelloWorld,
    Layout
  }
});

app.js updated to import app.scss

The final setup is to update our webpack config with some new rules for our styles. I am using the optional mini-css-extract-plugin to extract the styles into a separate file with its own content-hash.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const { VueLoaderPlugin } = require('vue-loader');
const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  mode: 'development',
  devtool: 'eval',
  entry: [
    './src/js/app.js',
  ],
  output: {
    clean: true,
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/dist',
    filename: '[name].bundle.[contenthash].js',
  },
  resolve: {
    // point bundler to the vue template compiler
    alias: {
      'vue$': 'vue/dist/vue.esm.js',
    },
    // allow imports to omit file exensions, 
    // e.g. "import foo from 'foobar'" instead of "import foo from 'foobar.js'"
    extensions: ['.js', '.vue'],
  },
  module: {
    rules: [
      // use vue-loader plugin for .vue files
      {
        test: /\.vue$/,
        use: 'vue-loader'
      },
      // rule for loading .scss files
      {
        test: /\.scss$/,
        use: [
          MiniCssExtractPlugin.loader,
          {
            loader: 'css-loader',
          },
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true,
            },
          },
        ],
      }
    ],
  },
  plugins: [
    new VueLoaderPlugin(),
    new MiniCssExtractPlugin({
      filename: 'css/[name].bundle.[contenthash].css',
    }),
    new HtmlWebpackPlugin({
      template: 'src/index.html',
      inject: true,
      //favicon: 'src/images/favicon.ico',
      publicPath: '/dist'
    }),
  ],
};

webpack.config.js updated for loading sass

After these changes, running the build should emit a third file, css/main.bundle.[hash].css:

Successful webpack build

Responsive Layout

Now that Bulma is set up, we can begin using the framework by adding a layout to wrap our content. Here is a boilerplate layout file, very similar to the example provided in the Bulma documentation. Add this code to ~/src/components/Layout.vue:

~/src/components/Layout.vue

And then we just need to update app.js and index.js to use the Layout:

import Vue from 'vue';

import HelloWorld from "../components/HelloWorld";
import Layout from "../components/Layout";

require('../sass/app.scss');

new Vue({
  el: '#app',
  components: {
    HelloWorld,
    Layout
  }
});

Add Layout component to app.js




  
  MVC 5 Vue.js Template

Add component to index.html

Now if we rebuild the bundle and run the VS debugger, we should see our hello world component styled and rendered in our new layout component.

Bulma Layout

Routing and API Setup

Now we have almost everything we need to start building out our SPA. At this point, index.html is hard coded to serve up our layout and our hello-world component. We need to change this so that it instead serves up dynamic content depending on which route the user has requested.

But before I set up the routing, I will set up some models and controller actions so that our routes actually have something useful to serve up.

API Backend

Let's create a simple data model and a data context for storing and reading data. Then we can add our API actions and routing.

1. Add the data model under ~/Models/MovieModel.cs

namespace mvc5_vuejs_template.Models
{
    public class MovieModel
    {
        public int Id { get; set; }

        public string Title { get; set; }

        public int Year { get; set; }

        public string Director { get; set; }

        public string Studio { get; set; }
    }
}

MovieModel.cs

2. Add the data context under ~/Services/MovieService.cs

namespace mvc5_vuejs_template.Services
{
    public class MovieService
    {
        private static List _movieContext = new List()
        {
            new MovieModel()
            {
                Id = 1,
                Title = "Jurrasic Park",
                Director = "Steven Spielberg",
                Year = 1993,
                Studio = "Universal Pictures"
            },
            new MovieModel()
            {
                Id = 2,
                Title = "Alien",
                Director = "Ridley Scott",
                Year = 1979,
                Studio = "20th Century Fox"
            },
            new MovieModel()
            {
                Id = 3,
                Title = "Titanic",
                Director = "James Cameron",
                Year = 1997,
                Studio = "Paramount Pictures"
            }
        };

        public IEnumerable GetMovies()
        {
            return _movieContext;
        }

        public int InsertMovie(MovieModel model)
        {
            int id = _movieContext.Last().Id + 1;

            model.Id = id;
            _movieContext.Add(model);
            return id;
        }
    }
}

MovieService.cs

3. Add the actions to ~/Controllers/MovieController.cs

namespace mvc5_vuejs_template.Controllers
{
    public class MovieController : Controller
    {
        private MovieService _movieService;

        public MovieController()
        {
            _movieService = new MovieService();
        }

        public JsonResult Index()
        {
            var movies = _movieService.GetMovies();
            return Json(movies.ToArray(), JsonRequestBehavior.AllowGet);
        }

        [HttpPost]
        public JsonResult Create(MovieModel movie)
        {
            var insertedMovie = _movieService.InsertMovie(movie);
            return Json(insertedMovie);
        }
    }
}

MovieController.cs

4. Add the API routes under ~/App_Start/RouteConfig.cs

namespace mvc5_vuejs_template
{
    public class RouteConfig
    {
        public static void RegisterRoutes(RouteCollection routes)
        {
            routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

            routes.MapRoute(
                name: "API",
                url: "api/{controller}/{action}/{id}",
                defaults: new { id = UrlParameter.Optional }
            );

            routes.MapRoute(
                name: "SPA",
                url: "{*catchall}",
                defaults: new { controller = "Spa", action = "Index" }
            );
        }
    }
}

RouteConfig.cs

Now our CRUD actions are accessible using api routes. The main difference between an API action and a traditional MVC action is that our API actions only return JSON data, whereas MVC actions typically return Razor views.

We can test the API by running the debugger and navigating to /api/movie/index to hit the Index action. We should get raw JSON back.

/api/movie/index route

Movie Views and Vue Router

Next, add some Vue components to display and add new Movies. Then we can set up client-side routing using Vue Router so we can navigate between the "pages" of our SPA.

1. Pull in the axios library for making requests to the API.

$ npm i -s axios

2. Add the list-view component under ~/src/components/Movies/Index.vue. This component will get the list of movies and render it in a table.

Id	Title	Year	Director	Studio
{{ movie.Id }}	{{ movie.Title }}	{{ movie.Year }}	{{ movie.Director }}	{{ movie.Studio }}

Movie/Index.vue

3. Add the create view under ~/src/Components/Movie/Create.vue. This component has a form to create new movies.

Movie/Create.vue

Now we have our views, but we need a way to navigate them in our SPA.

4. Pull in Vue Router from npm.

$ npm i -S vue-router

5. Add the routing to ~/src/js/router.js. This is where we will set up all of our client-side routing.

import VueRouter from 'vue-router';
import HelloWorld from '../components/HelloWorld';
import MovieIndex from '../components/Movie/Index';
import MovieCreate from '../components/Movie/Create';

const routes = [
  {
    path: '/',
    name: 'default',
    component: HelloWorld,
  },
  {
    path: '/movies',
    name: 'movie_index',
    component: MovieIndex,
  },
  {
    path: '/movies/create',
    name: 'movie_create',
    component: MovieCreate,
  },
];

export default new VueRouter({
  mode: 'history',
  routes,
  linkActiveClass: 'is-active', // apply bulma class when a router link is active
});

router.js

6. Import Vue Router and the custom routes to the entry point ~/src/js/app.js. We can also remove the code that imports the HelloWorld component, because that is handled by the router now.

import Vue from 'vue';

import VueRouter from 'vue-router';
import router from './router';
Vue.use(VueRouter);

// load ALL solid icons
// modify here to load individual icons as needed to reduce bundle size
import { fas } from '@fortawesome/free-solid-svg-icons';
import { library } from '@fortawesome/fontawesome-svg-core';
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome';
library.add(fas);
Vue.component('icon', FontAwesomeIcon);

import Layout from "../components/Layout";

require('../sass/app.scss');

new Vue({
  el: '#app',
  router,
  components: {
    Layout
  }
});

app.js

7. Finally, we need to update ~/src/index.html to render the component returned by our router. We just have to replace the hard-coded hello-world component with the built-in router-view component:




  
  MVC 5 Vue.js Template

index.html

Re-run the webpack build and start the visual studio debugger, then navigate to the /movies route. You should see the list of movies and you should be able to add more to the list.

/movies route

Router Links and Transitions

Vue Router also provides a convenient way to generate links to your routes using the router-link component. We will use this component now to wire up our navigation links. We can also wrap our content in a to create a smoother feel when navigating between different routes.

Layout.vue

Run the build again and try clicking the Home and Movies links in the navigation. The views should fade out/in smoothly as you navigate back and forth. You can tweak the fade effect by updating the included sass rules.

Integrated Build for Dev and Prod

Now we have a fully working SPA. The MVC application exposes a CRUD API, and all of the View code and routing is handled in Vue. The last thing we have to do is integrate the webpack build into our MSBuild process. This will ensure that our webpack bundles are built whenever...

A new developer checks out and builds the solution
You manually publish the web project to a folder
You deploy using your CI/CD process

Dev and Prod Builds

First, let's split our webpack build into two separate configurations. This will allow us to do conditional things like minification and source mapping depending on the environment.

1. Add a new webpack config for prod, ~/webpack.prod.js. This config will contain overrides for our production build.

const baseConfig = require('./webpack.config.js');
const { merge } = require("webpack-merge");

module.exports = merge(baseConfig, {
	mode: 'production',
	devtool: false,
});

webpack.prod.js

2. Add helper scripts to package.json so we have cleaner build commands.

{
  // package.json...
  // ...
  
  "scripts": {
    "dev": "webpack --config=webpack.config.js",
    "prod": "webpack --config=webpack.prod.js"
  }
}

Excerpt from package.json

3. Now, test out the different builds using the new custom commands:

$ npm run dev
$ npm run prod

Look at the output in the dist folder to see the differences between the two builds. The prod build should exclude source-maps, and the generated bundles will be much smaller in size. See the webpack documentation for more on how webpack optimizes production bundles.

MSBuild Integration

Now we can set up our project to automatically run the webpack build corresponding to the selected Build Configuration.

1. In Visual Studio, right-click the Project and unload it.

2. Double-click the project to edit the .csproj file.

3. Add the following code at the end of the figit


  
    $(CompileDependsOn);
    WebpackBuild;
  
  
    $(CopyAllFilesIntoSingleFolderForPackageDependsOn);
    CollectWebpackOutput;
  
  
    $(CopyAllFilesToSingleFolderFolderForMsDeployDependsOn);
    CollectWebpackOutput;
  


  
  
  
  
  
  


  
  
    
    
      .\dist\%(RecursiveDir)%(Filename)%(Extension)

Excerpt from .csproj file

Overview of what this does:

Creates a new build target called WebpackBuild. Building the project depends on the success of WebpackBuild.
Defines the target WebpackBuild which runs npm install and npm run dev or npm run prod depending on your build configuration.
Includes all files in the ~/dist output folder in the published output.

When you Build the project in Visual Studio now, you should see the webpack build in the Build Output:

MSBuild output

Note that if the webpack build fails, then the entire build will fail and Visual Studio will show the errors in the build output. This is really important for other developers who may not realize that project depends on this extra build process. It will force them to install node.js and run webpack in order to build and debug the project.

The code sample above also has a custom condition for a build configuration called Unit Test. This gives you a way to skip the entire npm/build process to save time when you are running tests.

Setting up your environment for rapid development

The SPA is completely set up now and ready for development. In the previous sections, I demonstrated how you would build out this application by setting up new models, controller actions, views (Vue components), and client-side routing. But before starting development, you should consider also setting up some tools and plugins to make this process even easier.

In the rest of this post I will summarize how I set up my own dev environment to quickly and efficient turn out clean, working Vue code.

Visual Studio Code

There is bad news and good news if you are looking to write Vue code for .NET web applications. The bad news is, as of the time I'm writing this post, Visual Studio has not really embraced Vue.js. That may change under .NET Core, but you're mostly on your own when it comes to Vue.js tooling, especially with MVC 5 projects.

The good news is that Visual Studio Code has amazing support for Vue.js. I actually recommend using VS Code in parallel with Visual Studio. You can edit and debug your ASP.NET code in VS, and you can use VS Code for all of the front-end work. If you haven't tried VS Code yet, this guide will be a great introduction for you – go ahead and install the latest version and continue on.

Visual Studio Code - Code Editing. Redefined

Visual Studio Code is a code editor redefined and optimized for building and debugging modern web and cloud applications. Visual Studio Code is free and available on your favorite platform - Linux, macOS, and Windows.

MicrosoftMicrosoft

Git Bash Integration

My first recommendation after you install VS Code is to set up Git Bash as the default terminal. As shown throughout this post, you will be using the terminal a lot, and in my opinion Git Bash is the best option on vanilla Windows unless you are a PowerShell expert.

Install Git for Windows which includes Git Bash. You most likely already have this, but here is the link in case you do not.
Open VS Code, and hit Ctrl+Shift+P then run the command Terminal: Select Default Profile.
Choose Git Bash from the list of options

Git Bash as default terminal

Now you can open the terminal (Ctrl+`) and you should get a new Git Bash terminal. Try out some basic commands like ls -la, or try running your build with npm run dev.

Vetur Extension

The first extension you will want to grab is Vetur, the official extension for Vue.js tooling. Vetur will allow you to do things like lint and auto-format your Vue code, and it adds Intellisense and snippets to save you from having to constantly look at documentation.

Download and enable the Extension in VS Code
Add a jsconfig file to the project:

{
    "include": [
      "./src/**/*"
    ]
}

jsconfig.json

3. Restart VS Code and open a Vue file. You should have syntax highlighting and intellisense right away. See examples below.

Syntax highlighting before/after

Vue API Intellisense

Vue VSCode Snippets

Next, you should grab Vue VSCode Snippets, which will save you a lot of time by scaffolding common structures with just a few keystrokes. Check out the Extension details for some snippets you can try.

Vue VSCode Snippets

Other Helpful Extensions

Some other Extensions that I can't live without include:

Auto Close Tag – automatically add HTML close tags just like Visual Studio
Auto Rename Tag – automatically rename HTML close tags just like Visual Studio
Bracket Pair Colorizer – colorize matching open/close brackets
GitLens – visualize code authorship inline in the editor
npm Intellisense – autocomplete import statements
Vue.js devtools - first-party chrome extension for debugging Vue components

ESLint for Vue

If you work on a team or plan on publishing your code, you should really consider setting up a linter for enforcing code styles and checking syntax.

Here, I'll show you how you can integrate ESLint into your build process so that the build fails if the code does not pass lint. I will also demonstrate how ESLint integrates into VS Code by highlighting errors, and how you can auto-correct common syntax issues. Using ESLint in this way will dramatically improve your code quality without getting in your way too much. Over time it will actually make you a better Vue coder.

1. Install ESLint dependencies

$ npm i -D eslint eslint-webpack-plugin

2. Generate your ESLint config

$ ./node_modules/.bin/eslint --init

For the prompts the follow, choose:

To check syntax, find problems, and enforce code style
JavaScript modules
Vue.js
Typescript: no
Browser
Use a popular style guide
Airbnb (or whichever you prefer)
JSON

The final prompt will ask you to install extra dependencies. This may or may not work due to permissions issues on Windows file systems. If the install errors out, just install the dependencies manually.

$ npm i -D eslint-plugin-vue@latest eslint-config-airbnb-base@latest eslint-plugin-import@^2.22.1

Manually install dependencies

3. Run the linter

$ npx eslint ./src/**/*.*

You should get a bunch of errors referencing lines of code in the src folder. Do not worry about fixing these yet, we will do that later with the help of VS Code and Vetur.

Build output with lint errors

4. Add a helper script to package.json so that you can run the linter with npm run lint

{
  // package.json
  // ...
  "scripts": {
    "lint": "eslint ./src/**/*.*",
    // ...
  }
}

Excerpt from package.json

5. Update .eslintrc.json to suit your tastes. I recommend starting with the following:

{
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": [
    "plugin:vue/base",
    "airbnb-base"
  ],
  "parserOptions": {
    "ecmaVersion": 12,
    "sourceType": "module"
  },
  "plugins": [
    "vue"
  ],
  "rules": {
    "linebreak-style": [
      "warn",
      "windows"
    ]
  }
}

.eslintrc.json

I have overridden one rule to allow Windows linebreak styles. Otherwise you will have to manually change to LF every time you edit a file in VS or VS Code. You can add/modify different rules here as needed.

6. Install the ESLint Extension in VSCode.

7. In VS Code, open your Vue and JS files to start fixing issues. When you open a file, you should get a list of issues in the Problems window, with in-line highlighting provided by Vetur. Vetur also allows you to quickly resolve these issues.

Here are just some of the ways you can resolve your lint errors:

Hover over the red squiggles, choose Quick Fix for a menu of options.
Move your cursor to the issue and hit Alt+Shift+. to auto-fix the issue.
Disable the rule globally in .eslintrc.json.
Use in-line or for the whole file, or for a specific block or line of code.
My personal favorite: Hit Ctrl+Shift+P and run the command ESLint: Fix all auto-fixable Problems

Using the code accumulated so far in this guide, I was actually able to autofix almost every problem. If you are following along, go ahead and fix all of your issues and run npm run lint until you get no errors back.

8. Update your webpack config to run and depend on ESLint.

const ESLintWebpackPlugin = require('eslint-webpack-plugin');

module.exports = {
  // ...
  plugins: [
    // ...
    new ESLintWebpackPlugin({
      failOnError: false,
    }),
  ],
};

Excerpt from webpack.config.js

Now when you run your build, ESLint will automatically check all of your source code and it will emit errors into the build output. You can enable failOnError to block the build if you have lint issues – it is nice to do this for prod builds but can be annoying for dev. failOnError is really important because it will prevent un-linted builds from going out, regardless of who is building the code. ESLint will be run as part of the MSBuild process, so even your CI/CD will error out if the linter fails.

File Watching

There is one more thing we can do to speed up development. A common annoyance with bundlers like webpack is that you have to run the build every time you make changes because your browser cannot directly execute the source code. Large bundles can easily take 10-20 seconds to run, and only then can you refresh the page and re-test. This delay is a significant cognitive burden and can really interrupt your flow as you are making changes.

The quickest fix for this problem is to use the watch flag when running webpack.

{
  // package.json
  // ...
  "scripts": {
    // ...
    "watch": "webpack --config=webpack.config.js --watch"
  }
}

$ npm run watch

When you run using watch, the build runs once and then the process stays open instead of returning. If you touch a file while the process is open, webpack will rapidly re-bundle your code. It is practically instantaneous, so really all you need to do is save the file and refresh your browser.

Webpack Dev Server and Hot Module Reloading

But what if you didn't even need to refresh your browser? We can take the watcher a step farther by using the Webpack DevServer to host our website.

Webpack DevServer is a node-based web server which can be used to automatically open your browser and reload your modules when you make changes to the code. The dev server runs the build and the watcher, and serves up the bundled output from memory. A common mistake is thinking that the dev server is using the files in your /dist folder, but it actually never touches those files. In fact, you will even see a message in the output like, Content not from webpack is served from 'C:\Users\username\source\repos\mvc5-vuejs-template\public' directory.

1. Install Webpack DevServer

$ npm i -D webpack-dev-server

2. Add devServer options to the webpack config

module.exports = {
  // ...
  devServer: {
    historyApiFallback: {
      index: '/dist/index.html',
    },
    proxy: [
      {
        context: '/api/**',
        target: 'http://localhost:64373', // use port from IISExpress
      },
    ],
    open: true
  },
};

Excerpt from webpack.config.js

The configuration above is where the special sauce is. We are telling the dev server to route all requests to /dist/index.html, which is the same exact routing we set up in the MVC project. Next, we are proxying our API routes to use the IIS Express Url. This way, we can get data from our MVC API by running the debugger in the background.

Note that you will have to update the IISExpress port to match the one used by your project.

3. Add a new script to package.json to run the dev server.

{
  // package.json
  // ...
  "scripts": {
    "hot": "webpack-dev-server --config=webpack.config.js"
  }
}

3. Start the Visual Studio debugger to make sure IISExpress is running

4. Start the dev server by running npm run hot

If everything is set up correctly, your browser should open automatically and you should be able to interact with your SPA on port 8080. All of the API requests should be proxied to IISExpress, which you can confirm by setting breakpoints in the controller.

Most importantly, when you edit and save a Vue file, the page should reload with your changes almost instantaneously. And as long as you are changing code inside of a

kleypot

Home Assistant - Better Proxmox Monitoring with InfluxDB

InfluxDB Setup

Proxmox Setup

Home Assistant Setup

Advanced Sensors

High CPU Usage Sensor

Conclusion

Paperless-ngx Push Notifications

How it works

Set up MQTT Client

Post-consumption Script

Node-RED Subscriber

Mobile App Push Notifications

Home Assistant: Add Camera Snapshots to Push Notifications

HTTP Endpoint

Example #1: Garage Notifications

Example #2: Alarm Panel Notifications

Conclusion

Laravel Development on Windows in 2022

Installing WSL2

Visual Studio Code Remote Development

Docker Desktop and Laravel Sail

Scaffolding with Laravel Breeze

Test and Build Tasks

Extensions for PHP and Laravel

PHP Intelephense

laravel-ide-helper

Intellisense for User-generated code

Laravel Artisan

Laravel Extension Pack

Extensions for Vue and JavaScript

Volar

Prettier and ESLint

Vue VSCode Snippets

PHPUnit Extensions

PHP Debugging

Other Useful Extensions

Vue.js Single Page Application with ASP.NET MVC 5

Model-Vue-Controller

Strip Down

SPA Routing

Hello Vue

Source Code

{{ message }}

Build Configuration

Styles and Layout

Bulma + Webpack Setup

Responsive Layout

Routing and API Setup

API Backend

Movie Views and Vue Router

Movies

Create Movie

Router Links and Transitions

Integrated Build for Dev and Prod

Dev and Prod Builds

MSBuild Integration

Setting up your environment for rapid development

Visual Studio Code

Git Bash Integration

Vetur Extension

Vue VSCode Snippets

Other Helpful Extensions

ESLint for Vue

File Watching

Webpack Dev Server and Hot Module Reloading

Browser-sync

Conclusion

Git Merge Deep Dive

Setup

Resolving Conflicts in Visual Studio

Back to Basics

Git Mergetool

Conclusion

Meld Merge on Windows and Visual Studio

Meld Merge

Global Configuration

Installation on Windows

Advanced Configuration

`Advanced Configuration`

`Going Back to vsdiffmerge`