I’m using Glance for over a year now, and never had any issue with it. However, as the number of widgets and data sources increased, I noticed that the dashboard started to load slowly, especially on initial load. I have to resign with many widgets just to keep the load time fast. I was also trying to split the dashboard into multiple pages, but it was not an ideal solution, especially when I wanted to see all the data at once. One of the widgets that I wanted to have was Synology Disk Station Widget, but it was increasing the load time significantly, as each authorization request was taking 2-3 seconds.

Recently, I discovered that Glance can load data from JSON files that are hosted via glance-assets directory. Knowing that, I thought that I could use crontab to periodically fetch data from my services and store them as JSON files in the glance-assets directory.

Docker compose setup

Here is my docker-compose snippet for Glance with the necessary volume mappings:

glance:
  image: glanceapp/glance:v0.8.4
  volumes:
    - ./glance:/app/config
    - ./glance-assets:/app/assets # << directory for JSON files
    - /etc/timezone:/etc/timezone:ro
    - /etc/localtime:/etc/localtime:ro
    - /var/run/docker.sock:/var/run/docker.sock

Monitoring Synology NAS

To monitor my Synology NAS, I created a bash script that uses the Synology API to fetch CPU, RAM, and storage utilization data. The script then writes this data to synology_stats.json in the glance-assets directory.

The original code that I used comes from the Glance community widgets repository, which you can find here.

You need to have jq installed on your system to parse JSON responses.

#!/bin/bash
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

NAS_IP="[YOUR_NAS_IP]"
NAS_PORT="[YOUR_NAS_PORT]" # usually 5000 or 5001 for HTTPS
USERNAME="[YOUR_NAS_USERNAME]"
PASSWORD="[YOUR_NAS_PASSWORD]"
BASE_URL="http://${NAS_IP}:${NAS_PORT}/webapi/entry.cgi"

# Authenticate and get SID
AUTH_RESPONSE=$(curl -s "${BASE_URL}?api=SYNO.API.Auth&version=6&method=login&account=${USERNAME}&passwd=${PASSWORD}&session=FileStation&format=sid")
SID=$(echo "$AUTH_RESPONSE" | jq -r '.data.sid')

if [[ -z "$SID" || "$SID" == "null" ]]; then
  echo "Failed to authenticate with Synology NAS" >&2
  exit 1
fi

# Fetch storage info
STORAGE_RESPONSE=$(curl -s "${BASE_URL}?api=SYNO.Core.System&method=info&type=storage&version=1&_sid=${SID}")

# Fetch CPU and RAM utilization
CPU_RESPONSE=$(curl -s "${BASE_URL}?api=SYNO.Core.System.Utilization&method=get&version=1&_sid=${SID}")

# Parse storage data
TOTAL_SIZE=$(echo "$STORAGE_RESPONSE" | jq -r '.data.vol_info[0].total_size')
USED_SIZE=$(echo "$STORAGE_RESPONSE" | jq -r '.data.vol_info[0].used_size')
STORAGE_PERCENT=$(awk "BEGIN {printf \"%.0f\", ($USED_SIZE / $TOTAL_SIZE) * 100}")

# Parse CPU and RAM data
CPU_PERCENT=$(echo "$CPU_RESPONSE" | jq -r '.data.cpu.user_load')
RAM_PERCENT=$(echo "$CPU_RESPONSE" | jq -r '.data.memory.real_usage')

# Generate timestamp
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Write JSON output
cat > /home/jpomykala/Compose/glance-assets/synology_stats.json <<EOF
{
    "timestamp": "${TIMESTAMP}",
    "cpu_percent": ${CPU_PERCENT},
    "ram_percent": ${RAM_PERCENT},
    "storage_percent": ${STORAGE_PERCENT}
}
EOF

echo "Synology stats updated successfully"

Make sure to replace all placeholders with credentials and adjust the output file path. Save the script as monitor-synology.sh. Don’t forget to give it execute permissions:

chmod +x monitor-synology.sh

I set up a cron job to run this script every 15 minutes:

sudo crontab -e

and add the following line:

*/15 * * * * /home/YOUR_PATH/scripts/monitor-synology.sh

After few minutes, you should see a file created in glance-assets with:

{
    "timestamp": "2026-01-02T10:30:04Z",
    "cpu_percent": 0,
    "ram_percent": 44,
    "storage_percent": 51
}

Glance widget configuration

Here is the Glance widget configuration to display the Synology NAS stats:

- type: custom-api
  cache: 1m
  title: Synology
  url: http://glance.home/assets/synology_stats.json
  template: |
    <div class="flex justify-between text-center">
      <div class="flex-1">
        <div class="size-h4 color-highlight">%</div>
        <div class="size-h6">RAM</div>
      </div>
      <div class="flex-1">
        <div class="size-h4 color-highlight">%</div>
        <div class="size-h6">STORAGE</div>
      </div>
      <div class="flex-1">
        <div class="size-h4 color-highlight" ></div>
        <div class="size-h6">LAST UPDATE</div>
      </div>
    </div>

This configuration uses the custom-api widget type to fetch data from the JSON file that will be updated by the cron job. In my case, the URL is:

http://glance.home/assets/synology_stats.json

but you should adjust the domain or IP address according to your setup.

Result

After setting everything up, I was able to add the Synology NAS widget to my Glance dashboard without any noticeable delay in loading time. The data is updated every 15 minutes, and the dashboard remains responsive and fast.

In my case, I also created similar scripts for monitoring other things like, systemctl services, and backups status, all using the same approach of pre-caching data in JSON files.

Support

If you think Glance is as cool as I do, please consider supporting the developer on GitHub Sponsors. I think even a small contribution will make the developer smile. :)

Recently, after 7 years of using Alfred PowerPack , I decided to create some workflows for my daily tasks. Unfortunately, I couldn’t find a quick way to get nice-looking icons for them, so I made an app that allows me to upload an SVG icon and generate a nice background for it.

