bumble-auracast/README.md

Local HTTP/HTTPS Setup with Custom CA

This project provides a dual-port Streamlit server setup for local networks:

• HTTP available on port 8502
• HTTPS (trusted with custom CA) available on port 8503

How it works

• A custom Certificate Authority (CA) is generated for your organization.
• Each device/server is issued a certificate signed by this CA.
• Customers can import the CA certificate into their OS/browser trust store, so the device's HTTPS connection is fully trusted (no browser warnings).

Usage

1. Generate Certificates

   • Run generate_ca_cert.sh in src/auracast/server/.
   • This creates:
     • certs/ca/ca_cert.pem / ca_key.pem (CA cert/key)
   • Distribute ca_cert.pem or ca_cert.crt to customers for installation in their trust store.
   • This is a one-time operation for your organization.

2. Start the Server

   • Run run_http_and_https.sh in src/auracast/server/.
   • This starts:
     • HTTP Streamlit on port 8500
     • HTTPS Streamlit on port 8501 (using the signed device cert)

3. Client Trust Setup

   • Customers should install ca_cert.pem in their operating system or browser trust store to trust the HTTPS connection.
   • After this, browsers will show a secure HTTPS connection to the device (no warnings).

Why this setup?

• WebRTC and other browser features require HTTPS for local devices.
• Using a local CA allows trusted HTTPS without needing a public certificate or exposing devices to the internet.
• HTTP is also available for compatibility/testing.

Advertise Hostname with mDNS

cd src/auracast/server
sudo ./provision_domain_hostname.sh <new_hostname> <new_domain>

• Example:

  sudo ./provision_domain_hostname.sh box1 auracast.local
  

• The script will:
  • Validate your input (no dots in hostname)
  • Set the system hostname
  • Update /etc/hosts
  • Set the Avahi domain in /etc/avahi/avahi-daemon.conf
  • Restart Avahi
  • Generate a unique per-device certificate and key signed by your CA, stored in certs/per_device/<hostname>.<domain>/.
  • The certificate will have a SAN matching the device's mDNS name (e.g., box1-summitwave.local).

---

Troubleshooting & Tips

• Use .local domain (e.g., box1-summitwave.local) - most clients will not resolve multi-label domains.
• Hostnames must not contain dots (.). Only use single-label names for the system hostname.
• Avahi domain can be multi-label (e.g., auracast.local).
• Clients may need libnss-mdns installed and /etc/nsswitch.conf configured with mdns4_minimal and mdns4 for multi-label mDNS names.
• If you have issues with mDNS name resolution, check for conflicting mDNS stacks (e.g., systemd-resolved, Bonjour, or other daemons).
• Some Linux clients may not resolve multi-label mDNS names via NSS—test with avahi-resolve-host-name and try from another device if needed.

---

After completing these steps, your device will be discoverable as <hostname>.<domain> (e.g., box1.auracast.local) on the local network via mDNS.

---

Checking Advertised mDNS Services

Once your device is configured, you can verify that its mDNS advertisement is visible on the network:

• List all mDNS services:

  avahi-browse -a
  

  Look for your hostname and service (e.g., box1.auracast.local).
• Check specific hostname resolution:

  avahi-resolve-host-name box1.auracast.local
  avahi-resolve-host-name -4 box1.auracast.local  # IPv4 only
  avahi-resolve-host-name -6 box1.auracast.local  # IPv6 only
  

Run the application with local webui

• for microphone streaming via the browser, https is required
• poetry run multicast_server.py
• sudo -E PATH="$PATH" bash ./start_frontend_https.sh
• bash start_mdns.sh