Ring Intercom Control

Self-hosted web app to manage Ring Intercom access for B&B and small hospitality workflows.

Main use case: create temporary guest links (check-in/check-out window) so guests can unlock the door only during their stay.

Supported languages: English, Italian, Spanish, German.

Documentation

Most project details are maintained in Docusaurus:

• Docs source: website/
• Intro: website/docs/intro.md
• Architecture: website/docs/architecture.md
• API (generated from backend docstrings): website/docs/api/reference.md
• Deployment: website/docs/deployment.md
• Development: website/docs/development.md
• Security: website/docs/security.md
• Contributing: website/docs/contributing.md

Published docs:

• https://mrgionsi.github.io/ring-intercom-control/

Key Capabilities

• Ring account integration (single or multiple accounts per user)
• Intercom unlock from web dashboard
• Guest links with start/end window and max-use limit
• Admin/user role model
• Audit trails for unlocks and login attempts

UI Preview

Login

Dashboard

Guest Links

Settings

Users (Admin)

Quick Start

Prerequisite: Node.js 20.17.0 or newer. The repository includes .nvmrc with the CI/docs baseline (20.19.0).

cd backend && npm install
cd ../frontend && npm install

cd backend
cp .env.example .env
npm run dev

cd frontend
npm run dev

App URLs:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

For complete setup, security, Docker, and CI/CD instructions, use the Docusaurus docs above.

Docker Deployment

The project supports containerized deployment for both backend and frontend.

• Backend image: backend/Dockerfile
• Frontend image: frontend/Dockerfile
• Compose stack: docker-compose/docker-compose.yml
• Env template: docker-compose/.env.example

Frontend Container (Standalone)

Build:

docker build ./frontend -t mrgionsi/ring-intercom-control-frontend:0.1.0-beta

Run:

docker run --rm -p 5173:5173 \
  -e PORT=5173 \
  -e BACKEND_URL=http://host.docker.internal:3001 \
  mrgionsi/ring-intercom-control-frontend:0.1.0-beta

Notes:

• BACKEND_URL is optional. If set, /api/* requests are proxied to backend.
• host.docker.internal works by default on Docker Desktop (Windows/macOS). On Linux, add:
  • --add-host=host.docker.internal:host-gateway
• Health endpoint inside container: GET /health returns { "ok": true }.
• Static cache policy:
  • index.html: no-cache
  • /assets/*: public, max-age=31536000, immutable

Docker Compose (Backend + Frontend)

Files:

• docker-compose/docker-compose.yml
• docker-compose/.env

Run:

cd docker-compose
cp .env.example .env
docker compose up -d

Stop:

cd docker-compose
docker compose down

Container logs are written to stdout/stderr, so they are visible with:

docker logs ring-intercom-backend
docker logs ring-intercom-frontend

Validation and QA

Build Checks

cd backend && npm run build
cd ../frontend && npm run build

Smoke Tests

PowerShell:

scripts/smoke-test.ps1

Bash:

scripts/smoke-test.sh

Optional authenticated smoke checks:

• SMOKE_USERNAME=<username>
• SMOKE_PASSWORD=<password>
• SMOKE_BASE_URL=http://localhost:3001

Security Audit

PowerShell:

scripts/security-check.ps1

Bash:

scripts/security-check.sh

Known Dependency Advisories

Current npm audit reports high-severity vulnerabilities in transitive dependencies:

• ip via ring-client-api -> werift / werift-ice; ip@2.0.1 is still the latest published version and npm's fix path is a breaking downgrade of ring-client-api.

These are currently tracked and deferred until upstream fix availability.

The docs site currently reports moderate dev-server advisories through Docusaurus' webpack-dev-server -> sockjs -> uuid dependency chain. The static production docs build is successful, and npm reports no available Docusaurus fix yet.

Branching Model

• main: stable, production-ready branch
• dev: integration and pre-release branch
• feature/*: short-lived implementation branches
• hotfix/*: emergency fixes from main

Roadmap

• Optional managed DB migration path (Supabase/Postgres)
• Extended automated test coverage (API + UI)

License

• See LICENSE.

Community

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support: SUPPORT.md
• Issues: https://github.com/mrgionsi/ring-intercom-control/issues