I had to generate ~8 icons, so instead opening Sketch I decided to make an app for it. It took me an hour to make it. 😄

I primarily use FontAwesome as my source for icons , but I believe there are more icon projects out there. I made it primarily for myself. It took me less than an hour to make it.

Creating workflows is now super easy with ChatGPT, but please beware of that ChatGPT not always knows everything regarding the latests updates, eg. Automation Tasks that are super cool. 😎

Here’s the link to the icon generator: Icon Generator

Feel free to ping me with suggestions! I’m open to adding more advanced options, but for now, I wanted to keep it simple.

I won’t cover how to send messages from the client to the server, as it didn’t fit into the context of the project presented in this post.

Prerequisites

To follow this tutorial, it’s good to know the basics of Java, Spring Boot, and Spring Security, and have a general understanding of WebSockets and ReactJS, as we will use ReactJS to communicate with the server using WebSockets.

Why WebSockets and not Server-Sent Events

A few months back, I started working on a workflow automation engine at SimpleLocalize. The idea was very simple: I wanted to create a feature where you can create workflows for translations. For example, when you modify a source translation, it would auto-translate other translations for all other languages.

I knew that building an automation engine handling all the rules and logic would be a challenge, but I also knew that some automations created by users wouldn’t run fast enough to return results in a few seconds. I needed a way to notify users browsing the content that the translations were being updated.

After a few hours of research, I decided to use server-side events (SSE) to send live updates to the client. SSE works similarly to a regular HTTP request but allows the server to send updates to the client without the client having to send a request. I didn’t need duplex communication; it was enough to send updates from the server to the client.

