This document provides instructions on how to set up and start a running instance of talawa-admin on your local system. The instructions are written to be followed in sequence so make sure to go through each of them step by step without skipping any sections.
- Talawa-Admin Installation
- Table of Contents
- Prerequisites for Developers
- Installation
- Configuration
- Post Configuration Steps
- Testing
We recommend that you follow these steps before beginning development work on Talawa-Admin:
- Talawa-API: (This is mandatory) The API system that the mobile app uses for accessing data. Setup your own local instance
- Talawa: (Optional) The mobile app that people will use to access Talawa's features. This may be useful if you need to verify administrative features you have added or modified.
The INSTALLATION.md files in both repositories show you how. The Talawa-API INSTALLATION.md will also show you the Organization URL to use access Talawa Admin.
You will need to have copies of your code on your local system. Here's how to do that.
First you need a local copy of talawa-admin. Run the following command in the directory of choice on your local system.
git clone https://github.com/PalisadoesFoundation/talawa-admin
This will download a local copy of talawa-admin in that directory.
Right after cloning the repo you can change the directory of your current terminal(shell) to the root directory of cloned repository using this command:
cd talawa-admin
NOTE: All the commands we're going to execute in the following instructions will assume you are in the root directory of the cloned talawa-admin project. If you fail to do so, the commands will not work.
If you've followed the previous steps you should have already set up node.js on your system. Click here for the official setup guide for npm.
Run the following command to install the packages and dependencies required by talawa-admin:
npm install --legacy-peer-deps
It's important to configure Talawa-Admin. Here's how to do it.
A file named .env is required in the root directory of talawa-admin for storing environment variables used at runtime. It is not a part of the repo and you will have to create it. For a sample of .env file there is a file named .env.example in the root directory. Create a new .env file by copying the contents of the .env.example into .env file. Use this command:
cp .env.example .env
This .env file must be populated with the following environment variables for talawa-admin to work:
| Variable | Description |
|---|---|
| REACT_APP_TALAWA_URL | URL endpoint for talawa-api graphql service |
| REACT_APP_USE_RECAPTCHA | Whether you want to use reCAPTCHA or not |
| REACT_APP_RECAPTCHA_SITE_KEY | Site key for authentication using reCAPTCHA |
Follow the instructions from section Setting up REACT_APP_TALAWA_URL in .env file up to and including section Setting up REACT_APP_RECAPTCHA_SITE_KEY in .env file to set up these environment variables.
Add the endpoint for accessing talawa-api graphql service to the variable named REACT_APP_TALAWA_URL in the .env file.
REACT_APP_TALAWA_URL="http://API-IP-ADRESS:4000/graphql/"
If you are a software developer working on your local system, then the URL would be:
REACT_APP_TALAWA_URL="http://localhost:4000/graphql/"
For additional details, please refer to to the How to Access the Talawa-API URL section in the INSTALLATION.md file found in the Talawa-API repo.
You may not want to setup reCAPTCHA since the project will still work. Moreover, it is recommended to not set it up in development environment.
Just skip to the Post Configuration Steps if you don't want to set it up. Else, read the following steps.
If you want to setup Google reCAPTCHA now, you may refer to to the RECAPTCHA section in the INSTALLATION.md file found in Talawa-API repo.
Talawa-admin needs the reCAPTCHA site key for the reCAPTCHA service you set up during talawa-api installation as shown in this screenshot:
Copy/paste this reCAPTCHA site key to the variable named REACT_APP_RECAPTCHA_SITE_KEY in .env file.
REACT_APP_RECAPTCHA_SITE_KEY="this_is_the_recaptcha_key"
It's now time to start Talawa-Admin and get it running
Run the following command to start talawa-admin development server:
npm run serve
By default talawa-admin runs on port 3000 on your system's localhost. It is available on the following endpoint:
http://localhost:3000/
The first time you navigate to the running talawa-admin's website you'll land at talawa-admin registration page. Sign up using whatever credentials you want and create the account. Make sure to remember the email and password you entered because they'll be used to sign you in later on.
Now sign in to talawa-admin using the email and password you used to sign up.
It is important to test our code. If you are a contributor, please follow these steps.
You can run the tests for talawa-admin using this command:
npm run test
You can see the output of failing tests in broswer by running jest-preview package before running your tests
npm run jest-preview
npm run test
You don't need to re-run the npm run jest-preview command each time, simply run the npm run test command if the Jest Preview server is already running in the background, it'll automatically detect any failing tests and show the preview at http://localhost:3336 as shown in this screenshot -
You can lint your code files using this command:
npm run lint:fix
We are using the package Husky to run git hooks that run according to different git workflows.
We run a pre-commit hook which automatically runs code quality checks each time you make a commit and also fixes some of the issues. This way you don't have to run them manually each time.
If you don't want these pre-commit checks running on each commit, you can manually opt out of it using the --no-verify flag with your commit message as shown:-
git commit -m "commit message" --no-verify
We are also running a post-merge(post-pull) hook which will automatically run "npm install --legacy-peer-deps" only if there is any change made to pakage.json file so that the developer has all the required dependencies when pulling files from remote.
If you don't want this hook to run, you can manually opt out of this using the no verify flag while using the merge command(git pull):
git pull --no-verify