/notes-app

main was modified after the contest results were announced. Contest source: https://github.com/roj1512/notes-app/tree/513d3b06c3c9c9b270e51ff221f389b1ea36882d

Primary LanguageTypeScriptBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Notes

A simple Telegram mini app that lets you take notes.

Features

  • Text formatting capabilities.
  • Supports Telegram entities: usernames, hashtags, and others.
  • Ability to share the notes as Telegram messages.

Architecture

The front end is powered by React and Lexical. The back end persists data in a PostgreSQL database, and can host a Bot API webhook at the same time.

Development

Prerequisites

To work on this project, you first need to:

  • Install Git, Deno, Node.js, and optionally pnpm if you don’t already have them. Docker will also be needed if you don’t already have a PostgreSQL server running and you want to follow the guide here to setup one.

  • Have a bot with a Web App configured properly. We’ll guide you through this, so you don’t need to worry it for now. All you need is a Telegram account.

Setting up PostgreSQL

If you don’t already have access to a running PostgreSQL server, you can start one using Docker this way:

docker run -d --name notes-app_postgres -p 127.0.0.1:5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_DB=main -d postgres

This will pull a recent version of the postgres image and start an instance of it under the name notes-app_postgres and start listening for connections on localhost, port 5432. The URI for connecting to it would be postgresql://postgres@127.0.0.1/main.

Cloning and configuring

  1. Clone the repository.
git clone --depth 1 https://github.com/roj1512/notes-app.git
  1. cd into the clone and create a .env file.
cd notes-app/
touch .env
  1. Add the required variables to the .env file you just created in the following format.
BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ
POSTGRESQL_URI=postgres://postgres@127.0.0.1/main
POLLING=1 # Whether to use polling

The BOT_TOKEN is the bot token @BotFather gave you. The POSTGRESQL_URI is your PostgreSQL connection URI, and it is postgres://postgres@127.0.0.1/main if you have set up your PostgreSQL server by following the above guide.

Telegram-side configuration

Method 1: Test server

  1. Open the Telegram app, and switch to test servers.

    • Telegram Desktop: Open the menu using the button in the top left corner, right click Add Account while holding Alt+Shift, and choose Test Server.
    • Telegram macOS: Sequentially click Settings in the tab bar until the debug menu opens, and click Add Account while holding Cmd.
    • Telegram iOS: Sequentially tap Settings in the tab bar until the debug menu opens, open Accounts > Login to another account > Test.

  2. Enter your phone number to sign up or log in.

  3. Send /newbot to @BotFather, and answer the questions to create a bot.

  4. Use the /newapp command to create a Web App. Choose the bot you’ve just created, follow the instructions, and when prompted for the URL, send the following URL.

http://localhost:3000
  1. Edit your .env to include the following variable.
TEST=1
  1. Since the app has features that leverage inline mode, you will also have to enable inline mode using the /setinline command.

Method 2: Production server

  1. Use a traffic tunneling service like Pagekite, Cloudflare Tunnel or ngrok to route a public https endpoint to your localhost:3000.

  2. Send /newbot to @BotFather, and answer the questions to create a bot.

  3. Use the /newapp command to create a Web App. Choose the bot you’ve just created, follow the instructions, and when prompted for the URL, send it the URL provided by your tunnel service.

  4. Since the app has features that leverage inline mode, you will also have to enable inline mode. To do that, use /setinline.

Starting the development server

  1. To watch the front end source and rebuild it on each change, open a terminal, cd into the app/ directory, install the dependencies if you haven’t already, and run the dev script.
cd app/ # Run this from the notes-app/
pnpm install # You can use any other package manager, but pnpm is recommended
pnpm dev
  1. To start the back end, open another terminal, cd into the app/, and run the dev task.
cd api/ # Run this from notes-app/
deno task dev

Deployment with Docker

A publicly available image of this project can be found on Docker Hub.

  1. Copy docker-compose.yml to the machine where you plan to deploy the project on.
  2. Create .env file next to the docker-compose.yml, and specify the following variables.
# Only BOT_TOKEN is required.
BOT_TOKEN=1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ

# The public https URL where the app will be available at. Recommended but not necessary.
WEB_APP_URL=https://your-domain.com

# You can also specify where the server will accept connections from. Don't forget to edit docker-compose.yml if you set a different port.
HOST=127.0.0.1
PORT=3000
  1. Create a volume named notes-app.
docker volume create notes-app
  1. Start the containers.
docker compose up -d

  1. Setup a reverse proxy for localhost:3000 using a web server like NGINX or Caddy, connect it to your domain, and setup TLS.

  2. Change the Web App URL in @BotFather to where your deployment is accessible from.

License

This project is licensed under the BSD-3-Clause license.