Skip to content

Commit

Permalink
Updates INSTALLATION.md to be clearer on Docker installation (Palisad…
Browse files Browse the repository at this point in the history 
…oesFoundation#2269)

* Reordered installation steps

* Reordered installation steps v2

* Fixes 2268

* Fixed TOC
  • Loading branch information
@palisadoes
palisadoes authored Apr 28, 2024
1 parent 636e51c commit 6e196fa
Showing 1 changed file with 111 additions and 54 deletions.
165 changes: 111 additions & 54 deletions INSTALLATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,23 @@ This document provides instructions on how to set up and start a running instanc

# Table of Contents

<!-- toc -->
<!-- TOC -->

- [Talawa-API Installation](#talawa-api-installation)
- [Table of Contents](#table-of-contents)
- [Installation Steps Summary](#installation-steps-summary)
- [Prerequisites](#prerequisites)
- [Install node.js](#install-nodejs)
- [Install npm](#install-npm)
- [Install TypeScript](#install-typescript)
- [Install git](#install-git)
- [Setting up this repository](#setting-up-this-repository)
- [Install node.js](#install-nodejs)
- [Install TypeScript](#install-typescript)
- [Installation Using Docker](#installation-using-docker)
- [Prerequisites](#prerequisites-1)
- [Run the Talawa-API Setup](#run-the-talawa-api-setup)
- [Install the Docker Application](#install-the-docker-application)
- [Docker Compose Setup](#docker-compose-setup)
- [For Development](#for-development)
- [For Production](#for-production)
- [Congratulations! 🎉 Your Talawa API is now successfully set up and running using Docker!](#congratulations-%F0%9F%8E%89-your-talawa-api-is-now-successfully-set-up-and-running-using-docker)
- [Import The Sample Data](#import-the-sample-data)
- [Installation without Docker](#installation-without-docker)
- [Install the Required Packages](#install-the-required-packages)
- [Install MongoDB](#install-mongodb)
Expand All @@ -31,24 +34,24 @@ This document provides instructions on how to set up and start a running instanc
- [The Environment Variables in `.env`](#the-environment-variables-in-env)
- [Changing the Development Environment in the .env file](#changing-the-development-environment-in-the-env-file)
- [Generating Token Secrets](#generating-token-secrets)
- [Setting up ACCESS_TOKEN_SECRET in the .env file](#setting-up-access_token_secret-in-the-env-file)
- [Setting up ACCESS\_TOKEN\_SECRET in the .env file](#setting-up-access_token_secret-in-the-env-file)
- [Linux](#linux)
- [Windows](#windows)
- [Setting up REFRESH_TOKEN_SECRET in the .env file](#setting-up-refresh_token_secret-in-the-env-file)
- [Setting up REFRESH\_TOKEN\_SECRET in the .env file](#setting-up-refresh_token_secret-in-the-env-file)
- [Configuring MongoDB in the .env file](#configuring-mongodb-in-the-env-file)
- [Using the CLI to get the MONGODB_URL Connection String](#using-the-cli-to-get-the-mongodb_url-connection-string)
- [Using Microsoft Windows to get the MONGODB_URL Connection String](#using-microsoft-windows-to-get-the-mongodb_url-connection-string)
- [Using the CLI to get the MONGODB\_URL Connection String](#using-the-cli-to-get-the-mongodb_url-connection-string)
- [Using Microsoft Windows to get the MONGODB\_URL Connection String](#using-microsoft-windows-to-get-the-mongodb_url-connection-string)
- [Configuring Redis in .env file](#configuring-redis-in-env-file)
- [For Local Setup (Linux and WSL)](#for-local-setup-linux-and-wsl)
- [For Remote Setup (Redis Cloud)](#for-remote-setup-redis-cloud)
- [Setting up .env LAST_RESORT_SUPERADMIN_EMAIL parameter in the .env file](#setting-up-env-last_resort_superadmin_email-parameter-in-the-env-file)
- [Setting up .env LAST\_RESORT\_SUPERADMIN\_EMAIL parameter in the .env file](#setting-up-env-last_resort_superadmin_email-parameter-in-the-env-file)
- [Configuring Google ReCAPTCHA in the .env file](#configuring-google-recaptcha-in-the-env-file)
- [Setting up the RECAPTCHA_SECRET_KEY](#setting-up-the-recaptcha_secret_key)
- [Setting up .env MAIL_USERNAME and MAIL_PASSWORD ReCAPTCHA Parameters](#setting-up-env-mail_username-and-mail_password-recaptcha-parameters)
- [Setting up the RECAPTCHA\_SECRET\_KEY](#setting-up-the-recaptcha_secret_key)
- [Setting up .env MAIL\_USERNAME and MAIL\_PASSWORD ReCAPTCHA Parameters](#setting-up-env-mail_username-and-mail_password-recaptcha-parameters)
- [Setting up SMTP Email Variables in the .env File](#setting-up-smtp-email-variables-in-the-env-file)
- [Setting up Logger configurations](#setting-up-logger-configurations)
- [Setting up COLORIZE_LOGS in .env file](#setting-up-colorize_logs-in-env-file)
- [Setting up LOG_LEVEL in .env file](#setting-up-log_level-in-env-file)
- [Setting up COLORIZE\_LOGS in .env file](#setting-up-colorize_logs-in-env-file)
- [Setting up LOG\_LEVEL in .env file](#setting-up-log_level-in-env-file)
- [Importing Sample Database](#importing-sample-database)
- [Syntax:](#syntax)
- [Examples:](#examples)
Expand All @@ -75,81 +78,134 @@ This document provides instructions on how to set up and start a running instanc

<!-- tocstop -->


# Installation Steps Summary

Installation is not difficult, but there are many steps. This is a brief explanation of what needs to be done:

1. Install `git`
2. Download the code from GitHub using `git`
3. Install `node.js` (Node), the runtime environment the application will need to work.
4. Configure the Node Package Manager (`npm`) to automatically use the correct version of Node for our application.
5. Use `npm` to install TypeScript, the language the application is written in.
6. Install other supporting software such as the database.
7. Configure the application
8. Start the application

These steps are explained in more detail in the sections that follow.

# Prerequisites

You will need to have copies of your code on your local system. Here's how to do that.
In this section we'll explain how to set up all the prerequisite software packages to get you up and running.

## Install node.js
## Install git

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](https://github.com/Schniz/fnm) and [nvm](https://github.com/nvm-sh/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 ensure the installation of Node.js version 20 LTS.
The easiest way to get the latest copies of our code is to install the `git` package on your computer.

_**NOTE**_
Follow the setup guide for `git` on official [git docs](https://git-scm.com/downloads). Basic `git` knowledge is required for open source contribution so make sure you're comfortable with it. [Here's](https://youtu.be/apGV9Kg7ics) a good tutorial to get started with `git` and `github`.

1. The repository has a `.node-version` file to help ensure you use the supported version of `node.js`. Do not edit this file.
1. We strongly recommend that you configure your node version manager of choice to automatically read `.node-version` files
## Setting up this repository

_**NOTE**_
First you need a local copy of `talawa-api`. Run the following command in the directory of choice on your local system.

1. On your computer, navigate to the folder where you want to setup the repository.
2. Open a `cmd` (Windows) or `terminal` (Linux or MacOS) session in this folder.
1. An easy way to do this is to right-click and choose appropriate option based on your OS.
3. **For Our Open Source Contributor Developers:**
1. Next, we'll fork and clone the `talawa-api` repository.
1. In your web browser, navigate to [https://github.com/PalisadoesFoundation/talawa-api/](https://github.com/PalisadoesFoundation/talawa-api/) and click on the `fork` button. It is placed on the right corner opposite the repository name `PalisadoesFoundation/talawa-api`.
![Image with fork](public/markdown/images/install1.png)
2. You should now see `talawa-api` under your repositories. It will be marked as forked from `PalisadoesFoundation/talawa-api`
![Image of user's clone](public/markdown/images/install2.png)
3. Clone the repository to your local computer (replacing the values in `{{}}`):
```bash
$ git clone https://github.com/{{YOUR GITHUB USERNAME}}/talawa-api.git
```
4. 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](./CONTRIBUTING.md)
4. **Talawa Administrators:**
1. Clone the repository to your local computer using this command:

```bash
$ git clone https://github.com/PalisadoesFoundation/talawa-api.git
```

1. The repository has a `.node-version` file to help ensure you use the supported version of `node.js`. Do not edit this file.
1. We strongly recommend that you configure your node version manager of choice to automatically read `.node-version` files
## Install node.js

## Install npm
Best way to install and manage `node.js` is making use of node version managers. We recommend using:

npm is a package manager for Node.js and is installed with Node.js. npm is used to install, share, and distribute code as well as to manage dependencies in your projects. To check if you have npm installed you can run this command in your terminal:
- [fnm](https://github.com/Schniz/fnm)

```
npm -v
```
Follow these steps to install the `node.js` packages in Windows, Linux and MacOS.

If you have it installed then you should see the version that's installed. If not, you can download Node.js and npm from the official [Node.js website](https://nodejs.org/en/download/).
1. For Windows:
1. first install `node.js` from their website at https://nodejs.org
1. When installing, don't click the option to install the `necessary tools`. These are not needed in our case.
2. then install `fnm`
1. **Note**: After installing `fnm`:
1. Refer to the installation page's section on the `Shell Setup` recommendations.
2. Enter `Windows PowerShell` in your Windows terminal window
3. Run the recommended `Windows PowerShell` command
4. This will ensure that you are always using the correct version of `node.js`
2. For Linux and MacOS, use the terminal window.
1. install `node.js`
2. then install `fnm`
1. Refer to the installation page's section on the `Shell Setup` recommendations.
2. Run the respective recommended commands to setup your node environment
3. This will ensure that you are always using the correct version of `node.js`
## Install TypeScript
TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. It adds optional types, classes, and modules to JavaScript, and supports tools for large-scale JavaScript applications.
To install TypeScript, you can use npm:
To install TypeScript, you can use the `npm` command which comes with `node.js`:
```bash
npm install -g typescript
```
This command installs TypeScript globally on your system so that it can be accessed from any project.
## Install git
# Installation Using Docker
Follow the setup guide for `git` on official [git docs](https://git-scm.com/downloads). Basic `git` knowledge is required for open source contribution so make sure you're comfortable with it. [Here's](https://youtu.be/apGV9Kg7ics) a good tutorial to get started with `git` and `github`.
This guide provides step-by-step instructions on deploying a talawa-api using Docker. Docker allows you to package your application and its dependencies into a container, providing a consistent environment across different systems.
## Setting up this repository
Here is a list of steps to follow:
1. Run the application setup procedure
2. Install the Docker application
3. Install the Docker helper
4. Install other supporting software such as the database using the `docker-compose` command.
5. Start Docker using the `docker-compose` command
6. Import the sample data into the database
First you need a local copy of talawa-api. Run the following command in the directory of choice on your local system.
## Run the Talawa-API Setup
1. Navigate to the folder where you want to setup the repository. Here, I will set it up in a folder called `talawa`.
1. 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-api` repository.
1. Navigate to [https://github.com/PalisadoesFoundation/talawa-api/](hhttps://github.com/PalisadoesFoundation/talawa-api/) and click on the `fork` button. It is placed on the right corner opposite the repository name `PalisadoesFoundation/talawa-api`.
![Image with fork](public/markdown/images/install1.png)
1. You should now see `talawa-api` under your repositories. It will be marked as forked from `PalisadoesFoundation/talawa-api`
![Image of user's clone](public/markdown/images/install2.png)
1. Clone the repository to your local computer (replacing the values in `{{}}`):
We have created a setup script to make configuring Talawa-API easier.
1. You can do this by running the command below.
2. Default answers will be given with capital letters
3. Details of what each prompt means can be found in the [Configuration](#configuration) section of this document.
```
$ git clone https://github.com/{{YOUR GITHUB USERNAME}}/talawa-api.git
npm run setup
```
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](./CONTRIBUTING.md)
## Install the Docker Application
`NOTE: All the commands we're going to execute in the following instructions will assume you are in the root directory of the project. If you fail to do so, the commands will not work.`
There are many ways to install Docker. We reccommend using Docker Desktop. It can be downloaded here:
# Installation Using Docker
- Download [Docker Desktop](https://www.docker.com/products/docker-desktop) using this link.
This guide provides step-by-step instructions on deploying a talawa-api using Docker. Docker allows you to package your application and its dependencies into a container, providing a consistent environment across different systems.
## Docker Compose Setup
## Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop) installed on your machine.
After installing Docker, you'll need to tell Docker to install the additional software it will need to run the application.

## Docker Compose Setup
The setup steps differ depending on whether you are working in a development or production environment.

### For Development

Follow these steps for setting up a software development environment.

1. **Build and Start Development Containers:**
```
docker-compose -f docker-compose.dev.yaml up --build
Expand All @@ -166,6 +222,8 @@ This guide provides step-by-step instructions on deploying a talawa-api using Do

### For Production

Follow these steps for setting up a production environment.

1. **Build and Start Production Containers:**
```
docker-compose -f docker-compose.prod.yml up --build -d
Expand All @@ -180,10 +238,9 @@ This guide provides step-by-step instructions on deploying a talawa-api using Do
docker-compose -f docker-compose.prod.yml down
```

### Congratulations! 🎉 Your Talawa API is now successfully set up and running using Docker!
## Import The Sample Data

**Note: If you're using Docker, you'll need to manually import the sample data after the Docker Compose has started the MongoDB container. For instructions on how to do this, refer to [Importing Sample Database](#importing-sample-database)**
You'll need to manually import the sample data after the Docker Compose has started the MongoDB container. For instructions on how to do this, refer to the [Importing Sample Database](#importing-sample-database) section of this document.
# Installation without Docker
Expand Down Expand Up @@ -211,7 +268,7 @@ We're listing some common approaches to set up a running instance of MongoDB dat

## Install Redis

Talawa-api makes use of `Redis` for caching frequently accessed data items in the primary database. We make use of `ioredis` to interact with the `redis-server` from within the code. The main Idea is the in production this will act as an in-memory cache. So it is recommended that you set it up locally. However for simplicity purposes, a section to accomodate for setting Redis up using a remote instance like Redis Cloud has been added. Please note that this is not recommended since the remote connection takes a considerable amount of time to be considered as a cache to improve application performance.
Talawa-api makes use of `Redis` for caching frequently accessed data items in the primary database. We make use of `ioredis` to interact with the `redis-server` from within the code. The main Idea is the in production this will act as an in-memory cache. So it is recommended that you set it up locally. However for simplicity purposes, a section to accommodate for setting Redis up using a remote instance like Redis Cloud has been added. Please note that this is not recommended since the remote connection takes a considerable amount of time to be considered as a cache to improve application performance.

### Performance Benefits

Expand Down

0 comments on commit 6e196fa

Please sign in to comment.