Unfortunately, the solution didn’t work well with the reverse proxy we used, which struggled with many long-running connections. At some point, when specific conditions were met, the frontend received malformed JSON responses, like { message: 'OK' } { mes (yiiikes!). The short-term solution was to set an SSE timeout to 15 seconds and reconnect after that time, but it wasn’t a good solution.

Shortly after that, I started looking into WebSockets. WebSockets were a buzzword in the web development world a few years back, and they are still very popular and widely used. They are well-supported by all modern browsers and infrastructure middlewares. I hoped that WebSockets would solve my problem with live updates, and they did!

Currently, we have over 100 live users simultaneously connected to the server without any hiccups, and we are gradually increasing this number by switching from SSE to WebSockets.

Why I don’t want to use STOMP and SockJS

Most of the tutorials (including the Spring Framework docs) on the internet use STOMP and SockJS to implement WebSockets in Spring Boot applications. It’s worth explaining what STOMP and SockJS are:

• STOMP provides a higher-level API to work with WebSockets, such as subscribing to topics, sending messages, etc. However, it adds complexity to the application, which I don’t need, at least for now.

• SockJS provides fallback support for browsers that don’t support WebSockets. Since all modern browsers support WebSockets, fallback support is generally unnecessary. While SockJS can be useful if WebSockets are blocked in a user’s network, such cases are rare these days, and I haven’t encountered any so far.

I’ve decided to use just the Spring Boot WebSocket dependency and the native WebSocket API provided by the browser to avoid dependence on any external libraries and Spring Boot magic.

Authentication in WebSockets

In a real-world application, you would need to authenticate and authorize users before they can connect to the WebSocket. You can use Spring Security to handle this process. Nearly seven years ago, I wrote a post on how to use Spring Security with WebSockets; you can check it out here. However, after gaining more experience, I’d prefer to use less Spring magic and keep things simple.

I’ve decided to use a straightforward ticket-based authentication mechanism. The server generates a ticket for the user when they connect to the WebSocket, and the client uses this ticket to authenticate with the server.

How to configure WebSockets in Spring Boot

Let’s dive into the code and see how we can configure WebSockets in Spring Boot 3. I’ve started by creating a service class called WssConnectorService that extends TextWebSocketHandler class provided by Spring Boot. To keep it easy to read for the purpose of this tutorial, the WssConnectorService realizes a few functionalities:

• It keeps track of all the connected users and their sessions.
• It creates a ticket for a user when they connect to the WebSocket.
• It removes unused tickets every 5 minutes.
• It sends a message to a user.
• It pings all the connected users every 10 seconds to check if the connection is still alive.

All tickets and sessions are stored in-memory, but in a real-world application, you could store them in a database or a cache like Redis.

@Component
public class WssConnectorService extends TextWebSocketHandler
{
  private final ObjectMapper objectMapper;
  private final List<WssUser> wssUsers = new CopyOnWriteArrayList<>();
  private final Map<String, WssTicketDetails> tickets = new ConcurrentHashMap<>();

  // Connection closed by client
  @Override
  public void afterConnectionClosed(@NotNull WebSocketSession session, @NotNull CloseStatus status)
  {
    wssUsers.removeIf(wssUser -> wssUser.session().equals(session));
  }

  // Connection established by client
  @Override
  public void afterConnectionEstablished(@NotNull WebSocketSession session)
  {
    // Example uri: /wss?ticket=123
    String ticket = Optional.ofNullable(session.getUri())
            .map(URI::toString)
            .map(UriComponentsBuilder::fromUriString)
            .map(builder -> builder.build().getQueryParams().getFirst("ticket"))
            .filter(StringUtils::hasText)
            .orElseThrow(() -> new BadRequestException("Ticket not found in query"));

    WssTicketDetails ticketDetails = tickets.get(ticket);
    WssUser wssUser = WssUser.builder()
            .userId(ticketDetails.userId())
            .projectToken(ticketDetails.project().projectToken())
            .session(session)
            .build();
    tickets.remove(ticket);
    wssUsers.add(wssUser);
  }

  public void sendEvent(WssUser wssUser, LiveEvent event)
  {
    try
    {
      String json = objectMapper.writeValueAsString(event);
      WebSocketSession session = wssUser.session();
      session.sendMessage(new TextMessage(json));
    } catch (
            Exception e) // you can catch more specific exception here and handle it in a different ways, e.g.: when the session is closed unexpectedly
    {
      wssUsers.remove(wssUser);
    }
  }

  public String createTicketForUser()
  {
    User user = // e.g.: get current user
            Project project = // e.g.: get project for the user
          WssTicketDetails ticketDetails = WssTicketDetails.builder()
          .project(project)
          .userId(userId)
          .createdAt(Instant.now())
          .build();
    String ticket = // create a unique ticket, e.g. UUID, SecureRandom, or JWT token with expiration time
            tickets.put(ticket, ticketDetails);
    return ticket;
  }

  @Scheduled(fixedDelay = 5, initialDelay = 5, timeUnit = TimeUnit.MINUTES)
  public void removeUnusedTickets()
  {
    tickets.entrySet().removeIf(this::isTicketExpired);
  }

  private boolean isTicketExpired(Map.Entry<String, WssTicketDetails> entry)
  {
    return entry.getValue().createdAt().toEpochMilli() < System.currentTimeMillis() - TimeUnit.MINUTES.toMillis(5);
  }

  @Scheduled(fixedDelay = 10, initialDelay = 10, timeUnit = TimeUnit.SECONDS)
  public void pingSessions()
  {
    for (WssUser wssUser : wssUsers)
    {
      sendEvent(wssUser, LivePingEvent.ping());
    }
  }
}

LiveEvent class is a simple interface that represents an event that can be sent to the client. We have two types of events: PING and CONTENT_CHANGE. Here is the implementation of the LivePingEvent class:

public interface LiveEvent
{
  LiveEventType type();
}

public enum LiveEventType
{
  PING,
  CONTENT_CHANGE
}

@Builder
public record LivePingEvent(LiveEventType type, String message) implements LiveEvent
{
  public static LivePingEvent ping()
  {
    return LivePingEvent.builder().type(LiveEventType.PING).message("ping").build();
  }

  @Override
  public LiveEventType getType()
  {
    return type;
  }
}

Isn’t it simple? We have a service class that extends TextWebSocketHandler and keeps track of all the connected users and their sessions. Here is the controller class that we will use to create a ticket for a user when they connect to the WebSocket, and send the ticket to the client:

@RestController
public class WssConnectorController
{
  private final WssConnectorService wssConnectorService;

  @GetMapping("/wss/ticket")
  public WssTicketResponse getTicket()
  {
    String ticket = wssConnectorService.createTicket();
    return WssTicketResponse.builder().ticket(ticket).build();
  }
}

Solid and dead simple, not very scalable as we used in-memory storage to keep everything, but it’s a good starting point.

Here is the configuration class that we will use to configure WebSockets in our Spring Boot 3 application. I’ve created a class called WssConfig that implements the WebSocketConfigurer interface, and added @EnableWebSocket annotation to enable WebSockets in our application.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration
@EnableWebSocket
public class WssConfig implements WebSocketConfigurer
{

  public WssConfig(WssConnectorService wssConnectorService)
  {
    this.wssConnectorService = wssConnectorService;
  }

  @Override
  public void registerWebSocketHandlers(WebSocketHandlerRegistry registry)
  {
    registry.addHandler(wssConnectorService, "/wss").setAllowedOrigins("*");
  }
}

Please also remember that you have to adjust your Spring Security configuration to allow access to the /wss endpoint.

How to connect to the WebSocket from the client

Now, that we have configured WebSockets in our Spring Boot 3 application, let’s see how we can connect to the WebSocket from the client. This part is a most satisfying one, as we will use a native APIs provided by the browser to connect to the WebSocket.

useEffect(() => {
  let wss: WebSocket;

  const connectToServer = async () => {
    const openWebSocket = (ticket: string) => {
      wss = new WebSocket("ws://localhost:8080/wss?ticket=" + ticket);
      wss.onopen = () => console.log("Connection opened");
      wss.onmessage = (message: any) => {
        const response = JSON.parse(message?.data);
        if (response.type === SseEventType.CONTENT_CHANGE) {
          // update the UI with the new content
        }
      };
      wss.onclose = () => console.log("Connection closed"); // you can try to reconnect here
    };
    fetch("/wss/ticket")
      .then((response) => response.json())
      .then((data) => data.ticket)
      .then((ticket) => openWebSocket(ticket))
      .catch((error) => console.error("Error getting ticket", error));
  };

  connectToServer().catch((error) => console.error("Error while initial connection", error));
  return () => {
    console.log("Gracefully closing the connection");
    wss.close();
  };
}, []);

In this code snippet, we are using the WebSocket and fetch APIs provided by the browser to connect to the WebSocket from the client. We are first fetching a ticket from the server using the /wss/ticket endpoint, and then we are connecting to the WebSocket using the ticket.

We are also handling the onopen and onmessage events of the WebSocket to log the connection status and process the messages received from the server.

Once you connect to the WebSocket, you can also periodically check if the connection is closed and reconnect if necessary, e.g.:

setInterval(() => {
  if (wss?.readyState === WebSocket.CLOSED) {
    console.log("Connection closed, reconnecting...");
    connectToServer().catch((error) => console.error("Error while reconnecting", error));
  }
}, 2000);

// cleanup the interval when the component is unmounted
return () => clearInterval(intervalId);

Conclusion

That’s all! In this post, we have set up the most basic implementation of WebSockets with Spring Boot 3 to send live updates from the server to the client.

The biggest advantage of this approach (and disadvantage at the same time) is that it’s very simple and doesn’t require any additional libraries like STOMP or SockJS. This simplicity makes the setup lightweight and easy to understand, reducing the overhead of learning and maintaining extra dependencies. However, it also means that you miss out on the additional features and abstractions provided by these libraries, such as automatic fallback mechanisms and higher-level messaging protocols.

If your application requirements are straightforward and you prefer to minimize dependencies, this approach is ideal. However, if you need more advanced features like message brokering, topic subscriptions, or support for older browsers and network environments, you might want to consider using mentioned technologies.

Below is an example of how the auto-translation feature works using a Context Menu in SimpleLocalize:

I started realising my idea from upgrading my network, by getting a better Wi-Fi PCIe card for my PC and router with WiFi 6. Previous setup wasn’t able to keep stable 80MB/s transfers, mostly due to weak Wi-Fi signal at my PC. I also had to switch from Raspberry Pi 3b+ to Raspberry Pi 5, because RPI3 doesn’t support 4K resolution.

To make sure everything will go smoothing from that point I’ve also took a case with active cooling, official microHDMI 2.1 cable, and official 27W power adapter.

…and that was just a start of my troubles. At time of writing this post (May 2024) Raspberry Pi 5 doesn’t work nice with moonlight-qt and there is no official Steam Link app for ARM64, so I took me a few days of digging to get the setup working. I’m writing this post so you don’t have to waste your time.

Here you can find a repository with all the scripts: https://github.com/jpomykala/moonlight-pi

Before we start

I assume that you have already done the followings:

Gaming PC side:

• Installed Steam
• Installed Sunshine
• Configured a static address on your router
• Configured Wake-On-Lan (WOL)

Raspberry Pi 5 side:

• Installed Raspbian Bookworm Lite (x64)
• Installed moonlight-qt on Raspberry Pi

I won’t cover those topics in this post, as they are straightforward to do. I also assume you have some basic IT skills to find information on your own, like finding a MAC address, using a command line, bash etc.

Moonlight and Raspberry Pi 5

Unfortunately, at time I’m writing the post the default configuration that comes with moonlight-qt doesn’t play nicely with Raspberry Pi 5, but way to make it work by creating a custom egls.json configuration file.

I’ve a 4K TV, so in my case the egls.json file looks like this:

{
  "device": "/dev/dri/card1",
  "outputs": [
    {
      "name": "HDMI1",
      "mode": "3840x2160"
    }
  ]
}

For different resolutions you should just change the mode value.

Important: Raspberry Pi 5 has 2 microHDMI ports, and the above egls.json assumes that you connect your TV to the microHDMI port next to power input.

Let’s run it:

QT_QPA_EGLFS_KMS_CONFIG=eglfs.json moonlight-qt

Now, you should see a moonlight app on your TV screen, and if you PC is running it should be there. You can use a small cog icon in the top-right corner to adjust the streaming settings to your liking. In my case I’ve selected 4K resolution and 60FPS with ~80MBs of bitrate. I’ve set encoders and decoder settings to “Automatic” and I checked “HDR (Experimental)”

Connecting Xbox Controller

For connecting an Xbox Controller I’ve used an official Xbox dongle and ‘xone’ driver that worked like a charm on a first shot. Please follow the instructions on the GitHub page to install the driver as they might change in the future.

Unfortunately, my previous attempt of connecting Xbox Controller via Bluetooth didn’t work for some reason, so I just turned off built-in Bluetooth and Wi-Fi, just to save power and decrease the interference using rfkill block wlan and rfkill block bluetooth.

Streaming Steam Big Picture

By default, moonlight opens a window where we can select our PC and change the settings. Once we choose a PC then we have to choose an app. Fortunately, moonlight-qt developers covered a case if we would like to automate the connection. Let’s start from listing apps that are available on your PC using moonlight-qt list <YOUR_PC_IP_ADDRESS>

jpomykala@raspberry:~ $ moonlight-qt list 192.168.0.120
00:00:00 - Qt Info: Unable to detect Wayland or X11, so EGLFS will be used by default. Set QT_QPA_PLATFORM to override this.
00:00:00 - Qt Info: Setting display mode by default. Set QT_QPA_EGLFS_ALWAYS_SET_MODE=0 to override this.
00:00:00 - Qt Critical: drmModeGetResources failed (Operation not supported)
Desktop
Steam Big Picture
jpomykala@raspberry:~ $ 

By default, moonlight have 2 apps, Desktop and Steam Big Picture, with this information we create a command that will look like this:

QT_QPA_EGLFS_KMS_CONFIG=eglfs.json moonlight-qt stream 192.168.0.120 'Steam Big Picture'

to start streaming Steam Big Picture automatically without needing any interaction.

Waking up the PC

Waking up the PC is a nice part of this post. I’ve installed etherwake package that allows me to send a Magic Packet

sudo apt install etherwake

Using it is simple as that:

etherwake <PC_MAC_ADDRESS>

You don’t need to add any IP address, mask or anything. It should just work. Here is copy and paste installation command:

Listening for controller events

This is the most exciting part of this post. Whenever, I turn on my Xbox Controller I wanted to wake up my PC, and run moonlight to start streaming the Steam Big Picture. For this I’ve used udev and udev rules. Udev allows me to detect whenever my Xbox Controller is connected or disconnected and run some custom scripts.

Getting controller details

Lets start about getting some details about the controller as we need to know what to look for in udev rules. Make sure that your controller is connected and run the following command: ls -l /dev/input

$ ls -l /dev/input/
total 0
drwxr-xr-x 2 root root     100 May 19 14:53 by-path
crw-rw---- 1 root input 13, 64 May 19 13:17 event0
crw-rw---- 1 root input 13, 65 May 19 14:10 event1
crw-rw---- 1 root input 13, 66 May 19 14:10 event2
crw-rw---- 1 root input 13, 67 May 19 14:10 event3
crw-rw---- 1 root input 13, 68 May 19 14:10 event4
crw-rw---- 1 root input 13, 68 May 19 14:10 event5
crw-rw---- 1 root input 13, 63 May 19 13:17 mice

This will list all input devices connected to your Raspberry Pi and you should see a few eventX files. In my case, the controller was the last device, which is event5, so let’s get more information to see if I was right. Run the following command:

udevadm info --name /dev/eventX --attribute-walk

and replace eventX with the number you’ve found in the previous step. In my case it was event5:

$ udevadm info --name /dev/event5 --attribute-walk
looking at parent device '/devices/platform/axi/1000120000.pcie/1f00300000.usb/xhci-hcd.1/usb3/3-1/3-1:1.0/gip0/gip0.0/input/input8':
    KERNELS=="input8"
    SUBSYSTEMS=="input"
    DRIVERS==""
    ATTRS{capabilities/abs}=="3003f"
    ATTRS{capabilities/ev}=="20000b"
    ATTRS{capabilities/ff}=="107030000 0"
    ATTRS{capabilities/key}=="7cdb000000000000 0 0 0 0"
    ATTRS{capabilities/led}=="0"
    ATTRS{capabilities/msc}=="0"
    ATTRS{capabilities/rel}=="0"
    ATTRS{capabilities/snd}=="0"
    ATTRS{capabilities/sw}=="0"
    ATTRS{id/bustype}=="0006"
    ATTRS{id/product}=="02ea"
    ATTRS{id/vendor}=="045e"
    ATTRS{id/version}=="0408"
    ATTRS{inhibited}=="0"
    ATTRS{name}=="Microsoft Xbox Controller"

Look at line ATTRS{name}=="Microsoft Xbox Controller" is what we are looking for, this is the name of the controller that we are going to use in our udev rule.

Writing udev rules

Now, we are going to create a rule that will execute a script whenever the controller is connected or disconnected. Create a file for a new rules:

sudo vim /etc/udev/rules.d/99-xbox-controller.rules

and add the following content:

ACTION=="add", SUBSYSTEM=="input", ATTRS{name}=="Microsoft Xbox Controller", RUN+="/home/jpomykala/moonlight/controller-connected.sh"
ACTION=="remove", SUBSYSTEM=="input", ATTRS{name}=="Microsoft Xbox Controller", RUN+="/home/jpomykala/moonlight/controller-disconnected.sh"

The first rule, will execute script at /home/jpomykala/moonlight/controller-connected.sh whenever the controller is connected, and it’s name is Microsoft Xbox Controller. The second rule will execute /home/jpomykala/moonlight/controller-disconnected.sh whenever the controller is disconnected.

The rules won’t work until we reload them, but before we do this, let’s create those scripts.

Logging and debugging

Before we start writing scripts, lets create a place where we can store logs, in my case I’ve chosen: /var/log/xbox-controller.log:

touch /var/log/xbox-controller.log
chmod +0777 /var/log/xbox-controller.log

I’ve set the permissions to 0777, so I can do anything with this file, but you can set it to 0644 if you want to be more restrictive.

When controller connects

controller-connected.sh script does a few things:

• creates a lockfile, because udev event fires 4 times, when my controller is connecting for some reason
• wakes my PC
• waits until I get a ping from my PC
• checks if the moonlight-qt is already running, and if not start it
• deletes a lockfile

When controller disconnects

controller-disconnected.sh script is much shorter as it only force kills the moonlight. It also requires a lockfile as the rule we’ve created fires 2 times.

Wrapping up

Remember to make all files executable via:

chmod +x controller-connected.sh
chmod +x controller-disconnected.sh

Now, let’s wrap this up and enable the rule by reloading them:

sudo udevadm control --reload-rules

To browse the logs use:

tail -f /var/log/xbox-controller.log

You can also check logs for udev via journalctl:

sudo journalctl -u systemd-udevd -f

Now your Raspberry Pi should wake up your PC and start streaming Steam Big Picture whenever you connect your Xbox Controller and stop the streaming whenever you disconnect it. 🥳

Further work

I plan to improve the final solution in a few ways:

• Wake on Lan part got naive assumptions; Whenever I’ve got ping from the PC I just wait a couple of seconds to make sure the Sunshine is ready to stream, this could be improved.
• Turning off PC; The current solution doesn’t turn off the PC at all, so this could be added. I didn’t find a way yet to do this without installing additional software on Windows.
• CEC and TV integration, I plan to use ‘cec-utils’ to automatically switch the TV output to the Raspberry Pi. For some reason, the CEC commands do nothing when I was executing them against my TV, so I give up for a moment.

Additionally, I wanted to add a small speaker to the Raspberry Pi to play a sound when I launch ‘moonlight-qt’. Furthermore, I would like to start some boot animation to make the startup process more visually appealing. This will add a more console feeling.

At the very beginning of my journey with documentation, I was testing GitBook software because it was shining and trendy at the time. It was a good move, because when you start something new, you want to avoid starting from scratch on every level. The main goal then is to deliver good quality code and value to the customers, all other things you can (or should) buy to save time.

Long story short, I wasn’t thrilled with GitBook after a couple of months because it didn’t fit to my needs. I didn’t like the style, and I was spending too much time on adjusting and fixing links and so on. I decided to go with my custom documentation, and surprisingly, everything went smoothly! The only concern was lack of good search option, which is available in all documentation solutions, or open-source Docusaurus. While searching for the best options and considering implementing my own search, I came across Algolia.

Installation

Start with Algolia search components and Algolia client installation:

npm install react-instantsearch-dom algoliasearch --save

Then install gray-matter, a Markdown parser, and globby for finding files:

npm install gray-matter globby --saveDev

Configuration

import algoliasearch from 'algoliasearch/lite';
import {connectStateResults, Hits, InstantSearch, SearchBox} from 'react-instantsearch-dom';

const searchClient = algoliasearch(
  'APP_ID',
  'SEARCH_API_KEY'
);

Results component

By default, Algolia <Hits/> component shows all results when search query is empty. I adjusted the code to show results only if there are any results and data are loaded.

const Results = connectStateResults(({searchState, searchResults, searching}) => {
  const hasQuery = searchState && searchState.query;
  const hasResults = (searchResults?.hits ?? []).length > 0;
  const isSearching = searching;
  if (hasQuery && hasResults) {
    return <Hits hitComponent={Hit}/>;
  }
  if (hasQuery && !hasResults && !isSearching) {
    return <div>No results 😔</div>
  }
  return null;
}
);

Hit component

Hit component is nothing but just one search result. I stripped my styling to make it easier to copy-paste. 😄

import React from "react";

function Hit(props: any) {
  const content = props?.hit?.content ?? "";
  const words = content.split(" ").length;
  return (<a href={props.hit.slug}>
    <div>
      <h3>{props?.hit?.frontmatter?.title ?? "no title"}</h3>
    </div>
    <p>{props?.hit?.frontmatter?.excerpt ?? ""}</p>
  </a>)
}

export default Hit;

Search component

Use InstantSearch component and search client, which you configured in the previous step. Put your index name and use Algolia SearchBox component and my custom Results component we created previously to change empty state behavior.

<InstantSearch indexName="simplelocalize-docs" searchClient={searchClient}>
    <SearchBox/>
    <Results/>
</InstantSearch>

I felt it would be better not to make it more complex than it needs to be, so I overwrite some CSS properties in my stylesheets to hide the search and reset buttons. I also added Bootstrap styling to the search box using SCSS @extend property. It’s simple and it does the job.

.ais-SearchBox-input {
  @extend .form-control;
}

.ais-SearchBox-submit {
  display: none;
}

.ais-SearchBox-reset {
  display: none;
}

Get markdown files to index

Now, it’s time to get all files that should be indexed and visible in the search results. I created a new index-docs.js file which will be executed after every successful build on CI/CD server. All my documentation pages are in /docs/ directory. So, I needed to write a script for converting it into an array of objects to populate Algolia search index.

import {globby} from 'globby';
import fs from "fs";
import matter from "gray-matter";
import algoliasearch from 'algoliasearch';

const pages = await globby([
  'docs/',
]);

const objects = pages.map(page => {
  const fileContents = fs.readFileSync(page, 'utf8')
  const {data, content} = matter(fileContents)
  const path = page.replace('.md', '');
  let slug = path === 'docs/index' ? 'docs' : path;
  slug = "/" + slug + "/"
  return {
    slug,
    content,
    frontmatter: {
      ...data
    }
  }
})

//algolia update index code

• I’m getting all markdown files from /docs/ directory with globby,
• reading content of the files with fs,
• parsing files with gray-matter for Markdown,
• and doing some magic tricks to convert file path to slugs which are used.

In my case, slugs are the just file paths, where the file path looks like this /docs/{category}/{title}.md, for example: /docs/integrations/next-translate.md, so slug will look like this: /docs/integrations/next-translate/.

In the end I’m getting an array of objects which looks like this:

[
    {
      "slug": "/docs/integrations/next-translate/",
      "content": "My article content for indexing",
      "frontmatter": {
        "category": "Integrations",
        "date": "2022-01-20",
        "some-other-properties": "properties"
      }
    }
]

Update Algolia index

Algolia provides a really simple and easy to use JavaScript client, so there is no magic here. We are acquiring our index, and saving objects which we created in the previous step.

const client = algoliasearch(
  'APP_ID',
  'ADMIN_API_KEY'
);
const index = client.initIndex("simplelocalize-docs")
index.saveObjects(objects, {
  autoGenerateObjectIDIfNotExist: true
});

Include index update in package.json

{
  "name": "simplelocalize-docs",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build && next export -o build/ && i18n:download && index:docs",
    "index:docs": "npx ts-node --skip-project index-docs.mjs",
    "i18n:upload": "simplelocalize upload",
    "i18n:download": "simplelocalize download"
  }
}

