From 8e18bfd53e9facda160d4751d9bde24546f74e8c Mon Sep 17 00:00:00 2001 From: Martin Dimitrov Date: Tue, 10 Jun 2025 18:52:23 -0700 Subject: [PATCH] add readme for doorman-client --- README.md | 6 +-- packages/doorman-api/README.md | 4 ++ packages/doorman-api/src/local/localDdb.ts | 2 +- packages/doorman-client/.env.local | 18 +++++++ packages/doorman-client/.gitignore | 1 - packages/doorman-client/README.md | 55 +++++++--------------- packages/doorman-client/package.json | 2 +- 7 files changed, 44 insertions(+), 44 deletions(-) create mode 100644 packages/doorman-client/.env.local diff --git a/README.md b/README.md index 5774422..a3bbfbc 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ bun install Check out the individual READMEs in the monorepo to see how to run each component of Doorman -- 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-client (Twilio Function that triggers when receiving buzzer call) +- doorman-api (Twilio Function API that manages Door state and configs) +- doorman-ui (frontend React app, served by doorman-api) - doorman-schema (future home for all the zod schemas and basic validations) ## CI/CD workflows diff --git a/packages/doorman-api/README.md b/packages/doorman-api/README.md index 21bc473..44c8732 100644 --- a/packages/doorman-api/README.md +++ b/packages/doorman-api/README.md @@ -48,6 +48,10 @@ martin 243091 243061 93 17:57 pts/4 00:00:13 java -Xrs -Djava.library.pat kill 243091 ``` +or if you want to kill all java processes (likely only this DDB local thing) + +`kill $(pidof java)` + ## deployment this project deploys the UI and API to twilio functions https://doorman-6741-prod.twil.io diff --git a/packages/doorman-api/src/local/localDdb.ts b/packages/doorman-api/src/local/localDdb.ts index 34f0a9c..0315603 100644 --- a/packages/doorman-api/src/local/localDdb.ts +++ b/packages/doorman-api/src/local/localDdb.ts @@ -69,7 +69,7 @@ const doorConfig: DoorConfig = { buzzer: testDoorBuzzer, pressKey: "4", discordUsers: [], - fallbackNumbers: [], + fallbackNumbers: ["1231231234"], pin: testDoorPin, buzzerCode: testDoorPin, timeout: 60, diff --git a/packages/doorman-client/.env.local b/packages/doorman-client/.env.local new file mode 100644 index 0000000..24070cc --- /dev/null +++ b/packages/doorman-client/.env.local @@ -0,0 +1,18 @@ +# twilio (not needed for dev) +# ACCOUNT_SID= +# AUTH_TOKEN= + +DOORMAN_URL=http://localhost:8080 + +# metrics +PUSHGATEWAY_URL=https://metrics.chromart.cc +STAGE=$user-dev +PUSHGATEWAY_USER=doorman +PUSHGATEWAY_PW=doormanmetrics + +# logs +LOKI_URL=https://logs.chromart.cc +LOKI_USER=doorman +LOKI_PW=doormanlogs + +NOTIFY_SECRET_KEY=discordnotifyme \ No newline at end of file diff --git a/packages/doorman-client/.gitignore b/packages/doorman-client/.gitignore index c06e76e..8dce244 100644 --- a/packages/doorman-client/.gitignore +++ b/packages/doorman-client/.gitignore @@ -80,7 +80,6 @@ web_modules/ .env.development.local .env.test.local .env.production.local -.env.local # parcel-bundler cache (https://parceljs.org/) .cache diff --git a/packages/doorman-client/README.md b/packages/doorman-client/README.md index 79c67cd..1e609af 100644 --- a/packages/doorman-client/README.md +++ b/packages/doorman-client/README.md @@ -1,51 +1,30 @@ -# Make your apartment buzzer smart with Twilio Functions +# doorman-client -I wanted to make my apartment buzzer acessible without a physical key, so I created these Twilio Functions to make my buzzer smarter. Features include: +This is the Twilio Function that is triggered when receiving a call from a buzzer. In short, it's job is to talk to the doorman-api to determine the buzzers configuration and to check if the door should be auto unlocked, or dial through to a phone number on file. -* Voice password (make your friends shout stupid things in public to get into your building!) -* PIN password, a classic -* No obvious weirdness or extra waiting for first-time guests or delivery people -* Notify multiple people until someone picks up the phone - as long as one of the roommates pick up, you won't miss your package +## dependency services +This service has a hard dependency on doorman-api, specifically on the /api/door/info Function. if this is down, the buzzer client will not work. -I kind of went overboard I think, given my original goal. But this was actually *really* easy to develop and set up. And also really cheap. +It has soft dependencies on self hosted monitoring solutions: +- Pushgateway (prometheus metrics) +- Loki (logs) -## How to set this up +## running locally -1. You could `git clone https://github.com/jlian/smart-door-buzzer-twilio-functions.git`, but it's not critical. -2. Get a Twilio account and valid Twilio number. -3. Go to https://www.twilio.com/console/runtime/functions/manage and hit **+**. -4. Add each of the 4 `.js` files into its own function with names that you'd remember. -5. Go to https://www.twilio.com/console/runtime/functions/configure and configure the environment variables: - * `TWILIO_PHONE` with the Twilio number you bought - * `PASSPHRASE` for voice password - * `PASSCODE` for PIN - * `JOHN_PHONE` and others for your cellphone number -5. Go to https://www.twilio.com/console/phone-numbers/incoming and select the phone number you bought earlier. -6. Scroll to where it says **A call comes in**, select **Function**, and then the function that corresponds to `buzzer-activated.js`. -7. Contact your HOA to make the Twilio number your buzzer number - this might be the hardest step. +NOTE: You'll want to make sure that doorman-api is also running locally first. .env.local is configured to use http://localhost:8080 as the doorman-api endpoint -## How this works +First install the necessary dependencies `bun install`. -[Twilio Functions](https://www.twilio.com/functions) is pretty sweet. It's completely serverless so you don't need a VM or computer to keep running an app. It's perfect for something small scale like your apartment buzzer. The flow of this program goes like this: +Run the doorman-client -1. A call comes to the Twilio phone number, `buzzer-activated.js` runs. -1. The [Gather](https://www.twilio.com/docs/api/twiml/gather) verb is used to get either a voice password or a 4-digit PIN. - 1. If correct, `door-open.js` dials a `9` to the buzzer (my building's buzzer code, yours may be different), which opens the door. - 1. If incorrect, `call-residents.js` calls all the residents until someone picks up and manually dial `9` to open the door. -1. When everything is finished, `text-me.js` texts a specified number with info on what happened. +`bun run start` -## How much this costs +To test doorman-client head over to -According to Twilio docs, collecting speech is charged at $.02 per 15 seconds. A Twilio number costs $1/month. Looking at my own billing dashboard, it never exceeds $2/month - pretty reasonable. +`http://localhost:4500/buzzer-activated?From=6133163433` -## Twilio tooling -Using the twilio serverless toolbox you can locally run the functions and test. +This will simulate a buzzer calling from 6133163433 (the test buzzer) -``` -bun run start -``` +If you let it poll for 10s then it should respond with Twilio xml saying to dial fallback numbers. -Deploy to your account with -``` -bun run deploy -``` \ No newline at end of file +If doorman-api is not running, it would always return with a `` \ No newline at end of file diff --git a/packages/doorman-client/package.json b/packages/doorman-client/package.json index 25d154c..28b3e59 100644 --- a/packages/doorman-client/package.json +++ b/packages/doorman-client/package.json @@ -5,7 +5,7 @@ "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "watch-build": "bun run --watch src/index.ts", - "start-twilio": "twilio-run --live --port 4500", + "start-twilio": "twilio-run --live --load-system-env --env .env.local --port 4500", "start": "concurrently \"bun run watch-build\" \"bun run start-twilio\"", "build": "bun run src/index.ts", "deploy": "twilio-run promote --from=staging --to=prod --load-system-env --env .env.twiliotemplate",