Running Trustroots locally
These instructions are for installing locally. If you’d like to have containerised setup, see Installing with Docker instead.
Prerequisites
Make sure you have installed all these prerequisites:
- Unix operating system, like Linux or MacOS. If you use Windows, please look into installing via Docker instead.
- Git (
git --version
, preinstalled on MacOS) - Node.js:
- See “engines” from
package.json
for supported versions - Use
node --version && npm --version
to check your current version. - We recommend managing Node.js versions using NVM.
- See “engines” from
- MongoDB
- See “engines” from
package.json
for supported versions - Use
mongod --version
to check your current version.
- See “engines” from
- Some of the NPM modules require compiling native code, which might require installing:
- MacOS: X-Code’s Command line tools. You can install or confirm they’re installed by running
xcode-select --install
- Linux:
build-essential
andmake
- MacOS: X-Code’s Command line tools. You can install or confirm they’re installed by running
- GraphicsMagick.
- In MacOS, you can simply use Homebrew to install it:
brew install graphicsmagick
- In MacOS, you can simply use Homebrew to install it:
Installing
1. Clone the repository:
git clone https://github.com/Trustroots/trustroots.git
cd trustroots
2. Make sure MongoDB is running on the default port (27017):
mongod
Optional: If you need to modify connection settings, see config/env/local.js
config file.
3. Install dependencies and start the app:
npm ci
npm start
🎉 Open http://localhost:3000 in your browser.
Good to know
- Run the app by typing
npm start
. - Run commands in production mode by appending
NODE_ENV
to command, e.g.:NODE_ENV=production npm start
. - Stop the app by hitting
Ctrl+C
. - When you change any file, they get recompiled and the browser is refreshed.
- Keep an eye on the console in case of compiling errors.
- NPM dependencies can be updated with
npm ci
- You can start clean by running
npm run dropdb && npm run distclean
.
Modifying configurations
Add any configurations you want to keep out of version control to config/env/local.js
file. It’s created for you on the first start and overrides anything in config/env/local.js
.
Development tools
Emails
MailDev is there for viewing and testing emails during development.
MailDev will be already running at localhost:1080 but if you need to run it manually, type:
npm run dashboard:mail
Background jobs
Agendash is a dashboard & inspector for Agenda, our job scheduling library.
To run it at localhost:1081, type:
npm run dashboard:jobs
Debugging
The standard node inspector runs on each start for the main app (port 5858) and the worker (port 5859).
To debug using Chrome:
- Run ‘npm start’
- Open
chrome://inspect/#devices
. Note the “Remote Target” list should be empty to start - Press “Open dedicated DevTools for Node”
- Press “Add connection” and add both
localhost:5858
andlocalhost:5859
- They will now appear in “Remote Target” list
- Press ‘inspect’ on whichever process you want to debug
- You should now have console/profiler etc available.
More information can be found in the NodeJS debug documentation.
Access the server from another device
- Make sure you are connected to the same network (WIFI/LAN). Find your ip address using
ipconfig
orifconfig
. - Add
host: null
intoconfig/env/local.js
- Alternatively you can also use service like Ngrok.
Running tests
npm test
(both client & server)npm run test:client
npm run test:client:watch
(run + watch for changes)npm run test:server
npm run test:server:watch
(run + watch for changes)
Analyzing bundles
You can see what goes into the “bundle” that Webpack compiles from all the JS, style and image assets by adding this to your config/env/local/js
:
bundleAnalyzer: {
enabled: true,
// See https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-plugin
options: {},
},
Now when you start the application, bundle analyzer will automatically open new browser tab at http://127.0.0.1:8888/
that shows you information about the bundle.
Coding styles
We apply Eslint rules to our JavaScript files and automatically format them using Prettier. You should install Eslint editor integration as well Prettier editor integration to notice code formatting errors and let the editor autoformat files for you automatically.
Files are autoformatted by Prettier each time you git commit
your changes.
Files are also continuously linted as you modify them when running npm start
, but if you need to lint all the files separately, run:
npm run lint
To continuously lint files as you modify them, run:
npm run lint:watch
To let Eslint fix linting errors automatically, append -- --fix
to either regular lint or -watch command like so:
npm run lint:watch -- --fix
Mock data
There is a data script that the individual mock data scripts with default values to generate mock user data, hosting offers, messages and tribes. It’s highly recommended you run this script after installation, that way you’ll have something to look at.
Run npm run seed
- This will add automatically add:
- 100 tribes
- 1000 users including 3 users with user names of
admin1
,admin2
,admin3
each with the password ofpassword123
- 2000 message threads with 1 to 10 messages in each thread
For more custom setups, you can alternatively run the scripts for generating data individually. It is currently recommended that you run them in the sequence provided below.
-
To add tribes, run
npm run seed:tribes 50
— This will create 50 tribes.- Run this prior to adding users to add users to tribes automatically
-
To add users, run
npm run seed:users 1000 -- --userNames adminusername
— This will create 1000 users and hosting offers.adminusername
is optional (a-z0-9) and will create an admin user.- It can take up to 5 minutes. Mongoose might complain about duplicates — just ignore these errors.
- To see the result, log in with your chosen username and password
password123
. - Additional admin usernames are also supported (eg.
npm run seed:users 1000 -- --userNames admin1 admin2 admin3
) - If tribes exist, users will also be added to random tribes
-
To add messages, run
npm run seed:messages 1000 10
— This will create 1000 message threads between random users with up to 10 messages in each thread.
All scripts additionally support --debug
and --limit
flags showing database debug information and not creating new elements if the number of database items already exist respectively.
Clean database
To drop your database, run:
npm run dropdb
Enable FCM push notifications (optional)
-
Create FCM account
-
Go to FCM console and create a new project
-
Open the project and hit the small gear next to “Overview” at the sidebar so that you get to “project settings” page
-
Choose “Cloud messaging” tab, copy “Sender ID” number
-
Choose “Service accounts” tab
-
Either “create new service account” via “Manage all service accounts” link or choose existing one from the list (for development, “Firebase Admin SDK” account is fine)
-
Click on the “Generate new private key” button
-
Choose “json” format and you’ll get a file to download
-
Add contents from that file to your
./config/env/local.js
:fcm: { senderId: 'PASTE_YOUR_SENDER_ID_NUMBER_HERE', serviceAccount: PASTE_YOUR_JSON_CONFIG_HERE },
-
To stop Eslint from complaining, you might need to convert double quotes to single quotes. (
"
→'
) or disable Eslint for those lines.
Enable collecting statistics to InfluxDB (optional)
-
Install InfluxDB v1.0+ and run it (type
influxd
) -
Add InfluxDB configuration to your
./config/env/local.js
:influxdb: { enabled: true, options: { host: 'localhost', port: 8086, // default 8086 protocol: 'http', // default 'http' // username: '', // password: '', database: 'trustroots' } }
-
You can observe data through InfluxDB admin panel: localhost:8083 or optionally install Grafana and connect it to InfluxDB.
-
Read more about the collected data and metrics
Use ImageMagick instead of GraphicsMagick
If you prefer ImageMagick over GraphicsMagick:
-
In MacOS, you can simply use Homebrew to install it:
brew install imagemagick
-
Change
imageProcessor
setting from./configs/env/local.js
toimagemagic
.
Support
- Check and open issues at GitHub
- Contact us
- Volunteer chat