--- name: teslamateapi-setup description: Add TeslaMateApi to an existing self-hosted TeslaMate server and do a test of the API, so the Fastcruise iOS app can connect. Use this skill for Fastcruise setup, TeslaMateApi, an API bridge for TeslaMate, or Tesla data on an iPhone. Give the setup wizard to the user when the user can run a command on the server. --- # TeslaMateApi setup for Fastcruise This skill is the agent version of the setup guide: https://fastcruise.app/blog/teslamate-fastcruise-setupguide ## What this skill does Fastcruise is a free iOS app for Tesla data. The app reads the TeslaMate server of the user. TeslaMate has no API for an app. TeslaMateApi is the bridge between the database and the app. This skill adds one service to the Docker Compose file of the user. Then it starts the service. Then it does a test of the API. The user does the work on the iPhone. You cannot install the app. ## Take this path first: give the wizard to the user The wizard is a bash script that the user runs on the TeslaMate server. It does the server work. It asks for no password and no key. This path keeps every value out of this chat. Use it when the user can open a terminal on the server. Give this command to the user: ```bash curl -fsSL https://fastcruise.app/skills/teslamateapi-setup/setup-wizard.sh -o setup-wizard.sh bash setup-wizard.sh ``` - Do not run the wizard yourself. The user must answer the questions of the wizard. - Give `--dry-run` to the user for a first look. Give `--port ` when port 8080 is in use. - The wizard shows the Compose file, the backup path, and the container result. - The wizard also shows the result of the test and the URL for the app. Ask the user for these items. - The wizard and the script write no secret value. Go to "Remote access" and "Report" at the end of this file. ## Or take this path: you do the server work Use this path only when the user asks you to do the work. Use it also when the user cannot run the wizard. ### Secrets The Compose file of TeslaMate holds the encryption key and the database password. Do not put these values in this chat. - Do not read the Compose file with a file tool. Use the script of this skill. The script keeps the values in the shell. - Do not print the environment of a service. Do not run `docker compose config` for a report. - Do not run `docker inspect`, `env`, or `cat .env`. - Do not ask the user for a password, an encryption key, or a token. Tell the user that you do not need these values. - Tell the user to change a value on the server when the user sends the value in this chat. The chat keeps the text. - Do not put a value in the report. Write the key names only. - Stop when you cannot keep these rules. Ask the user to do the step by hand. ### Step 1: Get access to the server Get the host name or the SSH address of the TeslaMate server from the user. Do the work on that server. When the TeslaMate server is the local machine, continue in the current directory. ### Step 2: Find the Compose file Find the Compose file of the TeslaMate project. Look for these names: 1. `compose.yaml` 2. `compose.yml` 3. `docker-compose.yml` 4. `docker-compose.yaml` ```bash ls compose.yaml compose.yml docker-compose.yml docker-compose.yaml 2>/dev/null docker compose ls # the active projects and their config files ``` Stop and tell the user when you find no file. TeslaMateApi must have the same Compose file as TeslaMate. ### Step 3: Add the service Download the script of this skill. Then run the script on the Compose file: ```bash curl -fsSL https://fastcruise.app/skills/teslamateapi-setup/add-service.py -o /tmp/add-service.py python3 /tmp/add-service.py --compose docker-compose.yml ``` Give the correct path and file name to `--compose`. The script does these steps: - It makes one backup of the Compose file. - It copies the environment block of the `teslamate` service into the new `teslamateapi` service. - It writes the key names to the output. It does not write a value. - It stops when the file has a `teslamateapi` service already. The script writes this service. The environment values are the values of the `teslamate` service: ```yaml teslamateapi: image: tobiasehlert/teslamateapi:latest restart: always depends_on: - database environment: # the keys and the values of the teslamate service ports: - 8080:8080 ``` - Read the output of the script. Tell the user when the script stops with an error. - Use `--port` for a different host port when port 8080 is in use. Use `--timezone` for the `TZ` line. - Keep `latest` as the image tag. Fastcruise was tested with version 1.21.0 and version 1.25.0. When the current version gives errors, change the tag to `1.21`. - Stop when the script cannot read the file. Ask the user to add the service by hand with the setup guide. Do not read the Compose file yourself. ### Step 4: Check the two services Run the check: ```bash python3 /tmp/add-service.py --compose docker-compose.yml --check ``` The command compares the two services inside the shell. The output shows the key names and `match` or `DIFFERENT`. Each line must say `match`. A different `DATABASE_PASS` stops the service. A different `ENCRYPTION_KEY` does not stop the service. Use this check for that reason. Tell the user which key differs. Stop when a line says `DIFFERENT`. ### Step 5: Start the service ```bash docker compose up -d teslamateapi docker compose ps teslamateapi ``` Wait for the result `Up`. The first start makes the database ready. This step can need a few minutes. Do not stop during this time. The message `connection refused` in this time is normal. Wait and read the log again. Run this command again after a short time: ```bash docker compose logs --tail=50 teslamateapi ``` The message `password authentication failed for user "teslamate"` shows an incorrect `DATABASE_PASS`. Correct the value on the server. Do not write the value in this chat. A container with a high restart count is in a restart loop. Compare `DATABASE_USER`, `DATABASE_PASS`, and `DATABASE_NAME` in the `teslamateapi` service with `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` in the `database` service. Use `--check` of the script for this comparison. ### Step 6: Do a test of the API Do the first test from the server: ```bash curl -sS http://127.0.0.1:8080/api/v1/cars ``` The result is JSON. It has the part `data` with the part `cars`. Each car has the parts `car_details`, `car_settings` and `teslamate_stats`. Do the second test with the address that the iPhone uses: ```bash curl -sS --max-time 5 "http://:8080/api/v1/cars" ``` This test shows that the API listens on the network interface and that the firewall lets the traffic through. Stop when a test shows an error. Tell the user the error. Do not tell the user that the setup is complete. ### Step 7: Give the app steps to the user Give these items to the user: - The URL for the app: `http://:8080` - Tell the user to give the local network permission to the app at the first connection. - The first connection can show an error. The user taps the connection status again. - The app: https://apps.apple.com/us/app/fastcruise-tesla/id6747918869 ## Remote access For remote access, give one of these methods: - A VPN, for example WireGuard, Tailscale, or the VPN of the router. This method is the safest one. - A reverse proxy with HTTPS and authentication in front of port 8080. Get the approval of the user before you change a firewall, a tunnel, or a reverse proxy. Tell the user that other persons can read the Tesla data when the API port is open on the internet. TeslaMateApi has no authentication by default. Every device in the network of the user can read the Tesla data. Tell the user. TeslaMateApi can use an `API_TOKEN` for authentication. Tell the user this option and stop. Do not ask for the value of a token in this chat. ## Report Give these items at the end: - The path of the Compose file and the path of the backup. - The container result from `docker compose ps`. - The result of each test of the API. - The URL for the app, and the work that remains for the user. Do not put a secret value in the report. Write the key names only.