# How to Configure the MQTT Connection in TeslaMate

> Easily configure your TeslaMate MQTT connection using environment variables. Learn how to set MQTT_HOST and enable telemetry publishing to your broker for seamless data integration.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: how-to-guide
- Published: 2026-06-18

---

**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`](https://github.com/teslamate-org/teslamate/blob/main/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:

```elixir
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)](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`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/application.ex), the children list includes the MQTT process only when configuration exists:

```elixir
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)](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`](https://github.com/teslamate-org/teslamate/blob/main/docker-compose.yml) file. Here is the minimal configuration required to enable MQTT:

```yaml
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)](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:

```bash
export DISABLE_MQTT=true

```

When disabled, [`config/runtime.exs`](https://github.com/teslamate-org/teslamate/blob/main/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`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt/publisher.ex), which provides a `publish/3` API. You can publish custom messages from your own Elixir code:

```elixir

# 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)](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`](https://github.com/teslamate-org/teslamate/blob/main/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`](https://github.com/teslamate-org/teslamate/blob/main/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.