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.
We recommend that you to follow these steps before beginning development work on Talawa-Admin:
- You need to have
nodejsinstalled in your machine. We recommend using Node version greater than 20.0.0. You can install it either through nvm (Node Version Manager) or by visiting the official Nodejs website. - 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.
- Navigate to the folder where you want to setup the repository. Here, I will set it up in a folder called
talawa. - Navigate to the folder and open a terminal in this folder (you can right-click and choose appropiate option based onn your OS). Next, we'll fork and clone the
talawa-adminrepository. - Navigate to https://github.com/PalisadoesFoundation/talawa-admin/ and click on the
forkbutton. It is placed on the right corner opposite the repository namePalisadoesFoundation/talawa-admin. - You should now see
talawa-adminunder your repositories. It will be marked as forked fromPalisadoesFoundation/talawa-admin - Clone the repository to your local computer (replacing the values in
{{}}):
$ git clone https://github.com/{{YOUR GITHUB USERNAME}}/talawa-admin.git
This will setup the repository and the code files locally for you. For more detailed instructions on contributing code, and managing the versions of this repository with Git, checkout CONTRIBUTING.md here
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.
Best way to install and manage node.js is making use of node version managers. Two most popular node version managers right now are fnm and nvm. We'd recommend fnm because it's written in rust and is much faster than nvm. Install whichever one you want and follow their guide to set up node.js on your system.
NOTE
- The repository has a
.node-versionfile to help ensure you use the supported version ofnode.js. Do not edit this file. - We strongly recommend that you configure your node version manager of choice to automatically read
.node-versionfiles
As talawa-admin and talawa-api repositories are written using Typescript, you will need to install typescript on your machine.
We recommend to install Typescript globally on your machine by running the following command in the terminal:
npm install -g typescript
For more details please refer to the installation guidelines provided in the official docs.
Run the following command to install the packages and dependencies required by talawa-admin:
npm install
It's important to configure Talawa-Admin. Here's how to do it.
You can use our interactive setup script for the configuration. Use the following command for the same.
npm run setup
All the options in "setup" can be done manually as well and here's how to do it. - Creating .env file
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 |
|---|---|
| PORT | Custom port for Talawa-Admin development purposes |
| 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 the sections Setting up PORT in .env file, Setting up REACT_APP_TALAWA_URL in .env file, Setting up REACT_APP_RECAPTCHA_SITE_KEY in .env file and Setting up Compiletime and Runtime logs to set up these environment variables.
Add a custom port number for Talawa-Admin development purposes to the variable named PORT in the .env file.
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/"
If you are trying to access Talawa Admin from a remote host with the API URL containing "localhost", You will have to change the API URL to
REACT_APP_TALAWA_URL="http://YOUR-REMOTE-ADDRESS:4000/graphql/"
For additional details, please refer 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 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"
Set the ALLOW_LOGS to "YES" if you want warnings , info and error messages in your console or leave it blank if you dont need them or want to keep the console clean
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 4321 on your system's localhost. It is available on the following endpoint:
http://localhost:4321/
If you have specified a custom port number in your .env file, Talawa-Admin will run on the following endpoint:
http://localhost:${{customPort}}/
Replace ${{customPort}} with the actual custom port number you have configured in your .env file.
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" 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