You can execute the script manually by running npm run index:docs.

And that’s it! See the search in action on SimpleLocalize documentation page.

CodeBuild is AWS-hosted tool for building software applications and 3 months after stable Java 11 release still it does not support anything newer than Java 9. Time is up, now we will build our own build environment which will support Java 11 and Java 12 in future right after stable release.

Requirements

• AWS CLI
• Docker
• Amazon ECR

We are going to need nothing special for this. AWS CLI with AWS account obliviously. Installed docker on our local machine to build image, and some basic knowledge how docker works and how proper Dockerfile should looks like. Basically we will create build environment which will be used during CodeBuild process using docker images. After that we will push created image to Amazon ECR. ECR is container registry like docker hub but managed by Amazon. Eventually we will use our image as build environment. Now it’s time to start “fixing” CodeBuild.

Build environment

First of all we need to should create our own Dockerfile with environment. I used official maven image from Docker Hub, we can choose there maven and Java version. [https://hub.docker.com//maven/](https://hub.docker.com//maven/) I added few environment variables and own CMD to show mvn --version on start instead running just mvn, because this leads to failing CodeBuild process.

FROM maven:3.6-jdk-11
MAINTAINER Jakub Pomykała <hello@jpomykala.me>

ENV PATH                   $PATH:$JAVA_HOME/bin
ENV JAVA_OPTS              "-server -XX:+UseG1GC -XX:+UseStringDeduplication -XX:+OptimizeStringConcat -Dsun.net.inetaddr.ttl=60"
ENV HEAP_SPACE             "-Xms512m -Xmx2g"

CMD ["mvn", "--version"]

Pushing to ECR

Now we can create new repository on Amazon ECR with name java11-codebuild-environemnt.

Sign in to ECR with

$(aws ecr get-login --no-include-email --<YOUR REGION>)

Build docker image with:

docker build -t java11-codebuild-environemnt .

and try to run it using:

docker run java11-codebuild-environemnt:latest

and ensure that maven displays installed version.

If everything work as expected, we can tag and push our image to ECR service.

docker tag java11-codebuild-environment:latest <YOUR_ECR_URL>/java11-codebuild-environment:latest
docker push <YOUR_ECR_URL>/java11-codebuild-environment:latest

Before we start using our container we need to setup proper access policy for CodeBuild service. This need to be done using internal ECR policy management (not the standard AWS roles/policies!) Amazon ECR > Repositories > Permissions > Edit policy JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CodeBuildAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "codebuild.amazonaws.com"
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ]
    }
  ]
}

