Home

Getting Started

Install Yarn

Install Yarn as the package manager. All npm commands should be using yarn and not npm. You probably have the latest 3.x.x version of Yarn. Switch to Yarn 1 using yarn set version 1.x (necessary as using different Yarn pkg version will completely change the yarn.lock file).

After installing Yarn

1. Run yarn once at the backend directory.
2. Run yarn once at the frontend directory.

yarn

Set up your Telegram Bot

You need your own Telegram Bot for the app login to work.

Create a bot with BotFather

1. Send /newbot to create a new Telegram bot.
2. When asked, enter a name for the bot.
3. Give the Telegram bot a unique username.
4. Copy and save the Telegram bot's access token for later steps

Set up the .env file

Backend

Make a copy of backend/.env.example to backend/.env.

cp backend/.env.example backend/.env

• JWT Tokens

  • ACCESS_TOKEN_SECRET and REFRESH_TOKEN_SECRET: To sign the respective JWT tokens. Any random string will do for each secret.
  • ACCESS_TOKEN_EXPIRY and REFRESH_TOKEN_EXPIRY: The amount of time the respective JWT tokens are valid for from the time of generation. E.g. 10s, 30m, 7d

• Telegram OAuth

  • OAUTH_TELEGRAM_BOT_TOKEN: Token of the bot you registered with BotFather.

• Telegram Jio Notification

  • TELEGRAM_MAIN_CHAT_GROUP_ID: Telegram chat_id of the chat that the above OAuth bot will send a notification to when a 'jio' is created. You can refer to this StackOverflow post on how to obtain your own chat_id or a group's chat_id.

• Telegram Alerts (interim way of sending logs, metric updates and alerts to the team - optional to configure if not needed)

  • TELEGRAM_ALERTS_BOT_TOKEN: The bot token for the alerts bot. (You can reuse the one in OAUTH_TELEGRAM_BOT_TOKEN above in local dev if don't want to create a separate bot)
  • TELEGRAM_ALERTS_CHAT_ID: The Telegram chat_id of the chat to send these alerts to.

• Postgres Database Connection Details

  • DATABASE_HOST: Your local Postgres database URL. (You can try leaving this empty, to see if the library defaults work)
  • DATABASE_PORT: The port to connect to. Should be 5432 if the default Postgres port is used.
  • DATABASE_USER: Your username used to login to the Postgres database.
  • DATABASE_PASSWORD: Your corresponding password used to login to the Postgres database.
  • DATABASE_NAME: The database name to connect to. E.g. climbjios-dev

• CloudFlare Stream (refer to CloudFlare's Documentation)

  • CLOUDFLARE_ACCOUNT_ID: Your CloudFlare account ID.
  • CLOUDFLARE_STREAM_API_TOKEN: Your CloudFlare Stream API token.
  • (please ping Ri Zhao or En Rong if you require access to the dev CloudFlare credentials)

• AWS S3 (refer to AWS's Documentation)

  • AWS_ACCESS_KEY_ID: The access key ID (with S3 read write permissions).
  • AWS_SECRET_ACCESS_KEY: The corresponding access key secret.
  • AWS_S3_BUCKET_NAME: The S3 bucket name that you have pre-created on AWS console.
  • AWS_REGION: The AWS region that the S3 bucket is hosted in. (We use ap-southeast-1 which is located in Singapore)
  • (please ping En Rong if you require access to the dev S3 bucket)

• CORS

  • CORS_ORIGIN: The CORS origin for the backend server. You can use http://localhost:3000 for local dev.

• Backend Ports

  • PORT: The port that the main backend runs on. Defaults to 4000 if unspecified.
  • CRONJOB_PORT: The port that the cronjob service runs on. Defaults to 4001 if unspecified.

• Google OAuth (can be ignored for now since we deprecated Google Login in favor of users onboarding with their verified Telegram username)

  • OAUTH_GOOGLE_ID: OAuth2 Client ID generated from Google Developer Console.
  • OAUTH_GOOGLE_SECRET: OAuth2 Secret generated from Google Developer Console.
  • OAUTH_GOOGLE_REDIRECT_URL: The URL that Google will redirect to upon successful login on Google's side. Should be http://localhost:4000/v1/auth/google/redirect in local dev.
  • NOTE: Put in a placeholder value for all these for backend to run e.g. (xyz)

Frontend

Make a copy of frontend/.env.example to frontend/.env.

cp frontend/.env.example frontend/.env

• VITE_HOST_API_KEY: Host key of backend. Should be http://localhost:4000 in local dev.
• VITE_DEBUG: Will show debug messages only if true. Should be set true in local dev.
• VITE_TELEGRAM_OAUTH_BOT_USERNAME: Username of the bot you registered with BotFather. E.g. climbjios_rz_bot.

Run the app locally

After setting up the environment variables and installing the requisite dependencies:

1. Start the Postgres server.
   • If you don't have a local Postgres instance & too lazy to download Postgres, you can try using supabase.io. Just find their connection strings and put it in the backend env variables.
2. In backend directory
   1. Run yarn migrate to run all database migrations (this command creates the database if it does not yet exist)
   2. Run yarn seed to add seed data
   3. Run yarn start:dev to start the main server locally
   4. (Optional) Run yarn start:dev:cronjob to start the cronjob microservice locally
3. In frontend directory, run yarn start
4. Setup ngrok tunneling
   1. Install ngrok and configure your ngrok auth token (instructions here)
   2. Run ngrok http 3000 to start the tunnel (you will be exposing your local machine port to the internet at the given URL)
   3. On Telegram's @BotFather, run the /setdomain command. Select bot your created above, then paste the URL received when running step 2.
   4. Access your local machine deployment via the URL received in step 2. The Telegram login widget should appear as a button.

Tech Stack

Area	Choice	What is it
Language	TypeScript	Statically typed JavaScript
View	React	Most popular UI library
Backend Framework	Nest.js	A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
Data Fetching	ahooks useRequest	Powerful hooks library for data fetching
ORM	Objection.js	An SQL-friendly ORM (Object Relation Mapping) for Node.js
SQL Query Builder	Knex.js	Build SQL queries for App logic and migrations
Database	PostgreSQL	Popular open source relational database

Development

Source Control

• main is release branch and should remain stable at all times.
• Create feature branches for your in-progress features and using the format <username>/my-feature (doesn't have to be your GitHub username, just use something identifiable and be consistent about it).
• We use Conventional Commits specification for commit messages:
  • E.g. feat: my commit message.
• Delete your branch after merging into main.

References

• Climbjios Kanban board

Credits: This guidebook is heavily inspired by TechInterviewHandbook's wiki.