1
Step 1Open the server Apps tab
Select the tutorial-vps VPS, open the Apps tab, and start a new app deployment. Keep sensitive server details hidden before capturing or sharing screenshots.
Deploy EMQX in 3 Steps
1
Connect Your VPS
Add your server credentials to Server Compass
2
Select EMQX
Choose from our template library
3
Deploy & Configure
Fill in settings and click Deploy
No Docker knowledge required
Step-by-step deployment guide
Deploy EMQX on a VPS with Server Compass
Use the EMQX template in Server Compass to deploy a self-hosted MQTT broker on your VPS, then verify the EMQX dashboard in a browser.
About 10 minutesBrowser verified
2
Step 2Choose an app template
Click New App and choose the template deployment path so Server Compass can load the built-in catalog.
3
Step 3Search for EMQX
Use the template picker search to find EMQX in the Server Compass template catalog.
4
Step 4Select the EMQX template
Choose the EMQX template. Server Compass fills the EMQX broker service, MQTT port, WebSocket port, dashboard port, and persistent data/log volumes.
5
Step 5Review the EMQX settings
Confirm the app name and compose services. In this run, the app was named emqx-demo, with MQTT on 1883, WebSocket on 8083, and the dashboard on 18083.
6
Step 6Deploy EMQX
Review the generated compose settings, confirm the MQTT, WebSocket, and dashboard ports are available, and click Deploy Now.
7
Step 7Watch the deployment progress
Keep the deployment modal open while Server Compass uploads the compose file, pulls the EMQX image, starts the container, and verifies the stack.
8
Step 8Confirm EMQX is running
After deployment finishes, return to the Apps tab and confirm the EMQX app is marked Running with its application URL available.
9
Step 9Open EMQX in the browser
Open the dashboard URL in a browser. The EMQX dashboard login screen confirms the MQTT broker stack is reachable.
After EMQX Opens
- Sign in to the dashboard with the default credentials and change the password immediately.
- Store broker credentials, dashboard credentials, and client secrets in a secure password manager.
- Add TLS and authentication rules before allowing production MQTT clients.
- Create listeners, users, ACLs, and integrations for your IoT or messaging workloads.
- Back up the EMQX data and log volumes before relying on it for production messaging.
Verified Result
The EMQX dashboard loaded successfully in a browser and displayed the login screen.
EMQX deployment questions
What does the EMQX template deploy?
It deploys the EMQX broker with persistent data and log volumes, MQTT access, WebSocket access, and the EMQX dashboard.
Which port did the tutorial use?
The tutorial verified the dashboard on host port 18083. MQTT used host port 1883, and WebSocket access used host port 8083.
Why does the browser verification stop at the login screen?
A fresh EMQX deployment is considered reachable when the dashboard login screen loads. Users, ACLs, TLS, listeners, and integrations are environment-specific.
Should this become a blog post?
No. The deployment guide should live on the EMQX template detail page and be linked from the reusable template deployment docs page.
CLI Deployment
Deploy EMQX Yourself
Want full control? Here's how to deploy EMQX yourself using Docker Compose.
1
Establish SSH Connection
Connect to your remote server using SSH. Make sure you have your server credentials ready.
terminal
# Log into your server
ssh root@<your-server-ip>
# If using key-based auth
ssh -i ~/.ssh/my-key root@<your-server-ip>First time? Docker not installed? Run: curl -fsSL https://get.docker.com | sh
2
Create Project Directory
Set up a directory to store your Docker configuration.
terminal
# Create and navigate to project directory
mkdir -p ~/apps/emqx
cd ~/apps/emqx3
Configure Docker Compose
Add this configuration to your docker-compose.yml file:
docker-compose.yml
services:
emqx:
image: emqx/emqx:latest
ports:
- "1883:1883"
- "8083:8083"
- "18083:18083"
volumes:
- emqx_data:/opt/emqx/data
- emqx_log:/opt/emqx/log
restart: unless-stopped
volumes:
emqx_data:
emqx_log:
Required Settings
PORTMQTT port(default: 1883)WS_PORTWebSocket port(default: 8083)DASHBOARD_PORTDashboard port(default: 18083)4
Start the Services
Execute the deployment and check the container status.
terminal
# Deploy the application
docker compose up -d
# Check container health
docker compose ps
# Monitor logs
docker compose logs -f --tail=1005
Allow Incoming Connections
Enable network access by updating your firewall rules.
terminal
# Allow the application port through firewall
sudo ufw allow 1883/tcp
sudo ufw reload
# Access your app at:
# http://your-server-ip:1883Skip the Terminal
Too complicated? Let Server Compass handle it.
Skip the terminal and deploy EMQX with a visual interface. Configure everything with clicks, not commands.
- Intuitive dashboard
- Deploy in 3 minutes
- Free SSL included
- Blue-green deploys
- Real-time logs
- Version history
Download Server Compass$29 one-time • Lifetime license
After Deployment
After deploying EMQX with Server Compass, complete these steps to finish setup
1
Access dashboard
2
Change admin password
3
Configure authentication
Need help? Check out our documentation for detailed guides.
EMQX FAQ
Common questions about self-hosting EMQX
How do I deploy EMQX with Server Compass?
Simply download Server Compass, connect to your VPS, and select EMQX from the templates list. Fill in the required configuration and click Deploy. The entire process takes under 3 minutes.
What are the system requirements for EMQX?
EMQX requires a minimum of 512MB RAM. We recommend a VPS with at least 1024MB RAM for optimal performance. Any modern Linux server with Docker support will work.
Can I migrate my existing EMQX data?
Yes! Server Compass provides volume mapping that allows you to import existing data. You can also use standard EMQX backup and restore procedures.
How do I update EMQX to the latest version?
Server Compass makes updates easy. Simply click the Update button in your deployment dashboard, and the latest EMQX image will be pulled and deployed with zero downtime.
Is EMQX free to self-host?
EMQX is open-source software. You only pay for your VPS hosting (typically $5-20/month) and optionally Server Compass ($29 one-time). No subscription fees or per-seat pricing.
Related Templates
View all Development
PocketBase
Open-source backend in a single file with realtime database, auth, and file storage
Appwrite
Open-source backend-as-a-service - self-hosted Firebase alternative
Parse Server
Open-source backend framework with dashboard
Supabase
Full Supabase self-hosted with Kong, GoTrue Auth, Realtime, and Studio
Ready to Self-Host EMQX?
Download Server Compass and deploy EMQX to your VPS in under 3 minutes. No Docker expertise required.
Download Server Compass