Installation

Caution

Don't install the userbot on recent registered accounts

Environment Variables

Variable	Importance	Description	Source / Link	Default value
API_ID	Required	Your Telegram API ID.	my.telegram.org	2040
API_HASH	Required	Your Telegram API Hash.	my.telegram.org	b18441a1ff607e10a989891a5462e627
STRINGSESSION	Required*	Pyrogram session string. Necessary for Docker/Cloud.	Use Script OR	—
DATABASE_TYPE	Required	Set to sqlite3 or mongodb.	—	—
DATABASE_NAME	Required	File name for sqlite3 (e.g., db.sqlite3) or Mongo DB name.	—	—
DATABASE_URL	Optional	Your MongoDB connection URL (only if using Mongo).	MongoDB Atlas	—
PM_LIMIT	Optional	Number of warnings before Anti-PM kicks in.	—	4
MODULES_REPO_BRANCH	Optional	Default custom modules repo branch	-	main
SECOND_SESSION	Optional	Session string for the Music Bot feature.	—	—
GEMINI_KEY	Plugin	API Key for Gemini AI features.	Google AI Studio	—
APIFLASH_KEY	Plugin	API Key for taking web screenshots.	ApiFlash	—
RMBG_KEY	Plugin	API Key for the removebg background remover.	remove.bg	—
VT_KEY	Plugin	API Key for the VirusTotal file scanner.	VirusTotal	—
COHERE_KEY	Plugin	API Key for Cohere AI features.	Cohere Dashboard	—

---

📝 Quick Notes

• Database: If you are using sqlite3, you can leave DATABASE_URL blank.
• Sessions: If STRINGSESSION is not provided, the bot will attempt to generate one at startup via the terminal, but this is not recommended for headless environments like Heroku or Docker.

☁️ Cloud Host

Koyeb	Heroku	Render

• YT Video [How to deploy on Koyeb]: https://youtu.be/2m_yB7EllYc
• YT Video by a user [How to deploy on Koyeb]: https://youtu.be/AmlFBZ26tY4?si=3buw5OCJ2wEz3tVJ

For most people above instrunctions are enough to deploy Moon-Userbot. Though if you still haven't been able to understand or deploy Moon-Userbot or maybe you're reading type person (like me), then continue reading.

Koyeb (Free)

• Go to Koyeb and sign up. Remember to use your real Gmail or your Github for it.
• Now you need to create a string session, watch this video to know how to create a string session.
• Now click on this link
• You'll be redirected to Koyeb's Deploy page. It'll look like this:

PC	Mobile

• Now time to configue our environment variable:
  1. Click on Environment Variables:
  2. Choose "Raw Editor":
  3. Now copy and paste this to the editor.
  4. Edit the variables with your own values. ⚠️ Do not remove any variable. ⚠️ Just leave it blank if you don't want to use an optional variable.
  • After that we need to also add one more variable for PORT with 8080 as value. Verify that you've 15 variables configured:
  5. Now comes builder part, for that we've two options: 1. Dockerfile 2. Buildpacks.
  • Dockerfile:
    • Click on Dockerfile:
    • and override Dockerfile location:
  • Buildpacks:
    • Click on Buildpacksand override the run command as below:
  6. Choose region as Washingtion DC:
  7. Change Exposed Port to 8080:
  8. Now click on Deploy and wait for the build to finish. And 🥳 you're done.

Render

If you're a premium user of Render, you can easily deploy Moon-Userbot on Render by clicking on the "Deploy to Render" icon above. The Moon repository contains a render.yaml file that is compatible with Render and has all the necessary settings. All you need to do is add a file in the environment section with the name .env and configure your variables in it.

Here are the detailed steps:

1. You'll be redirected to Render's Deploy page.
2. Now, you need to add your environment variables. Click on the "New Environment Variable" button.
3. Copy and paste the contents of this file into the editor. This file contains all the necessary variables.
4. Edit the variables with your own values. ⚠️ Do not remove any variable. ⚠️ Just leave it blank if you don't want to use an optional variable.
5. After adding all the variables, click on "Add" to save them.
6. Now, Render will automatically build and deploy your Moon-Userbot.
7. Once the deployment is complete, you're done.

Heroku

Heroku is no longer free. But you can still deploy Moon-Userbot on Heroku if you're paid user of it. Since we don't have any paid Heroku account, we can't provide you with a detailed guide. Feel free to contribute if you have a paid Heroku account and can help us with the guide.