We allow the CodeBuild service to get docker images, download them and check their availability.

CodeBuild configuration

The last step is to configure CodeBuild environment, like bellow.

And here we go! We can finally use the latest Java features and push it to the production right away! Next version is scheduled to March 2019, so we will go through this steps again but on Dockerfile we will just change maven:3.6-jdk-11 to maven:3.6-jdk-12. Even now we can do this because we can find docker images with beta releases of Java 12.

Please remember that this is not a step-by-step tutorial, I’m describing overall architecture with code (copy-paste ready certification). If you have any remarks, then let me know or create a Github issue. 😉

Requirements

• minimal knowledge about Amazon Web Services
• basic JavaScript skills

Used technologies

• Amazon Lambda
• Amazon SES
• Amazon API Gateway

Build environment

If you are familiar with used technologies the diagram should be pretty straightforward for you.

Static web page should be gathering data from contact form, validate and send them using XHR Fetch, jQuery or in other way to API Gateway by POST method. API Gateway will invoke Lambda function, and the Lambda function will invoke our JavaScript code where we parse POST request, do some custom logic and call sendEmail(...) on SES service.

0. Verify your e-mail address

SES e-mail address verification can be done here (eu-west-1)

1. Lambda Function

We will start with creating AWS Lambda function and choosing a NodeJS 8.1 environment.

