Local Setup¶

Goal: run uengage-crm locally against local MongoDB/MySQL/Redis, and understand how to work with prism-services.

1. Prerequisites¶

Tool	Version	Why
Node.js	16–18 recommended for monolith (deps target this era); 22.x for prism-services	runtime
npm	bundled	monolith deps
Yarn	latest	prism-services deps
MongoDB	4.x+ local	primary datastore (`uengage` DB)
MySQL	5.7/8.x local	transactional data (`addo_*` tables)
Redis	6+ local (or point to a dev ElastiCache)	cache
PM2	global (`npm i -g pm2`)	prod-style process mgmt (optional locally)
Serverless Framework	global (for prism-services deploy)	Lambda deploy

2. Clone both repos¶

# from your workspace root
#   /uengage-crm       ← this repo (monolith)
#   /prism-services    ← serverless

3. uengage-crm — configure environment¶

The repo ships a committed .env.dev (⚠️ this is a security smell — see Security — but it makes local bootstrap easy). config.js loads .env.dev when NODE_ENV=dev.

Key variables (names only — set real local values):

Variable	Local value	Notes
`NODE_ENV`	`dev`	selects `.env.dev`
`HOST` / `PORT`	`localhost` / `3000`	server bind
`DB_URL_STRING`	`mongodb://0.0.0.0:27017`	local MongoDB; DB name is hardcoded to `uengage`
`SQL_HOST` / `SQL_USER` / `PASSWORD` / `DATABASE`	`localhost` / … / … / `uengageDB`	local MySQL
`CONNECTION_LIMIT` / `WEB_CONNECTION_LIMIT` / `JOBS_CONNECTION_LIMIT`	20 / 15 / 10	pool sizes
`REDIS_HOST` / `REDIS_PORT`	local or dev	⚠️ `utilities/redis.js` currently hardcodes an ElastiCache host — you may need to edit it for local dev, or provide network access

⚠️ Redis is hardcoded to an AWS ElastiCache endpoint in utilities/redis.js. For true offline dev, temporarily point it at 127.0.0.1:6379. Do not commit that change.

4. Install & run the monolith¶

cd uengage-crm
npm install

# dev (nodemon, NODE_ENV=dev)
npm run start:dev

# prod-style
npm run start          # NODE_ENV=prod node index.js

package.json scripts:

Script	Command	Use
`start:dev`	`NODE_ENV=dev nodemon index.js`	local development
`start` / `start:prod`	`NODE_ENV=prod node index.js`	production run

On boot you should see: config loaded → crons registered → routes mounted → Socket.IO up → server.listen → MongoDB connected → Redis connected. If Mongo fails, the process exits(1); if Redis fails it logs but continues.

⚠️ Crons run locally too¶

All 91 crons register at startup. When developing, you may want to comment out heavy crons in index.js (there's a comment there: "Comment these crons if DB is attached to production env") so your machine isn't hammering data. Never point local crons at production DBs.

5. Running with PM2 (prod parity)¶

crm_ecosystem.config.js defines dev and prod app environments (MySQL/MongoDB creds read from env at startup).

pm2 start crm_ecosystem.config.js --env dev
pm2 logs
pm2 status

6. prism-services (serverless)¶

cd prism-services
yarn

Environment (per serverless-*.yml): MONGODB_URI, KAFKA_BROKER_URL. ⚠️ These are currently hardcoded in the YML files (Mongo Atlas URI + MSK broker list) — see Security. For local testing you generally invoke handlers directly rather than standing up Kafka:

# deploy (normally done by CI on main; needs AWS creds + VPC access)
serverless deploy --config serverless-orders.yml --stage prod
serverless deploy --config serverless-whatsapp.yml --stage prod

Because the consumers are triggered by MSK inside a VPC, full local emulation is impractical — prefer unit-testing the handler functions in src/**/handlers/* with a sample event, and use a dev MongoDB.

7. Smoke test¶

# monolith health: hit an ingestion endpoint with the dev token
curl -X POST http://localhost:3000/injestion/uengage \
  -H 'Content-Type: application/json' \
  -d '{"...":"sample order payload"}'
# then check MongoDB:
#   use uengage; db.crm_queue.find().sort({insertedAt:-1}).limit(1)

See API for payload shapes and Order Ingestion for the queue lifecycle.

8. Common setup pitfalls¶

Symptom	Cause	Fix
Process exits on boot	MongoDB not reachable	start local mongod; check `DB_URL_STRING`
Redis connect errors spam	hardcoded ElastiCache host unreachable	edit `utilities/redis.js` to local host (don't commit)
MySQL `ER_ACCESS_DENIED`	wrong `SQL_USER`/`PASSWORD`/`DATABASE`	align `.env.dev` with your local MySQL
CPU spikes locally	crons hammering	comment heavy crons in `index.js`
`@uengage.io/js-logger` missing	internal npm pkg	logger-service falls back to NullLogger; safe to ignore locally

System Overview · Project Structure · Deployment

Assignment¶

See ../15-Assessments/Assignments.md → "Get it running & trace one order".