This documentation is part of the "Projects with Books" initiative at zenOSmosis.
The source code for this project is available on GitHub.
Continuous Integration
Loading…
Continuous Integration
Relevant source files
Purpose and Scope
This page documents the automated testing workflow defined in .github/workflows/ci.yml:1-43 that validates the mosquitto service can be successfully deployed. The workflow triggers on push and pull request events to the main branch and verifies the Mosquitto MQTT broker container starts and reaches a running state.
Scope : Tests the mosquitto service only. The cloudflared service is excluded because it requires CLOUDFLARE_TUNNEL_TOKEN which cannot be securely provided in CI environments.
Workflow Overview
The CI workflow (.github/workflows/ci.yml1) defines a single job test-mosquitto (.github/workflows/ci.yml12) that runs on ubuntu-latest (.github/workflows/ci.yml13):
| Attribute | Value |
|---|---|
| Workflow Name | CI |
| Job Name | test-mosquitto |
| Runner | ubuntu-latest |
| Service Tested | mosquitto from docker-compose.yml:4-9 |
| Triggers | push to main, pull_request to main |
| Validation | Container state inspection with 10-attempt retry loop |
| Timeout | 100 seconds (10 × 10s) |
Sources: .github/workflows/ci.yml:1-43 docker-compose.yml:4-9
Workflow Configuration
Trigger Configuration
The workflow executes on two GitHub event types:
Sources: .github/workflows/ci.yml:3-9
Job Architecture
test-mosquitto Job Flow
Sources: .github/workflows/ci.yml:1-43 docker-compose.yml:4-9
Execution Sequence
Sources: .github/workflows/ci.yml:1-43
Workflow Steps
Step 1: Checkout repository
Uses actions/checkout@v2 (.github/workflows/ci.yml:16-17) to clone the repository, making docker-compose.yml:1-18 and mosquitto.conf:1-5 available to subsequent steps.
Sources: .github/workflows/ci.yml:16-17
Step 2: Set up Docker Compose
Installs docker-compose via apt-get (.github/workflows/ci.yml:19-22). Docker Engine is pre-installed on ubuntu-latest, but Docker Compose requires explicit installation.
Sources: .github/workflows/ci.yml:19-22
Step 3: Start Mosquitto service using Docker Compose
Executes docker-compose up -d mosquitto (.github/workflows/ci.yml:24-25), starting only the mosquitto service from docker-compose.yml:4-9 The -d flag runs the container in detached mode. The cloudflared service (docker-compose.yml:11-17) is excluded because it requires CLOUDFLARE_TUNNEL_TOKEN.
Sources: .github/workflows/ci.yml:24-25 docker-compose.yml:4-9
Step 4: Wait for Mosquitto to be healthy
Implements a bounded retry loop (.github/workflows/ci.yml:27-39):
| Parameter | Value |
|---|---|
| Max Attempts | 10 |
| Sleep Interval | 10 seconds |
| Total Timeout | 100 seconds |
| Inspection Command | docker inspect --format='{{.State.Status}}' mosquitto |
| Success Condition | Status equals running |
Health Check Logic Flow
Sources: .github/workflows/ci.yml:27-39
Step 5: Stop Mosquitto service using Docker Compose
Executes docker-compose down (.github/workflows/ci.yml:41-42) to stop and remove the mosquitto container. This step always runs regardless of health check outcome.
Sources: .github/workflows/ci.yml:41-42
Test Coverage
The workflow validates:
| Aspect | Validation Mechanism |
|---|---|
eclipse-mosquitto:latest image availability | docker-compose up pulls image from Docker Hub |
| docker-compose.yml:4-9 service definition | Container instantiation succeeds |
| mosquitto.conf:1-5 syntax validity | Container starts without error |
Volume mount ./mosquitto.conf:/mosquitto/config/mosquitto.conf | Implicit validation during startup |
| Mosquitto broker process initialization | Container reaches running state |
Sources: .github/workflows/ci.yml:1-43 docker-compose.yml:4-9 mosquitto.conf:1-5
Excluded from Testing
cloudflared Service
The cloudflared service (docker-compose.yml:11-17) is not tested because:
- Requires
CLOUDFLARE_TUNNEL_TOKEN(docker-compose.yml17) - Token is environment-specific and authenticates with Cloudflare’s network
- Exposing a real token in CI logs would create a security vulnerability
The workflow explicitly specifies docker-compose up -d mosquitto (.github/workflows/ci.yml25), omitting the cloudflared service.
Sources: .github/workflows/ci.yml:24-25 docker-compose.yml:11-17
Protocol and Functional Testing
Not tested:
| Excluded Test | Reason |
|---|---|
| MQTT protocol connectivity (ports 1883, 9001) | No MQTT client invoked |
| Message publish/subscribe operations | Requires mosquitto_pub/mosquitto_sub clients |
| WebSocket protocol | No WebSocket connection attempted |
| Authentication/authorization | Configuration uses allow_anonymous true |
| Performance/load testing | Outside scope of health check |
Sources: .github/workflows/ci.yml:1-43 mosquitto.conf:1-5
Success and Failure Conditions
Success
The workflow exits with code 0 (.github/workflows/ci.yml32) when:
Returns true within 10 attempts, indicating:
- Container started with configuration from mosquitto.conf:1-5
- Volume mount
./mosquitto.conf:/mosquitto/config/mosquitto.confloaded successfully - Mosquitto broker process initialized
- Container state is
running
Sources: .github/workflows/ci.yml:29-32 mosquitto.conf:1-5 docker-compose.yml8
Failure
Health Check Timeout
Exits with code 1 (.github/workflows/ci.yml39) after 10 failed attempts:
Waiting for Mosquitto to be healthy...
(10 iterations)
Mosquitto did not become healthy in time
Potential causes:
- Invalid mosquitto.conf:1-5 syntax
- Missing
./mosquitto.conffile - Resource constraints on runner
- Docker Hub rate limiting
Sources: .github/workflows/ci.yml:38-39
Docker Compose Failures
Failures during docker-compose up -d mosquitto (.github/workflows/ci.yml25):
| Failure | Cause |
|---|---|
| Image pull error | Docker Hub connectivity issue |
| YAML parse error | Invalid docker-compose.yml:1-18 syntax |
| Volume mount error | ./mosquitto.conf not found |
Sources: .github/workflows/ci.yml:24-25 docker-compose.yml:1-18
Local Test Replication
Replicate the CI workflow locally:
Sources: .github/workflows/ci.yml:24-42
Debugging Workflow Failures
Failure Diagnosis
Sources: .github/workflows/ci.yml:1-43
Adding Container Log Output
To capture container logs on failure, add this step after .github/workflows/ci.yml39:
Sources: .github/workflows/ci.yml:27-42
Limitations
Test Scope
| Limitation | Impact |
|---|---|
No cloudflared testing | Tunnel connectivity not validated |
| No protocol testing | MQTT/WebSocket functionality not verified |
| No persistence testing | Data retention not checked (no volumes configured) |
| No security testing | Anonymous access not explicitly validated |
Sources: .github/workflows/ci.yml:1-43 mosquitto.conf:1-5
Runner Environment
ubuntu-latest (.github/workflows/ci.yml13) may differ from production:
- Architecture: typically
x86_64 - Network: isolated runner environment
- Resources: GitHub-managed limits
- Docker version: may lag behind latest releases
Sources: .github/workflows/ci.yml13
Timeout Consideration
The 100-second timeout (.github/workflows/ci.yml:29-39) accommodates:
- Docker Hub rate limiting
- Runner load variations
- Network latency
Typical startup time: 5-10 seconds in production.
Sources: .github/workflows/ci.yml:27-39
Potential Enhancements
Extended Coverage
Possible additions to .github/workflows/ci.yml:1-43:
| Enhancement | Implementation |
|---|---|
| MQTT protocol test | Add mosquitto_pub/mosquitto_sub client steps |
| WebSocket test | Add MQTT.js connection step |
Mock cloudflared | Stub tunnel with local proxy |
| Config validation | Run mosquitto -t -c mosquitto.conf |
| ACL testing | Test access control (requires password file) |
Sources: .github/workflows/ci.yml:1-43
Summary
The CI/CD pipeline provides basic validation that the Mosquitto MQTT broker can be successfully deployed using the repository’s Docker Compose configuration. The pipeline:
- Executes on every push and pull request to
main - Tests only the
mosquittoservice (excludescloudflared) - Validates container startup and health within 100 seconds
- Ensures configuration files are syntactically valid
- Provides immediate feedback to developers on infrastructure changes
While limited in scope, this pipeline prevents basic configuration errors from reaching production and provides a foundation for more comprehensive testing in the future.
Sources: .github/workflows/ci.yml:1-43 docker-compose.yml:1-18 mosquitto.conf:1-7
Dismiss
Refresh this wiki
Enter email to refresh