🐳 Docker

You can either use docker run or docker compose.

Prerequisites

• Docker
• Docker Compose (version 1.x for docker-compose.yml, version 2.x for compose.yml)
• Put your environment vars in .env file check .env.dist for example format

👷‍♂️docker run:

We also push images to Docker Hub, so you can use the following commands to start and update the service:

• Start:
  1. If you want to use normal image:

  docker run --env-file ./.env -d qbtaumai/moonuserbot:latest

  2. If you want to use image with web (only recommended for heroku/koyeb/render etc.):

  docker run --env-file ./.env -d qbtaumai/moonubcloud:latest-cloud

• Updating:

  docker stop $(docker ps -q)

  then re-run the start command

🍟 docker compose [recommended]:

Docker Compose V1 (docker-compose.yml):

If you're using Docker Compose version 1.x, use the following commands to start and update the service:

• Start:

  docker-compose -f docker-compose.yml up -d

• Updating & running:

  docker-compose -f docker-compose.yml down && docker-compose -f docker-compose.yml pull && docker-compose -f docker-compose.yml up -d

Docker Compose V2 (compose.yml):

If you're using Docker Compose version 2.x, use the following commands to start and update the service:

• Start:

  docker compose -f compose.yml up -d

• Updating & running:

  docker compose -f compose.yml down && docker compose -f compose.yml pull && docker compose -f compose.yml up -d

Important

Make Sure you add appropriate env vars

🖥️ Local Host

🐧 Linux (WSL compatible)

Install Git

There are instructions for installing on several different Unix distributions on the Git website, at https://git-scm.com/download/linux

Clone the repo

git clone https://github.com/The-MoonTg-project/Moon-Userbot.git

Installation

cd Moon-Userbot 
chmod +x install.sh
./install.sh

Installer tested on:

• Arch
• Debian
• Ubuntu
• WSL (APT based distros)

Feel free to test on other distros and let us know!

Termux (Android)

1. Download and install termux from f-droid (click (https://f-droid.org/en/packages/com.termux/))
2. Copy this command and paste in termux:

curl -L# https://raw.githubusercontent.com/The-MoonTg-project/Moon-Userbot/master/termux-install.sh -o t-moonub.sh && bash t-moonub.sh

3. Termux may ask permission to work in the background, you should allow it

4. Wait for the "Enter API_ID and API_HASH" message in the terminal. If you aren't a developer and do not understand what it means, just press Enter. Afterwards proceed with the follow up vars it asks for.

5. When it'll ask about database type ("Choose database type"), enter 2 and press Enter

6. Now you need to authorize your Telegram account. Just follow instructions that you'll see - literally enter your Telegram's phone number and press enter.

7. When it'll ask "Is correct? (y/N)", enter 'y'

8. You'll receive a message from Telegram with a confirmation code. You should copy it and enter it to the terminal when it asks "Enter confirmation code".

   • If your account has a 2fa password, you'll be asked to enter it

9. Congrats! Userbot installed successfully. To start userbot, enter this command in shell: cd Moon-Userbot/ && python main.py

10. Switch to Telegram and enjoy 🎉

Linux

1. Copy this command and paste it to Terminal:

sudo apt update && sudo apt upgrade -y && sudo apt install git && git clone https://github.com/The-MoonTg-project/Moon-Userbot.git && cd Moon-Userbot/ && sudo bash install.sh

2. Wait for the "Enter API_ID and API_HASH" message in the terminal. If you aren't a developer and do not understand what it means, just press Enter.

3. When it'll ask about database type ("Choose database type"), enter sqlite option and press Enter

   • Those who know How-to's if want mongodb then they can use 1 option too

4. Now you need to authorize your Telegram account. Just follow instructions that you'll see - literally enter your Telegram's phone number and press enter.

5. When it asks Is correct? (y/N) > enter 'y'

6. You'll receive a message from Telegram with a confirmation code. You should copy it and enter it to the terminal when it asks "Enter confirmation code".

   • If your account has a 2fa password, you'll be asked to enter it

7. Congrats! Userbot installed successfully. To start userbot, enter this command in shell:

cd Moon-Userbot / && python main.py

8. Switch to Telegram and enjoy :)

Windows (WSL)

1. You need WSL feature enabled and install any WSL distro of your choice

2. Follow the steps mentioned in Linux section.