Update documentation with clearer instructions for setup and deployment #88

thefireblade · 2023-12-14T23:49:50Z

Description

Updating the README with relevant information on setup requirements including what kind of system is needed in order to deploy a Tesla Fleet Telemetry server as well updating documentation flow for setting up certificates, keys, and configuration files.

Also adding examples on how to run the server through Docker and manually.

Type of change

Please select all options that apply to this change:

New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Bug fix (non-breaking change which fixes an issue)
Documentation update

Checklist:

Confirm you have completed the following steps:

My code follows the style of this project.
I have performed a self-review of my code.
I have made corresponding updates to the documentation.
I have added/updated unit tests to cover my changes.
I have added/updated integration tests to cover my changes.

README.md

ThomasAlxDmy · 2023-12-18T00:00:08Z

README.md

-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.


@aaronpkahn we might want to drop a line here about the new self-service version.

README.md

aaronpkahn · 2024-01-09T23:54:15Z

README.md

@@ -9,21 +9,38 @@ 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
+## Requirements
+These are the minimum system requirements for a Fleet Telemetry server, with 10 active vehicles connected, running on a Debian-based server with regular day-to-day usage. The requirements will change based on vehicle usage and quantity of vehicles.


minor: the first comma here isn't grammatically correct.
Maybe reword to something like: These minimum system requirements assume a server with: 10 active vehicles connected, running on a Debian-based image, and with regular day-to-day vehicle usage.

Why are we having 10 active vehicle as a reference? probably better to have 1k.

aaronpkahn · 2024-01-09T23:56:35Z

README.md


-4. Configure the server
+Before you deploy your Fleet Telemetry server, you will need to configure your server (the docker image will check the config mounted on `/etc/fleet-telemetry/config.json`). Server config template:


Suggested rewordding: "Create a server configuration, which by default is mounted on /etc/fleet-telemetry/config.json. Template:"

aaronpkahn · 2024-01-09T23:58:07Z

README.md

