bxweb

The HTTP server for the Blinken’ Xmas project. Provides a simple web-interface for building tree animations and serving them over MQTT to the Pico connected to the neopixels on the tree.

Synopsis

bxweb [-h] [--version] [--broker-address ADDR] [--broker-port NUM]
      [--topic TOPIC] [--httpd-bind ADDR] [--httpd-port PORT]
      [--no-production] [--production] [--db FILE]

Options

-h, --help: Show the help message and exit

--version: Show program’s version number and exit

--broker-address ADDR: The address on which to find the MQTT broker. Default: broker

--broker-port NUM: The port on which to find the MQTT broker. Default: 1883

--topic TOPIC: The topic on which the Pico W is listening for messages. Default: blinkenxmas

--httpd-bind ADDR: The address on which to listen for HTTP requests. Default: 0.0.0.0

--httpd-port PORT: The port to listen for HTTP requests. Default: 8000

--no-production, --production: If specified, run in production mode where an internal server error will not terminate the server and will not output a stack trace (default: no)

--db FILE: The SQLite database to store presets in. Default: /var/local/cache/blinkenxmas/presets.db

Configuration

This application is a basic no-frills HTTP server producing the web front-end. While it is multi-threaded, it isn’t intended to scale to large numbers of users, because there’s no need with a single tree! Moreover, there’s no authentication, and no assumptions should be made as to the application’s security. To run this on the standard port 80 (or 443), you are recommended to place the application on an unprivileged port (e.g. the default of 8000), running as an unprivileged user, and place a reverse proxy (like nginx) in front of it.

A sample systemd.unit(5) for execution of the application is:

/etc/systemd/system/blinkenxmas-web.service

[Unit]
Description=Blinkenxmas web service
After=network.target local-fs.target

[Service]
Type=simple
ExecStart=/usr/local/bin/bxweb --production
Restart=on-failure

[Install]
WantedBy=multi-user.target

Note

At the time of writing, the application does not support systemd’s notify mechanism, or socket activation.

A sample reverse proxy for nginx is:

/etc/nginx/sites-available/blinkenxmas

server {
    listen 80;
    listen [::]:80;

    location / {
        proxy_pass http://localhost:8000/;

        # Limit requests to a reasonable size
        client_max_body_size 10m;
        client_body_buffer_size 128k;

        proxy_set_header Host $host;
        # Not currently used by the application
        add_header X-Frame-Options "sameorigin";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Environment

DEBUG: If set to “1”, the application will produce a full stack-trace on any fatal exception. If set to “2”, the application will jump to PDB for exception post-mortem on any fatal exception.