From 70651987bf0ab75aa32ebdfef0b5500a4c67e3df Mon Sep 17 00:00:00 2001 From: Martin Dimitrov Date: Tue, 10 Jun 2025 18:36:22 -0700 Subject: [PATCH] add main readme --- README.md | 79 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 45 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index f8a205f..5774422 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,28 @@ # doorman -To install dependencies: +To install dependencies for all packages ```bash bun install ``` -To run: +## Packages -```bash -bun run index.ts -``` +Check out the individual READMEs in the monorepo to see how to run each component of Doorman -This project was created using `bun init` in bun v1.0.3. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime. +- doorman-client (twilio function that runs when receiving buzzer call) +- doorman-api (backend API that manages Door state and configs) +- doorman-ui (frontend React app) +- doorman-schema (future home for all the zod schemas and basic validations) -## Deployments +## CI/CD workflows +On pushes to main, the Gitea action in `.gitea/workflows/deploy-twilio.yaml` handle deployments to Twilio / homeassistant. -They are configured to happen in gitea actions for CI/CD. If you need to deploy manually, it should be possible as long as you source the requisite envs first. - -## to deploy Doorman API / UI - -```bash -bun run deploy-serverless -``` - -## to deploy Doorman Buzzer client - -```bash -bun run deploy-buzzer-client -``` - -## homeassistant integration poller - -in configuration.yaml - -``` -switch: - - platform: rest - name: Doorman - icon: mdi:door-closed-lock - state_resource: https://doorman.chromart.cc/api/door/info?door=buzzer - resource: https://doorman.chromart.cc/api/door/auth?door=buzzer&key=1991 - is_on_template: "{{ value_json.status == 'OPEN' }}" -``` +1. Builds change +2. Run local integration tests +3. Deploy to staging +4. Run staging integration tests +5. Promote to prod ## .env.twiliotemplate @@ -51,3 +31,34 @@ This file is used for twilio Deployments in github actions. In short, it specifi For any value that is specified, it uses that value. For any value that is in the file but not specified (= nothing), it would be loaded from the execution environment (as a Gitea secret). If the env var is not in the environment passed in, then the deployment would fail. + +## for twilio packages, what is going on in src/index.ts (Bun.build) + +This file contains a Bun bundler for Javascript. In short, it compiles the Typescript code under ./src/functions into javascript, bundling all the local files together and optionally certain dependencies. + +This is necessary because Twilio Functions only supports Javascript, and doesn't allow importing code across files. This previously was really hard to maintain, because Javascript is not typed and the files were really long. Our deployed code is basically the package compiled into one file so it can be deployed in Twilio. + +Also, since Bun supports ESM (import . from .) and CommonJS (require) module syntax but Twilio only supports CommonJS, the bundler will explicitly bundle dependencies that only support CommonJS. This is because when deployed in Twilio, we cannot use ESM and Bun handles this conversion for us without the library needing dual support (though most libraries support both ESM and CommonJS). + +If we add a library that only supports ESM, then we need to add it as an explicitly bundled dep in src/index.ts + +### To deploy manually (not reccomended) + +First you need to have Twilio secrets in your env + +``` +export ACCOUNT_SID=AC... +export AUTH_TOKEN=8e... +``` + +#### to deploy Doorman API / UI manually + +```bash +bun run deploy-serverless<:staging> +``` + +#### to deploy Doorman Buzzer client + +```bash +bun run deploy-buzzer-client<:staging> +```