+### Deploy using Kubernetes with Helm Charts (recommended for large fleets)
+Hosting on [Kubernetes](https://kubernetes.io/) will enable the service to scale for large fleets. Helm Charts help you define, install, and upgrade applications on Kubernetes. 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.


reword: "Requires installation of Kubernetes and Helm."

aaronpkahn · 2024-01-09T23:59:13Z

README.md

+
+### 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)):


reword: "Pull the Tesla Fleet Telemetry image. Images are located in docker hub):"

aaronpkahn · 2024-01-09T23:59:42Z

README.md

+```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`:


reword: "Run and deploy the docker image with an mTLS certificate, private key, and config.json locally mounted on /etc/fleet-telemetry"

aaronpkahn · 2024-01-10T00:00:31Z

README.md

@@ -77,7 +94,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)
+Hosting on [Kubernetes](https://kubernetes.io/) will enable the service to scale for large fleets. Helm Charts help you define, install, and upgrade applications on Kubernetes. Reference Helm chart [here](https://github.com/teslamotors/helm-charts/blob/main/charts/fleet-telemetry/README.md).


Helm Charts help you define -> Helm Charts is used to define

Also, inconsistent capitalization: Reference Helm chart -> Reference Helm Chart? Or make chart lowercase in all examples?

Bre77 · 2024-01-22T04:59:38Z

README.md

-### 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.
+## Configuring and running the service
+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 to authenticate vehicles to your Fleet Telemetry server. Tesla vehicles rely on a mutual TLS (mTLS) WebSocket to create a connection with the backend.


You can use a self signed certificate to start the server, but /api/1/vehicles/fleet_telemetry_config will reject anything not signed by Tesla's CA. I do not believe this line is accurate in my experience.

Can you post what error you are receiving? I used a self-signed certificate for the fleet-telemetry server and it should be working as long as it registers properly with the endpoint.

Can you post what error you are receiving? I used a self-signed certificate for the fleet-telemetry server and it should be working as long as it registers properly with the endpoint.

{'response': None, 'error': 'Please follow instructions https://developer.tesla.com/docs/fleet-api#fleet-telemetry to send CSR to Tesla', 'error_description': ''}

Hi Brett
The error is because as discussed #41 (comment).
We are onboarding new csr submissions incrementally.

Hi Brett
The error is because as discussed #41 (comment).
We are onboarding new csr submissions incrementally.

That's correct, so I am trying to point out that proposed documentation change from @thefireblade that says you can use a self signed certificate is incorrect.

Hmm I don't think thats the issue. If you have mailed your CSR and haven't heard back, that means your account isn't ready for step 3 as mentioned in https://developer.tesla.com/docs/fleet-api#fleet-telemetry

thefireblade force-pushed the update-documentation branch 2 times, most recently from dff8701 to 777cc7e Compare December 17, 2023 23:05

thefireblade marked this pull request as ready for review December 17, 2023 23:06

ThomasAlxDmy reviewed Dec 17, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

ThomasAlxDmy reviewed Dec 18, 2023

View reviewed changes

thefireblade force-pushed the update-documentation branch 2 times, most recently from 1affa23 to d7c4e13 Compare December 18, 2023 20:46

agbpatro approved these changes Dec 18, 2023

View reviewed changes

aaronpkahn reviewed Dec 18, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

thefireblade force-pushed the update-documentation branch from d7c4e13 to 80501c0 Compare December 18, 2023 22:47

thefireblade requested a review from aaronpkahn December 18, 2023 23:13

thefireblade force-pushed the update-documentation branch 11 times, most recently from 3c8fe23 to eda646d Compare December 19, 2023 01:44

thefireblade force-pushed the update-documentation branch from eda646d to f622385 Compare December 26, 2023 15:53

aaronpkahn reviewed Jan 2, 2024

View reviewed changes

README.md Show resolved Hide resolved

Update documentation with clearer instructions for setup and deployment

b27c4e9

thefireblade force-pushed the update-documentation branch from f622385 to b27c4e9 Compare January 4, 2024 16:55

aaronpkahn reviewed Jan 9, 2024

View reviewed changes

aaronpkahn reviewed Jan 10, 2024

View reviewed changes

jbanyer mentioned this pull request Jan 22, 2024

How to generate and use the mTLS keys and cert? #99

Closed

Bre77 reviewed Jan 22, 2024

View reviewed changes

agbpatro closed this Apr 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation with clearer instructions for setup and deployment #88

Update documentation with clearer instructions for setup and deployment #88

thefireblade commented Dec 14, 2023 •

edited

Loading

ThomasAlxDmy Dec 18, 2023

aaronpkahn Jan 9, 2024

ThomasAlxDmy Jan 9, 2024

aaronpkahn Jan 9, 2024 •

edited

Loading

aaronpkahn Jan 9, 2024 •

edited

Loading

aaronpkahn Jan 9, 2024

aaronpkahn Jan 9, 2024

aaronpkahn Jan 10, 2024 •

edited

Loading

aaronpkahn Jan 10, 2024

Bre77 Jan 22, 2024

thefireblade Jan 23, 2024

Bre77 Jan 23, 2024 •

edited

Loading

agbpatro Jan 23, 2024

Bre77 Jan 23, 2024 •

edited

Loading

agbpatro Jan 23, 2024


		4. Configure the server
		Before you deploy your Fleet Telemetry server, you will need to configure your server (the docker image will check the config mounted on `/etc/fleet-telemetry/config.json`). Server config template:


		### 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)):

Update documentation with clearer instructions for setup and deployment #88

Update documentation with clearer instructions for setup and deployment #88

Conversation

thefireblade commented Dec 14, 2023 • edited Loading

Description

Type of change

Checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aaronpkahn Jan 9, 2024 • edited Loading

Choose a reason for hiding this comment

aaronpkahn Jan 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aaronpkahn Jan 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bre77 Jan 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bre77 Jan 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thefireblade commented Dec 14, 2023 •

edited

Loading

aaronpkahn Jan 9, 2024 •

edited

Loading

aaronpkahn Jan 9, 2024 •

edited

Loading

aaronpkahn Jan 10, 2024 •

edited

Loading

Bre77 Jan 23, 2024 •

edited

Loading

Bre77 Jan 23, 2024 •

edited

Loading