MeteorCloud
Self-hosted fleet platform for Linux devices.
MeteorCloud is the control plane, operator console, MQTT data plane, and device agent for managing edge fleets you own. Enroll devices, organize them by type and group, ship artifacts, run commands over MQTT, and keep operator access multi-tenant and auditable — without sending device data to a third-party SaaS.
Website: meteor-edge.com
Why MeteorCloud
| |
|---|
| You host it | Docker Compose on a VM/EC2, or Helm on a cluster you already run |
| Multi-tenant | Organizations, memberships, RBAC, and optional device-group scopes |
| Device lifecycle | Registration tokens, device-initiated enrollment, heartbeat, inventory |
| MQTT-ready | TLS broker (EMQX), per-device credentials, ACL, ingest, live telemetry |
| Artifacts | OS images, firmware, compose bundles — metadata in Postgres, blobs in filesystem or S3 |
| Replaceable infra | PostgreSQL required; Redis, MQTT, and object storage selected by config |
Architecture
MeteorCloud is split into three planes. The console is the operator UI; it talks only to the control plane.
| Plane | Path | Role |
|---|
| Device plane | src/device-plane/agent/ | meteorcli on the device: enroll, heartbeat, inventory, MQTT client |
| Data plane | src/data-plane/ | Platform MQTT gateway: subscribe/publish via EMQX, forward ingest to the control plane |
| Control plane | src/control-plane/ | Identity, tenancy, device registry, artifacts, MQTT policy, operator API, persistence |
Schema
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────────┐
│ Device plane │ │ Data plane │ │ Control plane │
│ (meteorcli) │ │ (MQTT gateway) │ │ (API + Postgres) │
└────────┬────────┘ └────────┬────────┘ └──────────┬───────────┘
│ │ │
│ HTTPS enroll / │ │
│ heartbeat / auth ├────────────────────────►│
│────────────────────────────────────────────────►│
│ │ │
│ MQTT telemetry / │ HTTP ingest │
│ status ──► EMQX ────►│────────────────────────►│
│ │ │
│◄── MQTT commands ◄────│◄── HTTP publish ────────│
│ EMQX │ │
Device → cloud (typical path)
- Agent enrolls and authenticates over HTTPS to the control plane.
- Agent publishes telemetry and status over MQTT to EMQX.
- Data plane receives those messages and HTTP-forwards them to the control plane for ingest and storage.
- Operators issue commands from the console → control plane → data plane → MQTT → agent.
More detail: docs/architecture.md.
Testing and development (laptop)
Compose on your machine. Not for production.
git clone https://github.com/meteor-edge/meteor-cloud.git
cd meteor-cloud
make dev
make seed # [email protected] / dev-password-123
Choose bundled services with COMPOSE_PROFILES in deploy/compose/.env (postgres, redis, minio, mqtt, emqx). Start one module: make dev-control-plane, make dev-data-plane, make dev-console. Stop: make stop.
Kubernetes (local k3d + Helm):
make k8s-up && make k8s-deploy && make k8s-status
See docs/getting-started.md and docs/development.md.
Production (VM)
On the server that will host MeteorCloud (on-prem VM or an existing EC2). Ansible installs Docker and starts production Compose (optional WireGuard).
# Ubuntu / Debian: sudo apt-get update && sudo apt-get install -y git make
# RHEL / Rocky / Alma: sudo dnf install -y git make
git clone https://github.com/meteor-edge/meteor-cloud.git
cd meteor-cloud
make up PLATFORM_DOMAIN=fleet.example.com
Create the printed DNS records (fleet.example.com, *.fleet.example.com,
vpn.fleet.example.com) and open https://fleet.example.com. Login and secrets
are printed at the end (~/.meteorcloud/secrets.env). Stop with make down.
Guide: docs/install-quickstart.md · docs/dns.md.
To create a new AWS EC2 from a laptop: make aws-up (docs/aws-deployment.md). Do not run make aws-up on the VM.
Deployment paths
Two independent paths; same images and settings.
MeteorCloud does not provision or manage Kubernetes clusters. The Helm chart installs into a cluster you already have. Ansible only prepares servers and runs Compose; it never deploys to Kubernetes. Terraform (infrastructure/terraform/aws) creates the AWS EC2 host for the Compose path.
On a VM you already have: clone, make up. To create a new AWS EC2 from a laptop, make aws-up (or edge-installer apply) runs Terraform then Ansible. Fresh-instance proof: GitHub Actions → EC2 smoke test (docs/aws-ci.md).
Dependencies
| Dependency | Status | Options |
|---|
| PostgreSQL | Required | Bundled container, or external |
| Artifact storage | Required | Filesystem volume, AWS S3, or any S3-compatible API |
| MQTT broker | Optional | Bundled or external EMQX; off by default |
| Redis | Optional | Shared rate limits across API replicas; in-memory otherwise |
| Kafka, ClickHouse | Not used | Not deployed |
The smallest install runs PostgreSQL, the API, the console, and a reverse proxy (Traefik with Compose, your ingress with Kubernetes).
Repository layout
├── src/
│ ├── control-plane/ # FastAPI (app.*), Dockerfile
│ ├── data-plane/ # MQTT gateway (data_plane.*), Dockerfile
│ └── device-plane/agent/ # meteorcli
├── console/ # operator UI, Dockerfile (nginx)
├── deploy/
│ ├── compose/ # Docker Compose files, .env.example
│ ├── ansible/ # server preparation + Compose deployment
│ └── kubernetes/helm/ # Helm chart
├── infrastructure/
│ ├── terraform/aws/ # EC2 host for the Compose path
│ └── installer/ # edge-installer (Terraform + Ansible on AWS)
├── contracts/ # HTTP JSON between planes
├── scripts/ # smoke tests, certificates, CI helpers
├── docs/
└── Makefile
Documentation
Start with Getting started, then the full index: docs/README.md.
Contributors: CONTRIBUTING.md. Coding agents: AGENTS.md.
Website: meteor-edge.com.
License
Copyright © Meteor Edge contributors.
Licensed under the Apache License, Version 2.0.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
