From 636e51cbbe15d318485f32dd0072d0c2d4a3be7e Mon Sep 17 00:00:00 2001 From: Peter Harrison <16875803+palisadoes@users.noreply.github.com> Date: Sat, 27 Apr 2024 14:42:14 -0700 Subject: [PATCH 1/2] Added new media directories (#2267) * Added new media directories * Changed order for .gitignore file * Added media directories * Updated media directory files * Removed references to files in media directories * Removed log/README.md reference --- .github/workflows/pull-request.yml | 3 --- .gitignore | 12 +++++------- images/.gitignore | 4 ++++ logs/.gitignore | 6 ++++-- logs/README.md | 17 ----------------- videos/.gitignore | 4 ++++ 6 files changed, 17 insertions(+), 29 deletions(-) create mode 100644 images/.gitignore delete mode 100644 logs/README.md create mode 100644 videos/.gitignore diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 68d2897ced..dc26bf8931 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -231,9 +231,6 @@ jobs: with: time: 10s - - name: Create a videos directory - run: mkdir -p videos - - name: Run the tests run: npm run test diff --git a/.gitignore b/.gitignore index 65e2794e5e..e25629d39e 100644 --- a/.gitignore +++ b/.gitignore @@ -17,20 +17,16 @@ node_modules/** .env .env_test -# Ignore uploads +# Ignore upload directories image/** images/** video/** videos/** # Ignore log files -logs/* -!logs/README.md +logs/** *.log -# Don't ignore any .gitignore files in any location -!.gitignore - # Added as the documentation only refers to npm, not yarn and pnpm. yarn.lock pnpm-lock.yaml @@ -46,6 +42,8 @@ key.pem csr.pem # MacOS - .DS_STORE +# Don't ignore any .gitignore files in any location +!.gitignore + diff --git a/images/.gitignore b/images/.gitignore new file mode 100644 index 0000000000..5e7d2734cf --- /dev/null +++ b/images/.gitignore @@ -0,0 +1,4 @@ +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/logs/.gitignore b/logs/.gitignore index e1cf583655..5e7d2734cf 100644 --- a/logs/.gitignore +++ b/logs/.gitignore @@ -1,2 +1,4 @@ -# DO NOT REMOVE -# This is required to maintain the logs/ directory in the repo +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/logs/README.md b/logs/README.md deleted file mode 100644 index fe24b7b4a9..0000000000 --- a/logs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Logs Directory - -## Overview - -This directory is the default location for the logs generated by the audit trailing mechanism of our application. The logging system is designed to provide a comprehensive and chronological record of events, actions, and operations performed within the application, offering transparency and accountability. - -## Setup Instructions - -### Initial Setup - -To initialize the logging system and ensure that all necessary configurations are correctly established, please run the following command from the root of the project: - -```bash - -npm run setup - -``` diff --git a/videos/.gitignore b/videos/.gitignore new file mode 100644 index 0000000000..5e7d2734cf --- /dev/null +++ b/videos/.gitignore @@ -0,0 +1,4 @@ +# Ignore everything in this directory +* +# Except this file +!.gitignore From 6e196fa63a3040bc2000c6612df53e54605f1113 Mon Sep 17 00:00:00 2001 From: Peter Harrison <16875803+palisadoes@users.noreply.github.com> Date: Sun, 28 Apr 2024 06:28:37 -0700 Subject: [PATCH 2/2] Updates INSTALLATION.md to be clearer on Docker installation (#2269) * Reordered installation steps * Reordered installation steps v2 * Fixes 2268 * Fixed TOC --- INSTALLATION.md | 165 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 111 insertions(+), 54 deletions(-) diff --git a/INSTALLATION.md b/INSTALLATION.md index 1549967cd0..9dce689e99 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -4,20 +4,23 @@ This document provides instructions on how to set up and start a running instanc # Table of Contents - + +- [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) @@ -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) @@ -75,39 +78,86 @@ This document provides instructions on how to set up and start a running instanc + +# 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 @@ -115,41 +165,47 @@ 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 @@ -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 @@ -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 @@ -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