Tickets API

This project holds the Coworking Metz tickets API source code, which keep entries about each period a coworker is physically present in the open space.

Getting Started

These instructions will give you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Requirements for the software and other tools to build, test and push

Git - Version control system
NodeJS 20.9+ - Cross-platform JavaScript runtime environment
yarn - Package manager

Install

A step by step series of examples that tell you how to get a development environment running

git clone git@github.com:coworking-metz/tickets-backend.git
cd tickets-backend
yarn

Copy the default environment file and set variable according to your will

cp .env.sample .env

Initialize database with an archive

You can either have a MongoDB process already running or start a new one through Docker prior importing the archive:

docker-compose up -d

docker exec -i tickets-backend-mongodb /usr/bin/mongorestore --nsInclude="tickets.*" --archive < /Users/whatever/2023-09-01-12-00-01-mongo-tickets.mongoarchive

Set up parking remote (Shelly)

To enable parking remote feature, you must define SHELLY_TOKEN (authentication key from your Shelly Cloud or Shelly local account), SHELLY_SERVER (URL to Shelly Cloud server or your local device) and SHELLY_PARKING_REMOTE_DEVICE (device id) in your environment. We assume everything is already configured and output is on channel 0.

:warning: When you change your Shelly account password, your authentication key is refreshed.

Set up Home Assistant

In order to contact Home Assistant, you have to define the following environment variables:

HOME_ASSISTANT_BASE_URL: reachable url of the Home Assistant server (like http://homeassitant.local:8123/). Trailing slash does matter.
HOME_ASSISTANT_LONG_LIVED_TOKEN: Long Lived Token of the Home Assistant account used to retrieve data. You can easily create a new one from the profile page http://homeassitant.local:8123/profile.

To find the entity_id of the entity you want to control, go to http://homeassistant.local:8123/developer-tools/state and look at for the left column named Entity.

[!IMPORTANT] Home Assistant instance is only reachable from the local network or from the production server.

Set up Auth

User identification is processed by WordPress server located on https://www.coworking-metz.fr/ through OAuth2. Once the user has been authenticated by WordPress, tickets-backend adds another layer based on internal business logic (balance, active subscription, membership). This results to a JWT authentification containing basic user information and access.

To learn how to consume JWT authentication, check out AUTH.md.

To properly configure auth, here are the following environment variables to set:

OAUTH_ENABLED: words speak for themselves. Default to 0.
OAUTH_FOLLOW_WHITELIST: list of origins that are allowed to retrieve JWT tokens, separated by commas. Trailing slash does matter.
OAUTH_FOLLOW_ANY: if you want to allow any origin. This should not be enabled in production. Default to 0.
WORDPRESS_BASE_URL: WordPress server managing users. Default to https://www.coworking-metz.fr/.
WORDPRESS_OAUTH_CLIENT_ID: WordPress OAuth plugin client identifier. You will find it the plugin settings.
WORDPRESS_OAUTH_CLIENT_SECRET: WordPress OAuth plugin client secret. You will find it the plugin settings.
JWT_ACCESS_TOKEN_PRIVATE_KEY: anything you want, as long as you don't tell anyone.
JWT_ACCESS_TOKEN_EXPIRATION_TIME: how long an access token should live. In the zeit/ms format. Default to 15m.
JWT_REFRESH_TOKEN_PRIVATE_KEY: anything you want, as long as you don't tell anyone.
JWT_REFRESH_TOKEN_EXPIRATION_TIME: how long an refresh token should live. In the zeit/ms format. Default to 30d.
JWT_REFRESH_TOKEN_SECRET_KEY: anything you want with at least 32 characters. Like it says in the name, keep it secret.

Calendar events

To retrieve events from a iCal calendar, you can setup CALENDAR_EVENTS_URL which should provide events in the ics format.

Start the project

yarn start

Or if you want some live-reload:

yarn dev

Email notifications

Tickets bundles a script to send notification emails to members. You should consider executing this script once a day, at the end of the day.

node scripts/send-notification-emails.js

Pro-tips: use crontab -e

When improving emails and to make sure the email is properly rendered, you can start Greenmail and Roundcube with docker-compose up. This will setup a SMTP/IMAP server and a WebUI for test purposes.

Then properly set your local environment:

SMTP_HOST=localhost
SMTP_PORT=33025
SMTP_USER=anyUser
SMTP_PASS=anyPassword

You should use the following command to take into account the local config when sending emails:

node --env-file .env scripts/send-notification-emails.js

Once emails have been sent, you can read them at http://localhost:38000. Enter the receiver email and any password as credentials to check its mailbox.

If you want to quickly test the rendered result on multiple email client, go to https://testi.at/.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

README-Template for what you're reading

coworking-metz / tickets-backend

readme