Telegram Mini App Template

Template for building Telegram Bots with Mini Apps in React and Go. Deployed instance available at @tg_mini_app_template_bot.

Features

• Example of creating Inline Keyboard to interact with the user. Keyboard creation can be found in main.go
• Example of adjusting UI styles to the user's current color theme using ThemeParams. CSS variable usage can be found in index.css
• Example of interaction with telegram-web-app.js to show a native alert. Script usage can be found in App.jsx
• Local environment with docker-compose, that serves traffic over HTTPS proxy and automatically applies UI changes without rebuilding the container
• Continious deliviery to Google Cloud Platform

Setup prerequisites

Telegram Bot token is required to interact with Telegram Bot API. To get one, сreate a bot using @BotFather or follow Telegram instructions.

Local environment

This repository provides an easy-to-use local development environment. Using it you can start writing your bot business logic without spending time on the environment.

Local environment includes:

• ngrok reverse proxy to server local mini-app and bot deployment over HTTPS
• nginx reverse proxy to host both API and UI on one ngrok domain and thus fit into the free plan
• React fast refresh to avoid rebuilding docker container on each change of the UI code

Local environment setup:

1. Create an account on ngrok
2. Get a ngrok auth token and save it to NGROK_AUTHTOKEN variable in .env file in the project root directory
3. Claim a free ngrok domain and save it to NGROK_DOMAIN variable in .env file in the project root directory
4. Copy Telegram Bot token and save it to TELEGRAM_BOT_TOKEN variable in .env file in the project root directory
5. Install Docker

To start or update the environment with the latest code changes, use:

docker compose up --build -d

After successful deployment, your local bot API will be available at https://ngrok-domain/api. Use this URL to set the bot webhook as described switching bot environment.

Production deployment

This repository provides a workflow to automatically deploy the code to Google Cloud Platform. The deploy job is triggered on each push to the main branch.

GCP services used for deployment:

• Cloud Run to host dockerized API and UI code
• Artifact Registry to store docker images
• Secret Manager to store sensitive data

Deployment setup:

1. Create a project in GCP
2. Copy project ID to GCP_PROJECT_ID GitHub variable
3. Pick a region for your app and save it to GCP_PROJECT_REGION GitHub variable
4. Create a service account with the following rights:
   • Service Account User (to create resources by the name of this account)
   • Cloud Run Admin (to create Cloud Run instances)
   • Artifact Registry Administrator (to manage images in the registry)
   • Secret Manager Secret Accessor (to access GCP secrets)
5. Copy the service account email and save it to GCP_SA_EMAIL GitHub variable
6. Export the service account key and save it to GCP_SA_KEY GitHub secret
7. Enable the following GCP APIs:
   • Cloud Run Admin API (to create Cloud Run instances)
   • Secret Manager API (to securely store secrets)
8. Create Artifact Registry for Docker images in GCP_PROJECT_REGION region
9. Copy Artifact Registry name and save it to GCP_ARTIFACT_REGISTRY GitHub variable
10. Create a secret with Telegram Bot token in Secret Manager
11. Copy the secret name and save it to GCP_SECRET_TG_TOKEN GitHub variable
12. Define the following GitHub variables:
    • GCP_SERVICE_UI_NAME with the desired name of UI Cloud Run instance
    • GCP_SERVICE_UI_MAX_INSTANCES with the desired maximum number of UI service instances
    • GCP_SERVICE_API_NAME with the desired name of API Cloud Run instance
    • GCP_SERVICE_API_MAX_INSTANCES with the desired maximum number of API service instances

After successful deployment, obtain the bot API URL from either deploy-api job results or from GCP Project Console and proceed to switching bot environment.

Switching bot environment

After the bot is either launched locally or deployed in GCP, Telegram needs to be configured with a proper webhook URL. To set it, use:

curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=${BOT_API_URL}/bot

Template structure

• Project root directory - contains files for local environment
  • docker-compose.yml - docker-compose file to setup local environment
  • proxy.template - nginx config template to route ngrok domain to API and UI containers
• api - contains files for the bot backend written in Go
  • Dockerfile - docker file for the API service image
  • Other files - minimal Go package layout with HTTP endpoint to handle Telegram Bot API calls
• ui - contains files for the mini app UI written in JS with React
  • dev.dockerfile - docker file for the local environment to track code changes and updated served UI bundle
  • prod.dockerfile - docker file for the production deployment to bundle UI and serve via nginx
  • nginx.template - nginx config template for production UI service image
  • Other files - React template with minimal changes for the integration with Telegram

Built with

• Docker
• Go
• React
• Vite
• gotgbot
• nginx
• ngrok

License

Distributed under the MIT License. See LICENSE for more information.

Contributing

Want a new feature added? Found a bug? Go ahead and open a new issue or feel free to submit a pull request.