The full code can be found on GitHub Gist

import aws-sdk

Once we have prepared environment, then we can start to implement the function. A first important thing is that we need to import aws-sdk to use SES and other Amazon services.

var aws = require("aws-sdk");

Link to aws-sdk documentation

AWS Lambda responses

Success and error responses. This part is more important than you think. If we return wrong JSON from lambda function to API Gateway, the client (contact form in this case) will get HTTP 500 status. Code will be invoked and email sent anyway, but it’s just a good practise to follow the documentation and just don’t return 500 status codes intentionally.

const successResponse = {
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json",
    },
    "body": JSON.stringify({ message: ":)" }),
    "isBase64Encoded": false
};

const errorResponse = {
    "statusCode": 500,
    "headers": {
        "Content-Type": "application/json",
    },
    "body": JSON.stringify({ message: "something bad happened, check logs" }),
    "isBase64Encoded": false
};

Check is domain allowed

By using this function we can easily turn on and off e-mail sending from certain domains.

const extractDomain = (emailAddress) => {
    const emailSplit = emailAddress.split('@');
    const arraySize = emailSplit.length;
    if(arraySize < 2){
        console.warn("Domain not found for email:", emailAddress);
        return "";
    }
    
    return emailSplit[arraySize - 1];
}

 const allowedDomains = ['simplelocalize.io', 'jpomykala.com', 'yourdomain.com'];
 const isDomainAllowed = (domain) => allowedDomains.includes(domain);

