Update documentation with clearer instructions for setup and deployment

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.
+
+* Allocate at least 0.2 AWS vCPU, 256MB RAM, and 8GB storage
+* Host on a publicly available server with an associated domain
+
+### Recommendations
+* Run on a Debian base image
+* Allocate and configure a server certificate using best practices
+
+### Dependencies
+* Go 1.20+
+* libzmq
+* Docker*
+* Kubernetes/Helm*
+
+*Kubernetes/Helm is required when using the Helm Charts deployment method (recommended) and Docker is required for deploying Fleet Telemetry via a docker image.
 
-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.
+### Vehicle Compatibility
 
-### 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).
+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.
 
-### 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. Fleet Telemetry has been designed to operate on top of Kubernetes, but you can run it as a standalone binary.
 
-2. Design a simple hosting architecture. We recommend: Firewall/Loadbalancer -> Fleet Telemetry -> Kafka.
+You may generate a self-signed certificate using the OpenSSL command below, though we recommend using best practices for generating a server certificate from a trusted certificate authority (have your domain/CNAME ready):
 
-3. Ensure mTLS connections are terminated on the Fleet Telemetry service.
+```sh
+openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
+```
 
-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:
 ```
 {
   "host": string - hostname,
@@ -43,7 +60,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 +74,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 +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)
+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 +153,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 +168,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)