Skip to content

Latest commit

 

History

History
301 lines (239 loc) · 13.2 KB

DOCS.md

File metadata and controls

301 lines (239 loc) · 13.2 KB

JASMA (OLD) Documentation

NOTE: THIS DOCUMENTATION IS DEPRECATED

Table of Contents

Tech Stack:

Frontend:

  • NextJS / React
  • TailwindCSS
  • React Query
  • Recoil
  • Axios
  • Font Awesome

Backend:

  • ExpressJS
  • PostGreSQL
  • Redis
  • NodeJS
  • Sequelize

Getting started

NOTE: The most easiest way to quickly get started is by using Docker. Go to 'Getting started with Docker' to read more about this.

Prerequisites

  • Install PostGreSQL
    sudo apt install postgresql
  • Install Redis
    sudo apt install redis-server
  • Install NPM
    sudo apt install npm
  • Install NodeJS
    sudo apt install nodejs

Install the minimal requirements to start development:
sudo apt install nodejs npm redis-server postgresql

Install node modules

In the root folder:
npm run installAll

Configure environment variables

Make sure to copy the following files and then edit them to setup the environment variables
from /express/.env.example to /express/.env
and from /next/.env.example to /next/.env.development
DO NOT EDIT OR RENAME .env.example DIRECTLY!
Use the following command to copy the files:
cd express && cp .env.example .env && cd ../next && cp .env.example .env.development

For local development you can keep the default environment variables.
For production change HOSTNAME and NEXTJS_ORIGIN to your domain name or ip address.
Change the ports accordingly as well as the PG_ADMIN_PASSWORD.

Setting up the database

After you have installed PostGreSQL. You can execute the following command to change the PSQL root user password.

  • sudo -u postgres psql --echo-queries -c "ALTER ROLE postgres WITH LOGIN PASSWORD 'example';"
    Change 'example' into a password of your liking. Make sure its the same as in the /express/.env file.
    To create the database do the following command:
  • npm run db:init
    To populate the database with fake users, posts, and comments. Replace 10 with the amount of each you want to generate.
  • npm run db:generate 10

Starting the app

There are several methods to start the app from the root directory.

  • npm run dev Starts the API, media, and client servers in 1 terminal, in development mode with live reloading (nodemon/next).
  • npm run start Starts the API, media, and client servers in 1 terminal, in production mode.
  • npm run dev:all Same as npm run dev, but every server starts in its own terminal.
  • npm run start:all Same as npm run start, but every server starts in its own terminal.
  • npm run start:pm2 Starts all servers as background proccesses without terminals. Requires pm2 to be installed.
  • Use npm run to see all available commands.
  • With npm run check:services you can see if Redis, PostgreSQL, Nginx, and pm2 are running and which ports are being listened on.
  • Make sure to use the command npm run build before starting NextJS in production mode. (any command with start).

You can also independently start each server with the commands.

  • cd express && npm run dev
  • cd next && npm run dev
  • cd media-server && npm run dev

Open http://localhost:3000 with your browser to see the app. API server lives on http://localhost:5000/api

Getting started with Docker

Prerequisites

First you need to install Docker. Note that that this app has not yet been tested with Docker Desktop.
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
For detailed installation instruction go to the docker installation manual

Once docker is installed copy either docker-compose-production.yml or docker-compose-development.yml to docker-compose.yml.
Use the following command to do so:
cp docker-compose-development.yml docker-compose.yml

NOTE: If you are running the postgresql, redis, or nginx services on your host machine you need to turn them off

Or else you might connect to those services instead of the docker services.
You can stop those services with the following commands:

sudo systemctl stop postgresql
sudo systemctl stop redis-server
sudo systemctl stop nginx
# Optional: Check the status of each service to make sure they stopped.
sudo systemctl status postgresql 
sudo systemctl status redis-server
sudo systemctl status nginx

It may be possible run both these services on your host machine and in the docker containers,
if the docker containers have differents (external) ports for those containers.

Configure Docker environment variables

You may need to change a few environment variables in your docker-compose.yml file.
If this is your very first time starting the app with Docker then you need to set the following environment variable to true
START_FIRST_TIME=true
After the containers have started you need to change it to START_FIRST_TIME=false.
This will env variable will delete any postgresql databases that exist for the app and then create a new one when it is set to true.

If you are using Docker for production then change the following environment variables to your host machine IP address or your domain name.
Example:

NEXTJS_ORIGIN=http://192.168.1.10
NEXT_PUBLIC_API_SERVER_URL=192.168.1.10

Starting the app with docker.

To start the app with docker and rebuild the docker images (if there are code changes or ENV variable changes) use the following command:
docker compose up --build
(Use CTRL+C to shut down the containers)
To start the app with docker without rebuilding the images use the following command:
docker compose up
To stop the app use the following command:
docker compose down
To check if the app containers are running and on which ports use the following command:
docker ps

Environment variables explained

Note that these environment variables are referenced from the docker-compose file. The env variables in the .env files might be slightly different.

jasma-api-server