E-mail message

This is a true strength of this solution. We are passing whole Javascript object from contact form to e-mail formatted with <pre></pre> tags and JSON.stringify.

const getEmailMessage = (request) => {
    return {
        Body: {
            Html: {
                Charset: "UTF-8",
                Data: `
                    <body>
                    <p>${request.message}</p>
                    <pre>${JSON.stringify(request, undefined, 2)}</pre>
                    </body>
                    `
            }
        },
        Subject: {
            Charset: "UTF-8",
            Data: `New submission`
        }
    }
}

Send e-mail with SES service

The most important part of this function is of course sending email by SES. Let’s create a JSON params object with a message, subject and all other SES options which can be found here.

 const params = {
        Destination: {
            ToAddresses: [sendToEmail]
        },
        Message: emailMessage,
        Source: `${request.name || "Unknown"} <your_verified_email_in_ses@gmail.com>`,
        ReplyToAddresses: [request._replyTo]
    };


    const sendPromise = new aws.SES()
        .sendEmail(params)
        .promise();

    await sendPromise
        .then(data => {
            console.log(`E-mail sent to ${sendToEmail}`);
            console.log(successResponse);
            callback(null, successResponse);
        })
        .catch(err => {
            console.log("E-mail NOT sent", err);
            console.log(errorResponse);
            callback(errorResponse);
        });

Now we can deploy our function and move to the API Gateway.

2. Set up API Gateway

Setting up API Gateway for Lambda functions, should be straightforward. There is no need to code anything, just click-and-play configuration. In this case I set up my endpoint to receive any HTTP method. For working contact form you will need only http/post method.

Things to remember

• Every time we change something on endpoint configuration we need deploy API again to see changes. Use: Actions -> Deploy API
• Remember about setting up CORS while using API Gateway. Use: Actions -> Enable CORS

3. Contact form example

HTML form

<form action="#" id="callbackForm" class="contact-form">
    <div class="form-group">
        <label for="email">Email</label>
        <input type="email" required id="email" class="form-control" placeholder="" autocomplete="email" name="email" />
    </div>
    <div class="form-group">
        <label for="name">Message</label>
        <input id="message" type="text" class="form-control" placeholder="" name="message" />
    </div>
    <button type="submit" id="sendMessageButton" class="btn btn-primary btn-block">
        Send message
    </button>
</form>

