diff --git a/README.md b/README.md index a7cd7cb..5efd586 100644 --- a/README.md +++ b/README.md @@ -9,21 +9,42 @@ Fleet Telemetry is a server reference implementation for Tesla's telemetry proto The service handles device connectivity as well as receiving and storing transmitted data. Once configured, devices establish a WebSocket connection to push configurable telemetry records. Fleet Telemetry provides clients with ack, error, or rate limit responses. -## Configuring and running the service +## Prerequisites +There are a few system prerequisites/recommendations for installing and deploying a Fleet Telemetry server. For ease of installation, the recommendation is to run this service in a Debian server. In order for any Fleet Telemetry server to interact with vehicles, you will need to own a website domain and host Fleet Telemetry on that domain, which is defined as the `partner_domain` in the [Fleet API documentation](https://developer.tesla.com/docs/fleet-api#fleet-telemetry). + +### Minimum System Requirements +These minimum system requirements for any Fleet Telemetry server with 10 active vehicles connected running on a Debian-based server with regular day-to-day usage. Note that the requirements will be much higher depending on vehicle usage or number of vehicles. + +* 0.2 AWS vCPU +* 256MB of RAM +* 8GB of Storage -As a service provider, you will need to register a publicly available endpoint to receive device connections. Tesla devices will rely on a mutual TLS (mTLS) WebSocket to create a connection with the backend. The application has been designed to operate on top of Kubernetes, but you can run it as a standalone binary if you prefer. +### Dependencies +Fleet Telemetry has the following dependencies: -### Install on Kubernetes with Helm Chart (recommended) -For ease of installation and operation, we recommend running Fleet Telemetry on Kubernetes. Helm Charts help you define, install, and upgrade applications on Kubernetes. You can find a reference helm chart [here](https://github.com/teslamotors/helm-charts/blob/main/charts/fleet-telemetry/README.md). +* Go 1.20+ +* libzmq +* Docker* +* Kubernetes/Helm* -### Install manually (skip this if you have installed with Helm on Kubernetes) -1. Allocate and assign a [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). This will be used in the server and client (vehicle) configuration. +*Docker and Kubernetes/Helm are required for installing through deploying an image or using Helm Charts (recommended). -2. Design a simple hosting architecture. We recommend: Firewall/Loadbalancer -> Fleet Telemetry -> Kafka. +### Vehicle Compatibility + +Vehicles must be running firmware version 2023.20.6 or later. You may find this information under your VIN in the Tesla Mobile App or the Software tab in the vehicle's infotainment system. Some older model S/X are not supported. + +## Configuring and running the service +As mentioned in prerequisites, you will need to own a public domain that will run this server in order for the vehicles to communicate with your Fleet Telemetry server. You may generate [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) for your domain and the generated tls certificate + private key pair will be used for the server to authenticate vehicles connecting as well as a means for devices to connect to your Fleet Telemetry server. Tesla devices will rely on a mutual TLS (mTLS) WebSocket to create a connection with the backend. Fleet Telemetry has been designed to operate on top of Kubernetes, but you can run it as a standalone binary if you prefer. -3. Ensure mTLS connections are terminated on the Fleet Telemetry service. +Once you've generated/obtained your a tls certificate + private key with your domain, aka `partner_domain`, you may onboard your Fleet Telemetry server through the [Fleet API documentation](https://developer.tesla.com/docs/fleet-api#fleet-telemetry). -4. Configure the server +You may generate self a self-signed certificate using OpenSSL (have your domain/CNAME ready): + +```sh +openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem +``` + +Before you deploy your Fleet Telemetry server, you will also need to configure your server (the docker image will check the config mounted on `/etc/fleet-telemetry/config.json`). Here is a template: ``` { "host": string - hostname, @@ -43,7 +64,7 @@ For ease of installation and operation, we recommend running Fleet Telemetry on "flush_period": int - ms flush period } }, - "kafka": { //librdkafka kafka config, seen here: https://raw.githubusercontent.com/confluentinc/librdkafka/master/CONFIGURATION.md + "kafka": { // librdkafka kafka config, seen here: https://raw.githubusercontent.com/confluentinc/librdkafka/master/CONFIGURATION.md "bootstrap.servers": "kafka:9092", "queue.buffering.max.messages": 1000000 }, @@ -57,7 +78,7 @@ For ease of installation and operation, we recommend running Fleet Telemetry on "enabled": bool, "message_limit": int - ex.: 1000 }, - "records": { list of records and their dispatchers, currently: alerts, errors, and V(vehicle data) + "records": { // list of records and their dispatchers, currently: alerts, errors, and V(vehicle data) "alerts": [ "logger" ], @@ -77,7 +98,28 @@ For ease of installation and operation, we recommend running Fleet Telemetry on ``` Example: [server_config.json](./examples/server_config.json) -5. Deploy and run the server. Get the latest docker image information from our [docker hub](https://hub.docker.com/r/tesla/fleet-telemetry/tags). This can be run as a binary via `./fleet-telemetry -config=/etc/fleet-telemetry/config.json` directly on a server, or as a Kubernetes deployment. Example snippet: +### Deploy using Kubernetes with Helm Charts (recommended for large fleets) +If you already have a [Kubernetes](https://kubernetes.io/) stack or plan building a service that is used for large fleets, we recommend running Fleet Telemetry on Kubernetes. Helm Charts help you define, install, and upgrade applications on Kubernetes. You can find a reference helm chart [here](https://github.com/teslamotors/helm-charts/blob/main/charts/fleet-telemetry/README.md). + +You must have [Kubernetes](https://kubernetes.io/docs/setup/) amd [Helm](https://helm.sh/docs/intro/install/) installed for this deployment method. + +### Deploy using Docker + +1. Pull the Tesla Fleet Telemetry image (you may find all images in [docker hub](https://hub.docker.com/r/tesla/fleet-telemetry/tags)): +```sh +docker pull tesla/fleet-telemetry:v0.1.8 +``` +2. Run and deploy your docker image with your mTLS certificate, private key, and config.json locally mounted on `/etc/fleet-telemetry`: +```sh +sudo docker run -v /etc/fleet-telemetry:/etc/fleet-telemetry tesla/fleet-telemetry:v0.1.8 +``` +### Deploy manually +1. Build the server +```sh +make install +``` + +2. Deploy and run the server. This can be run as a binary via `$GOPATH/bin/fleet-telemetry -config=/etc/fleet-telemetry/config.json` directly on a server, or as a Kubernetes deployment. Example snippet: ```yaml --- apiVersion: apps/v1 @@ -115,7 +157,7 @@ spec: type: LoadBalancer ``` -6. Create and share a vehicle configuration with Tesla. +3. Create and share a vehicle configuration with Tesla. ``` { "hostname": string - server hostname, @@ -130,10 +172,6 @@ spec: ``` Example: [client_config.json](./examples/client_config.json) -## Vehicle Compatibility - -Vehicles must be running firmware version 2023.20.6 or later. Some older model S/X are not supported. - ## Backends/dispatchers The following [dispatchers](./telemetry/producer.go#L10-L19) are supported * Kafka (preferred): Configure with the config.json file. See implementation here: [config/config.go](./config/config.go)