Description

This Railway template sets up an EMQX MQTT broker with a Caddy reverse proxy. The EMQX broker is configured to handle MQTT connections over TCP on port 1883. The Caddy reverse proxy manages access to the EMQX admin dashboard and handles MQTT connections over WebSocket.

[!NOTE] Admin password is randomly generated by default. See varialbe EMQX_DASHBOARD__DEFAULT_PASSWORD

This template deploys an open-source community edition of the EMQX broker.

EMQX

EMQX is a highly scalable, open-source MQTT broker designed to support large-scale IoT applications. It enables the exchange of messages between devices with minimal overhead, ensuring efficient and reliable communication.

Default Ports

Railway doesn't allow to expose multiple ports, thus there is a Caddy reverse proxy to handle HTTP and WebSocket connections.

EMQX listens the following ports by default

• TCP Port: 1883 (MQTT)
• WebSocket Port: 8083 (MQTT over WebSocket)
• SSL Port: 8883 (MQTT over TLS)
• Secure WebSocket Port: 8084 (MQTT over secure WebSocket)
• Admin Dashboard Port: 18083 (EMQX admin UI)

This template exposes 1883 TCP port directly from emqx service.

✨ Features

• Random admin password generation.
• MQTT 5.0 Support: EMQX supports the MQTT 5.0 specification, offering features like shared subscriptions, enhanced security, message properties, and more.
• High Performance: EMQX is designed for high performance and low latency, suitable for applications that require real-time communication.
• Scalability: EMQX can be easily scaled horizontally to handle a large number of concurrent connections and messages.
• Reliability: Ensures message delivery even in unreliable network conditions. Persistent sessions and durable message storage mechanisms prevent message loss.
• Security: Comprehensive security features, including TLS/SSL encryption, client authentication, access control, and integration with external authentication mechanisms.
• WebSockets: Supports MQTT over WebSockets, allowing devices and applications to communicate over HTTP/HTTPS ports.
• Advanced Clustering: Enables setting up multiple instances that work together to provide high availability and fault tolerance.
• Session Management: Provides flexible session management options, including session expiration, resumption, and storage.
• Retained Messages: Stores the last known state of a topic, ensuring that new subscribers immediately receive the latest data.
• QoS (Quality of Service): Supports MQTT's QoS levels, ensuring that messages are delivered as required by the application's quality-of-service requirements.

💁‍♀️ Services

• EMQX
• Caddy Reverse Proxy

🛠 How to use

• Click the Railway button 👆
• Add the required environment variables
• Deploy
• Open the deployment URL in a browser. Check EMQX_DASHBOARD__DEFAULT_PASSWORD variable for the password for admin user, if you didn't set it manually.
• Try MQTTX web client to connect to deployed server

Environment Variables for EMQX Service

• WS_PORT=8083: MQTT over WebSocket port.
• SSL_PORT=8883: MQTT over TLS port.
• TCP_PORT=1883: MQTT TCP port.
• WSS_PORT=8084: MQTT over secure WebSocket port.
• ADMIN_PORT=18083: Dashboard port.
• EMQX_NODE__COOKIE=${{ secret(64) }}: Cookie secret for node communication.
• EMQX_DASHBOARD__DEFAULT_PASSWORD=${{ secret(18) }}: Admin password for the EMQX dashboard.

Environment Variables for Caddy Service

• MQTT_SERVICE=${{emqx.RAILWAY_PRIVATE_DOMAIN}}: Name of the service/container with EMQX.
• MQTT_WS_PORT=${{emqx.WS_PORT}}: Port of the MQTT over WebSocket listener.
• MQTT_ADMIN_PORT=${{emqx.ADMIN_PORT}}: Port of the EMQX admin UI listener.

📝 Notes

• EMQX repo: https://github.com/emqx/emqx-docker
• Docs: https://docs.emqx.com/en/
• Caddy image: https://github.com/maximofftech/railway-emqx