JavaScript to submit the form

<script>
        $("#callbackForm").submit(function(e) {
            e.preventDefault();
            var replyTo = $("#email");
            var message = $("#message");
            var data = {
                "_sendTo": "<your_email>",
                "_replyTo": replyTo.val(),
                "message": message.val()
            };
            var url = "<API_GATEWAY_URL>";
            $.ajax({
                url: url,
                type: 'POST',
                crossDomain: true,
                data: JSON.stringify(data),
                dataType: 'json',
                contentType: "application/json"
            });
        });
</script>

Conclusion

We can scale this technique to multiple web pages with ease, but this solution in current form has few downsides. For now the only one protection against DDoS or some similar attack is rate limiter included in Lambda function. Right now there is no bot protection, no captcha or something like that. We can add Google re-captcha on the contact form and setup rate limiting on both API Gateway and Lambda function, to avoid unnecessary costs.

Update 2021-02-23

So far I didn’t have any issues with this solution. I’ve never received any SPAM or message from a bot. 😄

Server side - Spring Framework

We will start from adding proper dependency in pom.xml on backend side. In my case it the latest stable version was 2.0.2.RELEASE.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-websocket</artifactId>
</dependency>

Basic websockets configuration in Spring is easy as copy-paste configuration files and handle connection on client side. Create new configuration class annotated with @Configuration and @EnableWebSocketMessageBroker and extend it with AbstractWebSocketMessageBrokerConfigurer.

@Autowired
private ThreadPoolTaskScheduler threadPoolTaskScheduler;

@Override
public void configureMessageBroker(MessageBrokerRegistry config) {
  config
      .enableSimpleBroker("/queue")
      .setTaskScheduler(threadPoolTaskScheduler);
}

@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
  registry
      .addEndpoint("/ws")
      .setAllowedOrigins(ALLOWED_ORIGINS)
      .withSockJS()
      .setTaskScheduler(threadPoolTaskScheduler);
}

Remember to provide TaskScheduler which is required to sending messages. In above example I also configured CORS by using list of allowed origins from *.yml configuration.

Support for websocket authentication

Unfortunately as far as I know Spring websockets does not support authentication, so we need to implement it on our own. I came up with very simple idea, I’m authenticating user on SessionSubscribeEvent.

@EventListener(SessionSubscribeEvent.class)
public void onWebSocketSessionsConnected(SessionSubscribeEvent event) {
  Message<byte[]> eventMessage = event.getMessage();
  String token = getAuthorizationToken(eventMessage);
  // Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  // do whatever you need with user, throw exception if user should not be connected
  // ...
}

private String getAuthorizationToken(Message<byte[]> message) {
  StompHeaderAccessor headerAccessor = StompHeaderAccessor.wrap(message);

  List<String> authorization = Optional.of(headerAccessor)
      .map($ -> $.getNativeHeader(WebSocketHttpHeaders.AUTHORIZATION))
      .orElse(Collections.emptyList());
  // if header does not exists returns null instead empty list :/

  return authorization.stream()
      .findFirst()
      .orElseThrow(() -> new IllegalArgumentException("Missing access token in Stomp message headers"));
}

Now we are ready to send data to connected clients! In my application I’m using application events to send updates with ease to connected companies from any place in code. In my case I’m sending update to dashboard page on every new transaction for company. Every user subscribe his company message channel and get update on every transaction or alert if occurred.

@Autowired
private SimpMessagingTemplate webSocket;
	
@EventListener(UpdateDashboardRequestEvent.class)
public void onClientUpdate(UpdateDashboardRequestEvent request) {
  String companyName = request.getCompanyName();
  log.info("Sending dashboard update to {}", companyName);
  List<String> connectedCompanies = connectedUsersService.getConnectedCompanies();
  // when user/companies successfully connects to server I add him to list of connected users/companies
  
  boolean isConnected = connectedCompanies.contains(companyName);

  if (!isConnected) {
    log.warn("Company is not on connection list");
    return;
  }
  String companyDestinationUrl = "/queue/" + updateForCompany + "/company";
  Response response = ... 
  //response will be converted using message converters like on regular class annotated with @RestController
  webSocket.convertAndSend(companyDestinationUrl, response);
}

Client side - ReactJS

On client side I’m using two additional dependencies, one for SockJS and second for webstomp of course.

sockjs-client - official SockJS client

webstomp-client - community developed webstomp client

import React from "react";
import SockJS from "sockjs-client";
import webstomp from "webstomp-client";

// types of Props & State

class Dashboard extends React.Component<Props, State> {
  subscribeUpdates = () => {
    const {companyName} = this.props;
    this.topicSubscription = this.client.subscribe(
        `/queue/${companyName}/company`, this.onUpdate,
        {Authorization: `Bearer ${localStorage.getItem(ACCESS_TOKEN_KEY)}`},
    );
  };

  connectSocket = () => {
    const token = localStorage.getItem(ACCESS_TOKEN_KEY);
    //pure accessToken without 'Bearer' part
    const sockjs = new SockJS(
        `${process.env.REACT_APP_API_URL}/ws`, null,
        { headers: {Authorization: `Bearer ${token}` }},
    );
    this.client = webstomp.over(sockjs, { debug: false });
    this.client.connect({Authorization: `Bearer ${token}`}, this.subscribeUpdates);
  };

  componentDidMount() {
    this.connectSocket();
  }
  
  onUpdate = ({body = "{}"}) => {
    const message = JSON.parse(body)
    // do whatever you want, eg. setState to update view
  }

Conclusions

Done! 🌱 Below is an example how it looks like in my application. In terminal, we see logs from the server for test demo company with a vending machines. Every time machine sold a product data are sent to our server, and then transaction is validated and eventually inserted to database. In the end I’m sending event UpdateDashboardRequestEvent to update the dashboard with WebSockets.