START_FIRST_TIME Controls if the PSQL database is re-created on server startup. (true / false)
STAGE Controls if the app is started in dev or production mode. (development / production)
HOSTNAME Controls the hostname of the server. NOT USED (YET?).
PORT Controls the port of the API server. (Integer)
SESSION_SECRET Controls the session secret of the cookies stored in Redis. (String)
NEXTJS_ORIGIN The IP address or domain of NextJS. Used for CORS policy. (IP address or domain)
NEXTJS_PORT Making sure the server knows what port NextJS is using. Used for CORS policy (Integer)
PG_SUPER_USER The username for logging in to postgresql as the root super user. (String)
PG_SUPER_PASSWORD The password for logging in to postgresql as the root super user. (String)
PG_ADMIN_USER The username for managing the jasma postgresql database. (String)
PG_ADMIN_PASSWORD The password for managing the jasma postgresql database. (String)
PG_HOST The hostname for connecting to postgresql. (IP address or domain)
PG_PORT The port for connecting to postgresql. (Integer)
PG_SUPER_DATABASE The name of the root / super database in postgresql. (String)
PG_ADMIN_DATABASE The name of the jasma database in postgresql. (String)
REDIS_HOST The hostname for connecting to redis. (IP address or domain)
REDIS_PORT The port for connecting to redis. (Integer)
PAYPAL_SECRET The Paypal secret of your Paypal account. Used for accepting payments. (String)
PAYPAL_CLIENT_ID_SANDBOX The client ID of your Paypal App. For testing and development. Uses fake money. (String)
PAYPAL_CLIENT_ID_PRODUCTION The client ID of your Paypal App. For production. Uses real money. (String)
STRIPE_SECRET_KEY The Stripe secret of your Stripe account. Used for accepting payments. (String)

jasma-client

BASE_URL The URL in the browser to connect to the app. NOT USED (YET?) (IP address or domain)
PORT The port of NextJS. Used to connect the user/browser to the client. NextJS Server Side Rendering. (Integer)
NEXT_PUBLIC_API_SERVER_URL The IP address or domain of the API server. Used for connecting client to backend. (IP address or domain)
NEXT_PUBLIC_API_SERVER_PORT The port the API server. Used for connecting client to backend. (Integer)
NEXT_PUBLIC_NODE_ENV Controls if the app is started in dev or production mode. (development / production)
ANALYZE Controls if the NextJS document size analyzer should be turned on. Setting this to true might crash the browser. (true / false)
SESSION_SECRET NextJS session secret. NOT USED. (String)
PAYPAL_SECRET Paypal secret of your paypal account. NOT USED. (String)
NEXT_PUBLIC_PAYPAL_CLIENT_ID_SANDBOX Client ID of your paypal app. For testing. NOT USED. (String)
NEXT_PUBLIC_PAYPAL_CLIENT_ID_PRODUCTION Client ID of your paypal app. For production. NOT USED. (String)
NEXT_TELEMETRY_DEBUG Controls wether to show debug and telemetry data in the console. (1 / 0)
NEXT_TELEMETRY_DISABLED Controls wether to send telemetry and app usage data to Vercel. (1 / 0)

API Routes

Routes marked with ! require authenthication/authorization.

Routes marked with !! require moderator/admin authenthication/authorization.

Auth

  • POST /api/auth/register
  • POST /api/auth/login
  • POST /api/auth/logout
  • POST /api/auth/checkAuth
  • POST /api/auth/checkAuthUserRole
  • ! POST /api/auth/changePassword

Users

  • ! GET /api/users/getClientUser
  • GET /api/users/getUserId/${username}
  • GET /api/users/${userID}/UserInfo
  • GET /api/users/${userid}/profilepic
  • ! PUT /api/users/uploadProfilePic
  • ! POST /api/users/addFollower
  • ! DELETE /api/users/removeFollower/${userID_two}
  • GET /api/users/${userID}/getFollowers
  • GET /api/users/${userID}/getFollowing
  • ! GET /api/users/checkIsFollowing/${userID_two}
  • !! GET /api/users/getUsersByRole
  • !! PUT /api/users/changeUserRole

Posts

  • ! POST /api/posts/createPost
  • ! DELETE /api/posts/deletePost/${postID}
  • ! PUT /api/posts/editPost
  • GET /api/posts/getUserPosts?user_id=${user_id}&limit=${limit}
  • GET /api/posts/getSinglePost/${post_id}
  • GET /api/posts/getLatestPosts?limit=${limit}
  • ! GET /api/posts/getNewsFeed
  • ! POST /api/posts/addPostBookmark
  • ! DELETE /api/posts/removePostBookmark/${post_id}
  • ! GET /api/posts/getBookmarkedPosts

Comments

  • ! POST /api/comments/createComment
  • ! DELETE /api/comments/deleteComment/${commentID}
  • ! PUT /api/comments/editComment
  • GET /api/comments/getComments?post_id=${post_id}&limit=${limit}

Search

  • GET /api/search/search?q=${keyword}&filter=${filter}

Hashtags

  • GET /api/hashtags/getTopHashtags?limit=${limit}
  • GET /api/hashtags/getHashtagCount/${hashtag}
  • ! GET /api/hashtags/getSubscribedHashtags
  • ! POST /api/hashtags/subscribeToHashtags
  • ! DELETE /api/hashtags/unsubscribeFromHashtag

Notifications

  • ! GET /api/notifications/getNotifications
  • ! PUT /api/notifications/readNotification

Reports

  • POST /api/reports/createReport
  • !! GET /api/reports/getReports
  • !! DELETE /api/reports/deleteReport/${postID}
  • !! DELETE /api/reports/ignoreReport/${postID}

Advertisements

  • ! POST /api/ads/createAd
  • ! DELETE /api/ads/deleteAd/${adID}
  • ! PUT /api/ads/editAd
  • ! GET /api/ads/getAd/${adID}
  • ! GET /api/ads/getAds

Media

  • GET /media/${mediaType}/${context}/${fileName}

External documentation of 3rd party libraries, frameworks, and tools