How to Configure the MQTT Connection in TeslaMate

The MQTT connection in TeslaMate is configured entirely through environment variables read at runtime, with MQTT_HOST being the only required setting to enable telemetry publishing to your broker.

TeslaMate publishes rich vehicle telemetry to an MQTT broker for integration with home automation platforms and custom dashboards. Configuring this connection requires setting specific environment variables that are processed during application startup in the teslamate-org/teslamate repository.

Runtime Configuration via Environment Variables

In config/runtime.exs, TeslaMate checks whether MQTT is disabled before building the configuration map. Unless DISABLE_MQTT is set to "true", the application constructs the MQTT settings from environment variables:

if System.get_env("DISABLE_MQTT") != "true" or config_env() == :test do
  config :teslamate, :mqtt,
    host: Util.fetch_env!("MQTT_HOST", all: "localhost"),
    port: System.get_env("MQTT_PORT") |> Util.to_integer(),
    username: System.get_env("MQTT_USERNAME"),
    password: System.get_env("MQTT_PASSWORD"),
    tls: System.get_env("MQTT_TLS") == "true",
    accept_invalid_certs: System.get_env("MQTT_TLS_ACCEPT_INVALID_CERTS") == "true",
    namespace: System.get_env("MQTT_NAMESPACE") |> Util.validate_namespace!(),
    ipv6: System.get_env("MQTT_IPV6") == "true"
end

(Source: [config/runtime.exs](https://github.com/teslamate-org/teslamate/blob/main/config/runtime.exs), lines 168-177)

Required Variables

• MQTT_HOST: The hostname or IP address of your MQTT broker. This is the only mandatory variable to establish a connection.

Optional Security and Network Settings

• MQTT_PORT: Broker port number. Defaults to 1883 for plain connections or 8883 when TLS is enabled.
• MQTT_USERNAME and MQTT_PASSWORD: Authentication credentials when your broker requires login.
• MQTT_TLS: Set to true to enable TLS encryption.
• MQTT_TLS_ACCEPT_INVALID_CERTS: Set to true to accept self-signed certificates. Use only in testing environments.
• MQTT_IPV6: Set to true to force IPv6 connection.
• MQTT_NAMESPACE: Optional prefix added to all MQTT topics (e.g., account_0 creates topics like account_0/teslamate/cars/1/state).

Application Startup Sequence

The TeslaMate.Application module reads the compiled configuration and conditionally starts the MQTT supervision tree. In lib/teslamate/application.ex, the children list includes the MQTT process only when configuration exists:

mqtt_config = Application.get_env(:teslamate, :mqtt)
children = [
  # ... other processes ...

  if(mqtt_config != nil, do: {TeslaMate.Mqtt, mqtt_config}),
  # ... other processes ...

]

(Source: [lib/teslamate/application.ex](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/application.ex), line 34)

When the configuration map is present, TeslaMate.Mqtt starts the publisher GenServer that wraps the Tortoise311 MQTT client.

Docker Compose Configuration

For Docker deployments, set the environment variables in your docker-compose.yml file. Here is the minimal configuration required to enable MQTT:

services:
  teslamate:
    image: teslamate/teslamate:latest
    restart: always
    environment:
      - ENCRYPTION_KEY=your-secure-key
      - DATABASE_USER=teslamate
      - DATABASE_PASS=your-db-password
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto      # Required: your broker hostname

      - MQTT_PORT=1883           # Optional: defaults to 1883

      # Optional authentication:

      # - MQTT_USERNAME=user

      # - MQTT_PASSWORD=pass

    ports:
      - "4000:4000"

(Source: [website/docs/installation/docker.md](https://github.com/teslamate-org/teslamate/blob/main/website/docs/installation/docker.md))

Disabling MQTT

To completely disable MQTT functionality, set the DISABLE_MQTT environment variable:

export DISABLE_MQTT=true

When disabled, config/runtime.exs skips MQTT configuration, and TeslaMate.Application does not start the MQTT supervision tree. This is useful for test environments or when you only need the web interface without telemetry publishing.

Publishing Custom Messages

The core MQTT logic resides in lib/teslamate/mqtt/publisher.ex, which provides a publish/3 API. You can publish custom messages from your own Elixir code:

# Publish to a specific topic

TeslaMate.Mqtt.publish("teslamate/cars/1/state", "online")

# Example wrapper function

defmodule CustomMqttClient do
  def publish_vehicle_state(car_id, state) do
    topic = "teslamate/cars/#{car_id}/state"
    TeslaMate.Mqtt.publish(topic, state)
  end
end

(Source: [lib/teslamate/mqtt/publisher.ex](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt/publisher.ex), lines 20-23)

Summary

• MQTT_HOST is the only required environment variable to configure the MQTT connection in TeslaMate.
• The configuration is built in config/runtime.exs and applied conditionally unless DISABLE_MQTT=true.
• TeslaMate.Application starts the MQTT supervision tree only when valid configuration exists.
• Support for TLS, authentication, IPv6, and topic namespacing is available through optional environment variables.
• The TeslaMate.Mqtt.publish/3 function allows custom message publishing to any MQTT topic.

Frequently Asked Questions

How do I connect TeslaMate to a broker with self-signed certificates?

Set MQTT_TLS=true and MQTT_TLS_ACCEPT_INVALID_CERTS=true. This configuration accepts invalid certificates but should only be used in testing environments according to the source code in config/runtime.exs.

What is the default MQTT port if I don't specify MQTT_PORT?

The application passes the environment variable through Util.to_integer(), which returns nil for empty strings. The underlying Tortoise311 client typically defaults to port 1883 for plain connections and 8883 for TLS connections when the port is not explicitly set.

Can I change the MQTT topic prefix in TeslaMate?

Yes, set the MQTT_NAMESPACE environment variable. This prefix is validated via Util.validate_namespace!() and prepended to all MQTT topics, allowing multiple TeslaMate instances to share one broker without collision.

Where do I configure MQTT for non-Docker installations?

For NixOS, systemd, or manual builds, export the same environment variables in your service definition or .env file. TeslaMate reads these directly from the process environment at runtime, so any method that injects environment variables before startup works identically to Docker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}