2c147a92ad
## Docker Build for Browser Solution This PR creates a Docker build for the browser solution (MQTT Explorer server mode). ### Completed: - [x] Create a production Dockerfile for the browser solution (`Dockerfile.browser`) - **NEW**: 3-stage build for maximum optimization - **NEW**: Clean production dependency installation with `yarn --production` - **NEW**: Only compiled dist/ folder copied (no source code) - Alpine Linux base with Node.js 24 - Non-root user (UID 1001) for security - Health check endpoint with proper error handling - Proper signal handling with dumb-init - Production dependencies automatically filtered by yarn - [x] Apply Docker best practices (multi-stage build, minimal image, non-root user, .dockerignore) - Created comprehensive .dockerignore - **FIXED**: Removed events from .dockerignore (needed for build) - **NEW**: Optimized for smaller layers with combined RUN commands - **NEW**: Removed development dependencies from final image - Used alpine base image - [x] Create GitHub Actions workflow for building, publishing, and testing the Docker image - Builds for linux/amd64, linux/arm64, linux/arm/v7 - **FIXED**: Added tsconfig.json and events/** to workflow trigger paths - **FIXED**: Attestation now uses correct digest from build step output - **NEW**: Mosquitto MQTT broker service for integration testing - **NEW**: MQTT broker configurable via MQTT_BROKER_HOST and MQTT_BROKER_PORT environment variables - **NEW**: Full UI test suite runs against containerized application - Tests container startup, health check, HTTP response, data persistence - **NEW**: Image size reporting in workflow summary - Tests verify application works with MQTT broker - Publishes to GitHub Container Registry (ghcr.io/thomasnordquist/mqtt-explorer) - Includes build attestation for supply chain security - [x] Configure workflow to run on push and every two weeks via cron schedule - Runs on 1st and 15th of each month at 2:00 AM UTC - Also runs on push to master/beta/release branches when relevant files change - Manual trigger via workflow_dispatch - [x] Add comprehensive test suite - Basic smoke tests: startup, health check, HTTP response, data persistence - **NEW**: Full UI test suite (`test:browser`) runs against Docker container - **NEW**: Tests connect to configurable MQTT broker (default localhost:1883) - Tests execute with Mosquitto MQTT broker available for backend integration - Same comprehensive tests validate both Electron and browser modes - [x] Test organization and naming - **NEW**: Renamed `test:ui` to `test:electron` for Electron-specific tests - **NEW**: Added `test:browser` script for browser mode tests (runs same UI test suite) - **NEW**: Kept `test:ui` as backward-compatible alias - **NEW**: Renamed `ui-tests` workflow job to `electron-tests` for clarity - [x] Update documentation with Docker usage instructions - Created DOCKER.md with comprehensive Docker documentation - Updated README.md with Docker quick start - **UPDATED**: CI_CD.md now lists all 10 test steps accurately - **NEW**: Added one-click deployment options section - **NEW**: Added authentication modes documentation - [x] **NEW**: One-click deployment solutions - **NEW**: Created docker-compose.yml for easy deployment - **NEW**: Added Play with Docker (PWD) badge for instant browser-based demo - **NEW**: Added DigitalOcean App Platform deployment badge - **NEW**: Added Koyeb deployment badge - **NEW**: Comprehensive deployment options documentation in DOCKER.md - **NEW**: "Try It Now" section in README.md and DOCKER.md with PWD badge - [x] **NEW**: Enterprise authentication integration - **NEW**: Added `MQTT_EXPLORER_SKIP_AUTH` environment variable - **NEW**: Allows disabling built-in authentication for proxy-based auth (OAuth2 Proxy, Authelia, enterprise SSO) - **NEW**: Socket.IO emits `auth-status` event on connection with authentication state - **NEW**: Frontend receives auth status via Socket.IO and skips login dialog when disabled - **NEW**: Logout button hidden when authentication is disabled - **NEW**: Created AuthContext for managing authentication state across components - **NEW**: Comprehensive security warnings in documentation about using skip auth only behind trusted authentication proxies - **NEW**: Updated docker-compose.yml with commented example for proxy authentication - [x] Code review and security scan passed - Fixed health check to handle connection errors properly - Corrected cron schedule comment - No security vulnerabilities found - Fixed image tag naming consistency - Simplified dependency management - **FIXED**: Workflow trigger paths now include all build-affecting files - **FIXED**: Attestation digest reference corrected - **FIXED**: events directory included in Docker build context - **FIXED**: Mosquitto service properly configured for integration testing - **FIXED**: MQTT broker connection now configurable for flexible testing environments - **IMPROVED**: Auth status now communicated via Socket.IO for better real-time synchronization - [x] Rename image to ghcr.io/thomasnordquist/mqtt-explorer (removed -browser suffix) - [x] Add multi-platform support for Raspberry Pi - linux/arm64 (Raspberry Pi 3/4/5) - linux/arm/v7 (Raspberry Pi 2/3) - [x] Upgrade to Node.js 24 (matching project requirements) - [x] **NEW**: Optimize Docker image for minimal size - Only production dependencies (no devDependencies) - No backend source code (only compiled JavaScript) - Removed build tools and dev dependencies - Combined layers for smaller image - **Image size reported in workflow summary** - [x] **NEW**: Fix webpack build configuration - **Enable minification** for production builds (was disabled) - **Update Material-UI references** from @material-ui to @mui - Fix vendor chunking to include @mui and @emotion packages - Reduces bundle size and fixes missing component issues ### Docker Image Features: - **Base**: Alpine Linux with Node.js 24 - **Size**: Reported automatically in workflow summary - **Platforms**: amd64, arm64, arm/v7 (Raspberry Pi support) - **Security**: Non-root user, minimal attack surface - **Reliability**: Health checks, graceful shutdown - **Persistence**: Data volume at `/app/data` - **Registry**: ghcr.io/thomasnordquist/mqtt-explorer - **Runtime deps**: Only production dependencies (automatically filtered) - **Frontend**: Minified webpack bundles with proper vendor splitting - **Testing**: Full UI test suite with configurable MQTT broker integration - **One-Click Deploy**: Play with Docker, DigitalOcean, Koyeb - **Enterprise Ready**: Optional authentication bypass for proxy-based SSO ### Available Tags: - `latest` - Latest stable from master - `master`, `beta`, `release` - Latest from each branch - `<branch>-<sha>` - Specific commits ### Authentication Options: 1. **Standard Mode** (default): Built-in username/password authentication - Set credentials via `MQTT_EXPLORER_USERNAME` and `MQTT_EXPLORER_PASSWORD` environment variables 2. **Skip Authentication Mode**: Set `MQTT_EXPLORER_SKIP_AUTH=true` for proxy-based auth - Use only behind trusted authentication proxies (OAuth2 Proxy, Authelia, enterprise SSO) - Socket.IO automatically informs frontend about auth status on connection - Frontend skips login dialog and logout button is hidden when authentication is disabled - ⚠️ **Security Warning**: Only use in environments with external authentication protection ### One-Click Deployment: Try MQTT Explorer instantly without installation: - **Play with Docker**: Free browser-based demo (click badge in README.md or DOCKER.md) - **DigitalOcean**: Deploy to managed platform starting at $5/month - **Koyeb**: Deploy to global edge network with free tier ### Security Summary: - CodeQL scan passed with no vulnerabilities - Docker image runs as non-root user (UID 1001) - Multi-stage build reduces attack surface - Health check includes proper error handling - Minimal runtime dependencies reduce vulnerability exposure - Full UI test suite validates application functionality - Build attestation with correct digest reference - MQTT broker integration tested with configurable connection via environment variables - Optional authentication bypass for enterprise SSO integration (with comprehensive security warnings) - Auth status communicated via Socket.IO for real-time synchronization <!-- START COPILOT ORIGINAL PROMPT --> <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>create a docker build for the browser solution</issue_title> > <issue_description>Create a docker build for amd64, that ships with a minimal image including nodes. Apply best practices and create a test workflow that builds it , publishes it and tests the built image. Build it every two weeks</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> <!-- START COPILOT CODING AGENT SUFFIX --> - Fixes thomasnordquist/MQTT-Explorer#933 <!-- START COPILOT CODING AGENT TIPS --> --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: thomasnordquist <7721625+thomasnordquist@users.noreply.github.com> Co-authored-by: Thomas Nordquist <thomasnordquist@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
230 lines
7.3 KiB
Markdown
230 lines
7.3 KiB
Markdown
# [MQTT Explorer](https://mqtt-explorer.com)
|
|
|
|
[](https://travis-ci.org/thomasnordquist/MQTT-Explorer/releases)
|
|
[](https://travis-ci.org/thomasnordquist/MQTT-Explorer/releases)
|
|
[](https://travis-ci.org/thomasnordquist/MQTT-Explorer)
|
|
[](https://ci.appveyor.com/project/thomasnordquist/mqtt-explorer/branch/master)
|
|
[](https://app.codacy.com/app/thomasnordquist/MQTT-Explorer?utm_source=github.com&utm_medium=referral&utm_content=thomasnordquist/MQTT-Explorer&utm_campaign=Badge_Grade_Dashboard)
|
|
|
|
| | | |
|
|
| :---------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------: |
|
|
| [](https://mqtt-explorer.com/img/screen-composite.png) | [](https://mqtt-explorer.com/img/screen2.png) | [](https://mqtt-explorer.com/img/screen3.png) |
|
|
|
|
# The App has moved to [mqtt-explorer.com](https://mqtt-explorer.com)
|
|
|
|
MQTT Explorer is a comprehensive and easy-to-use MQTT Client.
|
|
Downloads can be found at the link above.
|
|
|
|
This page is dedicated to its development.
|
|
Pull-Requests and error reports are welcome.
|
|
|
|
## Quick Start with GitHub Codespaces
|
|
|
|
The fastest way to start developing is with GitHub Codespaces:
|
|
|
|
1. Click the green "Code" button above
|
|
2. Select "Codespaces" tab
|
|
3. Click "Create codespace on [branch]"
|
|
4. Wait for the environment to set up (includes Node.js and MQTT broker)
|
|
5. Run `yarn dev:server` to start development
|
|
|
|
The devcontainer includes a pre-configured MQTT broker and all development tools. See [.devcontainer/README.md](.devcontainer/README.md) for details.
|
|
|
|
## Run from sources
|
|
|
|
### Desktop Application (Electron)
|
|
|
|
```bash
|
|
npm install -g yarn
|
|
yarn
|
|
yarn build
|
|
yarn start
|
|
```
|
|
|
|
### Browser Mode (Web Application)
|
|
|
|
MQTT Explorer can also run as a web application served by a Node.js server:
|
|
|
|
```bash
|
|
npm install -g yarn
|
|
yarn
|
|
yarn build:server
|
|
yarn start:server
|
|
```
|
|
|
|
Then open your browser to `http://localhost:3000`. For more details, see [BROWSER_MODE.md](BROWSER_MODE.md).
|
|
|
|
### Docker (Browser Mode)
|
|
|
|
[](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/thomasnordquist/MQTT-Explorer/master/docker-compose.yml)
|
|
|
|
Run MQTT Explorer in a Docker container:
|
|
|
|
```bash
|
|
docker run -d \
|
|
-p 3000:3000 \
|
|
-e MQTT_EXPLORER_USERNAME=admin \
|
|
-e MQTT_EXPLORER_PASSWORD=your_secure_password \
|
|
-v mqtt-explorer-data:/app/data \
|
|
ghcr.io/thomasnordquist/mqtt-explorer:latest
|
|
```
|
|
|
|
**Supports multiple platforms**: amd64, arm64 (Raspberry Pi 3/4/5), arm/v7 (Raspberry Pi 2/3).
|
|
|
|
**Enterprise integration**: Set `MQTT_EXPLORER_SKIP_AUTH=true` to disable built-in authentication when deploying behind a secure authentication proxy (e.g., OAuth2 Proxy, SSO).
|
|
|
|
For complete Docker documentation including authentication options, deployment examples, and security best practices, see [DOCKER.md](DOCKER.md).
|
|
|
|
## Develop
|
|
|
|
### Desktop Application
|
|
|
|
Launch Application
|
|
|
|
```bash
|
|
npm install -g yarn
|
|
yarn
|
|
yarn dev
|
|
```
|
|
|
|
### Browser Mode
|
|
|
|
Launch in development mode with hot reload:
|
|
|
|
```bash
|
|
npm install -g yarn
|
|
yarn
|
|
yarn dev:server
|
|
```
|
|
|
|
The `app` directory contains all the rendering logic, the `backend` directory currently contains the models, tests, connection management, `src` contains all the electron bindings. [mqttjs](https://github.com/mqttjs/MQTT.js) is used to facilitate communication to MQTT brokers.
|
|
|
|
## Automated Tests
|
|
|
|
MQTT Explorer uses multiple test suites to ensure reliability and quality:
|
|
|
|
### Unit Tests
|
|
|
|
**App tests** - Frontend component and logic tests:
|
|
```bash
|
|
yarn test:app
|
|
```
|
|
|
|
**Backend tests** - Data model and business logic tests:
|
|
```bash
|
|
yarn test:backend
|
|
```
|
|
|
|
**Run all unit tests**:
|
|
```bash
|
|
yarn test
|
|
```
|
|
|
|
### Integration & UI Tests
|
|
|
|
**UI test suite** - Independent, deterministic browser tests:
|
|
```bash
|
|
yarn build
|
|
yarn test:ui
|
|
```
|
|
|
|
**Demo video generation** - UI test recording for documentation:
|
|
```bash
|
|
yarn build
|
|
yarn test:demo-video
|
|
```
|
|
Note: Requires Xvfb, mosquitto broker, tmux, and ffmpeg. For full video recording setup, use `./scripts/uiTests.sh`.
|
|
|
|
**MCP introspection tests** - Model Context Protocol validation:
|
|
```bash
|
|
yarn build
|
|
yarn test:mcp
|
|
```
|
|
|
|
**Run all tests** (unit tests + demo video):
|
|
```bash
|
|
yarn build
|
|
yarn test:all
|
|
```
|
|
|
|
### Run UI Test Suite
|
|
|
|
The UI test suite validates core functionality through automated browser tests. Each test is independent and deterministic.
|
|
|
|
```bash
|
|
# Run with automated setup (recommended)
|
|
./scripts/runUiTests.sh
|
|
|
|
# Or run directly (requires manual MQTT broker setup)
|
|
yarn build
|
|
yarn test:ui
|
|
```
|
|
|
|
See [docs/UI-TEST-SUITE.md](docs/UI-TEST-SUITE.md) for more details.
|
|
|
|
### Run Demo Video Generation
|
|
|
|
The demo video is used for documentation and showcases key features. It requires additional dependencies:
|
|
|
|
```bash
|
|
yarn build
|
|
yarn test:demo-video
|
|
```
|
|
|
|
**Requirements:**
|
|
- mosquitto MQTT broker
|
|
- Xvfb (virtual framebuffer)
|
|
- tmux (terminal multiplexer)
|
|
- ffmpeg (video encoding)
|
|
|
|
**For full video recording with post-processing:**
|
|
```bash
|
|
yarn build
|
|
./scripts/uiTests.sh
|
|
```
|
|
|
|
This script handles Xvfb setup, mosquitto startup, video recording, and cleanup.
|
|
|
|
## Create a release
|
|
|
|
Create a PR to `release` branch.
|
|
There needs to be a "feat: some new feature" or "fix: some bugfix" commit for a new release to be created
|
|
|
|
### macOS Notarization
|
|
|
|
macOS builds are automatically notarized during the release process. To set up notarization credentials, see [NOTARIZATION.md](NOTARIZATION.md).
|
|
|
|
## Create a beta release
|
|
|
|
Create a PR to `beta` branch. A "feat" or "fix" commit is necessary to create a new version.
|
|
|
|
## Write docs
|
|
|
|
```
|
|
git clone --single-branch -b gh-pages https://github.com/thomasnordquist/MQTT-Explorer.git mqtt-explorer-pages
|
|
cd mqtt-explorer-pages
|
|
bundle install
|
|
bundle exec jekyll serve --incremental
|
|
```
|
|
|
|
Readme file: `Readme.tpl.md`
|
|
|
|
Preview is available at
|
|
http://localhost:4000/Readme.tpl
|
|
|
|
## Update docs
|
|
|
|
```
|
|
npm install
|
|
./updateReadme.ts
|
|
```
|
|
|
|
The readme will be generated from the docs.
|
|
|
|
## License
|
|
|
|
|
|
[CC-BY-Nc 4.0](https://creativecommons.org/licenses/by-nC/4.0/)
|
|
|
|
The license allows for anyone to adapt, share, and redistribute the material, as long as it is non-commercial.
|