Installation

RosFit can be deployed in multiple ways depending on your scale and infrastructure requirements. Docker Compose is the fastest path for local development and small-to-medium fleets. Kubernetes is recommended for production.

Docker Compose (recommended)

The repository ships with a complete docker-compose.yml that starts every service you need. This is the recommended approach for local development, demos, and fleets of up to ~50 devices.

git clone https://github.com/rosfit/rosfit.git
cd rosfit
cp .env.example .env
docker compose up -d

Services overview

The compose file defines seven services:

services:
  emqx:
    image: emqx/emqx:5.6
    ports:
      - "1883:1883"     # MQTT
      - "8883:8883"     # MQTT TLS
      - "8083:8083"     # MQTT WebSocket
      - "18083:18083"   # EMQX Dashboard
    volumes:
      - ./config/emqx/acl.conf:/opt/emqx/etc/acl.conf
      - emqx_data:/opt/emqx/data

  postgres:
    image: timescale/timescaledb:latest-pg16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: rosfit
      POSTGRES_USER: rosfit
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    command: server /data --console-address ":9001"
    volumes:
      - minio_data:/data

  api:
    build: ./api
    ports:
      - "8000:8000"
    depends_on:
      - postgres
      - redis
      - emqx
    env_file: .env

  handler:
    build: ./handler
    depends_on:
      - postgres
      - redis
      - emqx
    env_file: .env

  dashboard:
    build: ./dashboard
    ports:
      - "3000:3000"
    depends_on:
      - api

Verifying the deployment

After running docker compose up -d, wait about 30 seconds for all services to initialise, then check their health:

docker compose ps

You can also verify individual service connectivity:

# Test MQTT broker
mosquitto_pub -h localhost -p 1883 -t "test" -m "hello"

# Test API
curl http://localhost:8000/api/v1/health

# Open dashboard
open http://localhost:3000

Self-hosted Kubernetes

For production fleets, RosFit provides a Helm chart that deploys all services to any Kubernetes cluster.

helm repo add rosfit https://charts.rosfit.io
helm repo update

helm install rosfit rosfit/rosfit \
  --namespace rosfit \
  --create-namespace \
  --values values.yaml

A minimal values.yaml looks like this:

global:
  domain: rosfit.example.com

api:
  replicas: 2
  env:
    JWT_SECRET: your-production-secret

emqx:
  replicas: 3
  persistence:
    size: 10Gi

postgres:
  persistence:
    size: 50Gi

minio:
  persistence:
    size: 100Gi

ingress:
  enabled: true
  className: nginx
  tls: true
  certManager: true

The chart supports horizontal scaling for the API and message handler services, persistent volume claims for all stateful services, and automatic TLS via cert-manager.

Cloud (hosted)

If you prefer a managed deployment, RosFit Cloud handles all infrastructure for you.

Sign up at rosfit.io and create an organisation.
Copy your API key from the settings page.
Point your bridge at the cloud endpoint:

mqtt:
  host: mqtt.rosfit.io
  port: 8883
  tls: true
  token: your-api-key

Open the dashboard at https://app.rosfit.io.

Cloud plans include managed EMQX clustering, automated backups, global edge endpoints, and 99.9% SLA.

Environment variables

Configure the RosFit stack via the .env file (Docker Compose) or through your Kubernetes secret / config map.

Variable	Default	Description
`DATABASE_URL`	`postgresql://rosfit:rosfit@postgres:5432/rosfit`	PostgreSQL / TimescaleDB connection string
`REDIS_URL`	`redis://redis:6379/0`	Redis connection string for shadows and caching
`MQTT_BROKER_HOST`	`emqx`	MQTT broker hostname
`MQTT_BROKER_PORT`	`1883`	MQTT broker port
`MINIO_ENDPOINT`	`minio:9000`	MinIO endpoint for firmware artefact storage
`JWT_SECRET`	—	Secret key for signing JWT tokens (required)
`ROSFIT_ENV`	`development`	Environment name (`development`, `staging`, `production`)

For production deployments, always set JWT_SECRET to a strong random value and switch ROSFIT_ENV to production, which enables stricter security defaults and disables debug logging.

Port reference

The following ports are used by RosFit services. Ensure they are open in your firewall or security group.

Port	Protocol	Service	Description
1883	MQTT	EMQX	MQTT plaintext (devices and bridge)
8883	MQTTS	EMQX	MQTT over TLS (production devices)
8083	WebSocket	EMQX	MQTT over WebSocket (browser clients)
8000	HTTP	API	FastAPI backend (REST + WebSocket)
3000	HTTP	Dashboard	React frontend
9000	HTTP	MinIO	Object storage API
9001	HTTP	MinIO	Object storage web console
5432	TCP	PostgreSQL	Database (internal, not exposed in production)
6379	TCP	Redis	Cache and shadows (internal, not exposed in production)

Explore the project structure