Pizzario Bot – Complete Setup & Operations Guide

Minimal Docker-ready architecture, first-run wizard, hosting, payments, maps, domains, themes, and admin usage

Overview

This guide explains how to run and operate the Pizzario Telegram bot in a Docker container with minimal startup configuration, and how to configure all optional features directly within Telegram. It covers keys, hosting providers, payments, maps, domains, themes, language, support, notifications, and the admin dashboard.

Only two environment variables are required to start: TELEGRAM_BOT_TOKEN and GEMINI_API_KEY. Everything else is configured inside the bot and stored in SQLite under /app/data.

Table of Contents

📋 Getting Started

Requirements

Create Telegram Bot Token

  1. Open Telegram and search for BotFather.
  2. Send /newbot and follow prompts (choose a name and a unique username ending with bot).
  3. BotFather returns a token like 123456:ABC-DEF.... Keep it secret.

Use this token as TELEGRAM_BOT_TOKEN when starting the container.

Create Gemini API Key

  1. Go to Google AI Studio and sign in.
  2. Create an API key under the Keys section.
  3. Copy the key and store it securely.

Use this as GEMINI_API_KEY. The bot's AI assistant is immediately available after startup.

Build & Run Docker (Windows & Linux)

This guide assumes you are a beginner and want to run the bot on a Virtual Private Server (VPS) or your local computer.

Choose your Operating System:

🐧 Linux VPS Setup (Ubuntu/Debian)

Step 1: Get the Bot Files

You should have a zip file of the bot or access to the source code folder (e.g., pizzario-fresh).

Step 2: Upload Files to Your Server

If you are running this on a VPS (like DigitalOcean, Vultr, Hetzner), you need to get the files onto the server.

Option A: Using FileZilla (Easiest for Beginners)
  1. Download and install FileZilla Client (free).
  2. Open FileZilla.
  3. Host: Enter your server IP (e.g., sftp://164.92.123.45). Note the sftp:// prefix.
  4. Username: Usually root.
  5. Password: Your server password.
  6. Port: 22.
  7. Click Quickconnect.
  8. On the right side (Remote site), navigate to /root. Right-click and "Create directory" named pizzario-bot. Enter that folder.
  9. On the left side (Local site), find your extracted bot folder.
  10. Select all files (Ctrl+A) and drag them from left to right to upload them.
Option B: Using GitHub (For Advanced Users)

If your code is on a private GitHub repo:

# Install git
sudo apt update && sudo apt install git -y

# Clone repo (you will be asked for username/token)
git clone https://github.com/yourusername/pizzario-bot.git
cd pizzario-bot

Step 3: Install Docker

You need Docker to run the bot. Run these commands on your server (Ubuntu/Debian):

# 1. Update system
sudo apt update
sudo apt upgrade -y

# 2. Install Docker (official script)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 3. Verify installation
docker --version
docker compose version

Step 4: Configure the Bot

  1. Find the file named env.example.
  2. Rename it to .env (or copy it). 
    cp env.example .env
  3. Edit the file to add your keys. 
    nano .env
  4. Fill in your TELEGRAM_BOT_TOKEN and GEMINI_API_KEY. You can get these from the "Requirements" section above.
  5. Press Ctrl+X, then Y, then Enter to save and exit.

Step 5: Run the Bot

Now you are ready to start the bot!

docker compose up -d --build

This command builds the bot and starts it in the background.

Checking Logs: docker compose logs -f

Stopping: docker compose down

🪟 Windows VPS Setup

If you rented a Windows Server VPS, you will use Remote Desktop Connection (RDP) to control it just like your own computer.

Step 1: Connect to Your VPS

  1. On your local computer, search for "Remote Desktop Connection" app.
  2. Computer: Enter your VPS IP address (e.g., 164.92.123.45).
  3. Username: Usually Administrator.
  4. Click Connect. Enter your VPS password when asked.
  5. You will see a Windows desktop appear.

Step 2: Install Docker Desktop

  1. Inside the VPS, open the web browser (Edge).
  2. Go to docker.com and download Docker Desktop for Windows.
  3. Run the installer. Ensure "Use WSL 2 instead of Hyper-V" is checked (recommended).
  4. After installation, you may need to restart the VPS. You will be disconnected; just reconnect after a minute.
  5. Open Docker Desktop and accept the terms. Wait for the engine to start (green icon).

Step 3: Upload Bot Files

The easiest way is simply Copy & Paste:

  1. On your local computer, find your pizzario-fresh folder.
  2. Right-click the folder and select Copy (or Ctrl+C).
  3. Switch to your VPS Remote Desktop window.
  4. Right-click on the Desktop and select Paste (or Ctrl+V).
  5. Wait for the files to transfer.

Step 4: Configure the Bot

  1. Open the folder on your VPS Desktop.
  2. Find env.example and rename it to .env.
  3. Open .env with Notepad.
  4. Paste your TELEGRAM_BOT_TOKEN and GEMINI_API_KEY.
  5. Save and close the file.

Step 5: Run the Bot

  1. Inside the bot folder, right-click empty space and select "Open in Terminal" (or Open PowerShell here).
  2. Type the following command and press Enter: 
    docker compose up -d --build
  3. Docker will download dependencies and start your bot.
Success! After the container is running, open Telegram, search for your bot by its username, and send /admin to start the First-Run Wizard.

🔧 Admin Documentation

Everything you need to know to configure and manage the Pizzario Bot as an administrator.

First-Run Wizard & Admin Lock

After startup, send /admin from your Telegram account. The first caller is permanently stored as the primary admin.

Admin Dashboard Usage

Open /admin. Controls include:

Cloudflare Pages & R2 Tokens

To enable site deployment and image storage, you need to connect your Cloudflare account. This requires your Account ID and a custom API Token.

1. Get Your Account ID

  1. Log in to the Cloudflare Dashboard.
  2. Go to Workers & Pages on the left sidebar.
  3. Look for "Account ID" on the right side of the Overview page.
  4. Copy this ID (e.g., a1b2c3d4e5f6...).

2. Create API Token

You need a token with permissions for both Cloudflare Pages (hosting) and R2 (storage).

  1. Go to My Profile → API Tokens.
  2. Click Create Token.
  3. Scroll down and click Get started next to "Create Custom Token".
  4. Name the token (e.g., "Pizzario Bot").
  5. Permissions: Add the following 3 permissions:
    • Account | Cloudflare Pages | Edit
    • Account | Workers R2 Storage | Edit
    • Account | Workers R2 Storage | Read
  6. Account Resources: Select "Include" → "All accounts" (or your specific account).
  7. Click Continue to summary → Create Token.
  8. Copy the token immediately (you won't see it again).

3. Connect Inside the Bot

  1. Open /admin → "Setup Hosting".
  2. Choose "Cloudflare Pages" or "Cloudflare R2 Storage".
  3. Paste the combined string: ACCOUNT_ID:API_TOKEN.

4. Cloudflare Free Plan Limits & Upgrades

Cloudflare offers a very generous free tier that is sufficient for most small to medium pizza bot operations. However, you should be aware of the limits:

Cloudflare Pages (Hosting):

  • Free Plan: 500 builds per month, 100 custom domains, unlimited bandwidth.
  • When to Upgrade: If you exceed 500 builds/month or need advanced features like web analytics.
  • Cost: Pro plan starts at $20/month.

Cloudflare R2 (Image Storage):

  • Free Plan: 10 GB storage, 1 million uploads (Class A), 10 million reads (Class B) per month.
  • When to Upgrade: When you exceed these limits. R2 is "Pay-as-you-go".
  • Cost: $0.015/GB storage, $4.50 per million uploads, $0.36 per million reads.
Recommendation: Most users will never need to pay for Cloudflare. If your bot grows very large (thousands of active sites), the R2 "Pay-as-you-go" model is extremely cost-effective compared to other providers.

Maps: Google vs OpenStreetMap

Recommendation

OpenStreetMap (OSM) is recommended for most setups: free, no key needed, and now fully compatible with onboarding (GPS reverse geocoding and embedding). Google Maps is useful if you rely on Places Autocomplete and specific embed features.

Setup OSM

  1. Open /admin → "Map Provider Setup".
  2. Select "OpenStreetMap (free)".

Setup Google Maps

  1. Create a Google Cloud project and enable:
    • Maps Embed API
    • Places API
    • Geocoding API
  2. Create an API key; restrict it to your allowed environments.
  3. Open /admin → "Map Provider Setup" → "Use Google Maps", then paste the API key when prompted.

Setup PayPal

  1. Create a PayPal REST app and obtain Client ID and Client Secret.
  2. Open /admin → "Payment Setup" → "PayPal".
  3. Enter Client ID, then Client Secret, then choose Mode (sandbox or live).
  4. Paste the Webhook Base URL (see detailed guide below).

The bot exposes POST /paypal/webhook and GET /health on the configured port.

Setup Gumroad

  1. Open /admin → "Payment Setup" → "Gumroad".
  2. Provide Product URL, Seller ID, and Billing Period (days).
  3. Use "Connect Gumroad" to validate.

Setup Telegram Stars

  1. Open /admin → "Payment Setup" → "Telegram Stars".
  2. Set Stars Price and Billing Period.
  3. Enable or disable as needed.
Telegram takes a fee when withdrawing Stars. Consider setting a price that accounts for this.

Webhook Base URL (Detailed Guide for Beginners)

The Webhook Base URL is one of the most important settings for accepting payments. Here's everything you need to know, explained step-by-step for non-technical users.

What is a Webhook URL?

Think of a webhook like a doorbell. When someone pays for your service through PayPal, PayPal "rings the doorbell" of your bot to tell it "Hey, someone just paid!" The Webhook URL is the address where PayPal knows to ring that doorbell.

Why Do You Need It?

What Does a Webhook URL Look Like?

Format: https://your-domain.com

Examples:

  • https://bot.mypizzashop.com - Using your own domain
  • https://pizzario.myserver.io - Using a subdomain
  • https://mysite.ngrok.io - Using ngrok for testing

Important: Do NOT include a trailing slash or any path. The bot will add /paypal/webhook automatically.

Choose Your Setup Method

Pick the option that best matches your situation:

🌐 Option 1: You Have Your Own Domain (Recommended for Production)

Best for: Running a real business with real payments

Step 1: Buy a Domain Name

A domain is like your address on the internet (example: mypizzabot.com).

Where to buy:

What to buy: Any .com domain you like. Example: mypizzabot.com or pizzarioserver.com

Step 2: Find Your Server's IP Address

Your server (the computer running your bot) has a unique number called an IP address. You need this to connect your domain to your server.

How to find it:

  • If using a VPS (like DigitalOcean, Vultr, Linode): Look in your dashboard, it's usually displayed prominently
  • If running at home: Go to whatismyip.com to see your public IP

Example IP: 164.92.123.45 (yours will be different)

Step 3: Connect Your Domain to Your Server (DNS Settings)

This tells the internet "when someone visits my domain, send them to my server."

Step-by-step for Namecheap (similar for others):

  1. Log into Namecheap and go to "Domain List"
  2. Click "Manage" next to your domain
  3. Click "Advanced DNS" tab
  4. Click "Add New Record" button
  5. Fill in:
    • Type: Select "A Record"
    • Host: Type bot (this creates bot.yourdomain.com)
    • Value: Paste your server's IP address (like 164.92.123.45)
    • TTL: Leave as "Automatic"
  6. Click the green checkmark to save

Result: Now bot.yourdomain.com points to your server!

Wait time: DNS changes can take 5 minutes to 24 hours to work worldwide. Usually it's about 15-30 minutes.

Step 4: Set Up HTTPS (Security Certificate)

PayPal requires your connection to be secure (HTTPS with the padlock icon). The easiest free way is using Cloudflare:

Using Cloudflare (Recommended - Free & Easy):

  1. Go to cloudflare.com and create a free account
  2. Click "Add a Site" and enter your domain (like yourdomain.com)
  3. Select the FREE plan
  4. Cloudflare will show you new nameservers (like anna.ns.cloudflare.com)
  5. Go back to Namecheap → Domain → Nameservers → Select "Custom DNS"
  6. Paste the two Cloudflare nameservers
  7. Wait 1-24 hours for it to activate
  8. In Cloudflare, go to SSL/TLS → Set mode to "Flexible" or "Full"

Result: Your domain now has HTTPS automatically! The padlock icon will appear.

Step 5: Open the Port on Your Server

Your server has a "firewall" that blocks unwanted traffic. You need to allow traffic on port 3000 (where your bot listens).

For Windows Server:

  1. Open "Windows Defender Firewall with Advanced Security"
  2. Click "Inbound Rules" on the left
  3. Click "New Rule..." on the right
  4. Select "Port" → Click Next
  5. Select "TCP" and enter 3000 → Click Next
  6. Select "Allow the connection" → Click Next
  7. Check all boxes (Domain, Private, Public) → Click Next
  8. Name it "Pizzario Bot" → Click Finish

For Linux (Ubuntu/Debian):

sudo ufw allow 3000
Step 6: Enter Your URL in the Bot
  1. Open Telegram and send /admin to your bot
  2. Click "💳 Setup Payment"
  3. Click "PayPal"
  4. When asked for Webhook URL, enter: https://bot.yourdomain.com

Replace yourdomain.com with your actual domain!

🧪 Option 2: Using ngrok for Testing (Free, No Domain Needed)

Best for: Testing payments before going live. NOT for real business use.

What is ngrok? It's a free tool that creates a temporary public URL for your local computer. Think of it as a "temporary doorbell" for testing.

Step 1: Download and Install ngrok
  1. Go to ngrok.com
  2. Click "Sign up" and create a free account
  3. After signing in, click "Download" for your operating system
  4. Extract the downloaded file somewhere you can find it (like your Desktop)
Step 2: Connect ngrok to Your Account
  1. On the ngrok website, go to "Your Authtoken" in the dashboard
  2. Copy the long code that looks like: 2abc123def456...
  3. Open Command Prompt (Windows) or Terminal (Mac/Linux)
  4. Navigate to where you saved ngrok: cd Desktop
  5. Run: ngrok config add-authtoken YOUR_TOKEN_HERE

Replace YOUR_TOKEN_HERE with the code you copied.

Step 3: Start ngrok
  1. Make sure your Pizzario bot is running first
  2. In Command Prompt/Terminal, run: ngrok http 3000
  3. You'll see something like this: 
    Session Status                online
Forwarding                    https://abc123xyz.ngrok.io -> http://localhost:3000
  4. Copy the https:// URL (the one ending in .ngrok.io)
Step 4: Enter the URL in Your Bot
  1. Open Telegram and send /admin to your bot
  2. Click "💳 Setup Payment" → "PayPal"
  3. When asked for Webhook URL, paste your ngrok URL: https://abc123xyz.ngrok.io
⚠️ Important Limitations:
  • The URL changes every time you restart ngrok
  • Free ngrok has limited connections
  • If you close the command window, ngrok stops
  • This is ONLY for testing - use Option 1 for real payments

☁️ Option 3: Using a Cloud Hosting Platform (Easiest for Beginners)

Best for: People who don't want to manage their own server

What are these? Cloud platforms run your bot for you. They give you a permanent URL automatically - no domain purchase or setup needed!

Popular platforms and their URLs:

Platform Your URL Format Example
Railway https://YOUR-PROJECT.up.railway.app https://pizzario-bot.up.railway.app
Render https://YOUR-SERVICE.onrender.com https://pizzario-bot.onrender.com
Fly.io https://YOUR-APP.fly.dev https://pizzario-bot.fly.dev
Heroku https://YOUR-APP.herokuapp.com https://pizzario-bot.herokuapp.com

How to use: After deploying your bot to any of these platforms, just find your app's URL in the dashboard and paste it into the bot's Payment Setup!

How to Test If Your Webhook URL is Working

Easy Test (Do This First!):

  1. Open any web browser (Chrome, Firefox, Edge, Safari)
  2. In the address bar, type your webhook URL followed by /health
    Example: https://bot.yourdomain.com/health
  3. Press Enter

What you should see:

{"status":"ok","service":"pizzario-payment-gateway","timestamp":"2024-01-15T10:30:00.000Z"}

✅ If you see this message: Congratulations! Your webhook URL is working correctly.

❌ If you see an error or blank page: Something is wrong. Check the troubleshooting section below.

Troubleshooting: Common Problems and How to Fix Them

What You See What It Means How to Fix It
"This site can't be reached" or "Connection refused" The browser can't find or connect to your server
  1. Make sure your bot is actually running
  2. Check that port 3000 is open in your firewall
  3. Verify your domain's DNS is pointing to the right IP
"Your connection is not private" or SSL error HTTPS is not set up correctly
  1. Make sure you're using Cloudflare (or another SSL provider)
  2. Wait a few hours for SSL certificate to activate
  3. Check that Cloudflare SSL mode is set to "Flexible" or "Full"
"DNS_PROBE_FINISHED_NXDOMAIN" Your domain name doesn't exist or DNS isn't set up
  1. Double-check you typed the domain correctly
  2. Verify the A record is set up at your registrar
  3. Wait up to 24 hours for DNS to propagate
Payments go through but users don't get upgraded PayPal can't reach your webhook
  1. Test the /health endpoint first
  2. Make sure you entered the URL without a trailing slash
  3. Check PayPal Developer dashboard for webhook delivery errors
💡 Still stuck? Use the /ai command in your bot to ask for help! The AI assistant knows about this documentation and can guide you through the setup.

Notifications Setup

The Notifications feature allows you to stay informed about important events happening in your bot. As an admin, you can receive real-time alerts directly in Telegram.

How to Access Notifications Settings

  1. Open /admin in Telegram
  2. Click on "🔔 Notifications"
  3. Configure your notification preferences

Available Notification Types

Notification Description When It Triggers
New Site Created Alert when a user creates a new pizza website After successful site deployment
New Support Ticket Alert when a user submits a support request When user uses /support command
Payment Received Alert when a premium payment is confirmed After PayPal/Stars payment completes
Domain Request Alert when a user requests a custom domain When user submits domain for approval
Customization Updates Alert when a user uploads logo or images After image upload completes

How to Enable/Disable Notifications

  1. Navigate to /admin → "Notifications"
  2. Toggle each notification type on or off
  3. Settings are saved automatically

Notification Format

Notifications are sent as Telegram messages with relevant details:

Example - New Support Ticket:

🆘 New Support Ticket #42

👤 User: @john_pizza (12345678)
📋 Issue: Website Customization
📝 Description:
I want to change my menu layout...

Best Practices

📢 Bulk Messages

Send broadcast messages to all your bot users (everyone who has started the bot). This is great for announcements, promotions, or updates.

How to Send

  1. Open /admin → "📢 Bulk Messages".
  2. Click "✉️ Create New Message".
  3. Step 1: Send the text content for your message. You can use emojis!
  4. Step 2: Optionally attach an image. Send a photo or type "no" to skip.
  5. Step 3: Choose when to send:
    • 🚀 Send Now: Starts sending immediately (within 1 minute).
    • ⏰ In 1 Hour: Schedules for later.
    • 📅 In 24 Hours / 1 Week: Good for planned promotions.

Managing Messages

Note: Messages are sent in batches to avoid hitting Telegram limits. Large user bases may take a few minutes to complete.

Premium Plan Configuration

  1. Open /admin → "Edit Premium Plan".
  2. Edit Plan Name, Price, Billing Period.
  3. Toggle features (Language, Offer, Domain, Templates, Customize) between Free and Premium.

Namesilo & Manual Domain Linking

Option 1: Manual Domain Linking (Any Registrar)

If you purchase a domain for a user manually (e.g., from Namecheap, GoDaddy, or Namesilo), follow these steps to link it to their site:

  1. Get the User's Site URL: Ask the user for their current site link (e.g., https://pizzeria-1234.pizzariobot.com).
  2. Configure DNS: Go to your domain registrar's DNS settings for the new domain.
    • Create a CNAME record.
    • Host: @ (or www)
    • Value/Target: The user's current site URL (without https://).
    • Example: Point mypizza.com to pizzeria-1234.pizzariobot.com.
  3. Wait for Propagation: DNS changes can take 15-30 minutes.
  4. Inform the User: Tell the user their new domain is ready! They can now use mypizza.com to access their site.

Option 2: Namesilo API (Automated)

If you have a Namesilo account, you can let users search for domains directly in the bot.

  1. Open /admin → "Namesilo API Setup".
  2. Paste your Namesilo API key.
  3. Users can now use /domain to search for available domains.
  4. If they request a domain, you (the admin) will get a notification to approve/buy it manually.

Add More Themes

  1. Add new template HTML files to the templates directory.
  2. Users can then select the new template via /templates.
  3. Publish changes to apply the theme.

Add More Languages

  1. Enable Language feature as Free or Premium in the Premium Plan.
  2. Users can change their site language and republish.

Rename the Bot

  1. Open BotFather in Telegram.
  2. Use /setname and /setdescription to update display name and description.

Token remains unchanged. Users see the new name immediately.

Ask the AI Assistant

Use /ai <question> at any time for setup help, troubleshooting, or best practices. The assistant is available immediately after startup.

Health Check & Ports

👤 User Documentation

Everything users need to know to create and manage their pizza website.

How Users Generate a Site

  1. Send /start and follow onboarding prompts.
  2. Share GPS location to auto-detect country, currency, and phone code.
  3. Enter your pizzeria name and phone number.
  4. Use the "Add Your Pizza Menu" button to create your menu.
  5. Optionally add pizza images and social media links.
  6. Your site will be published and you'll receive the URL!

Edit Main Offer (Hero)

The offer appears in the hero section at the very top of your website. It's the first thing visitors see!

  1. Send /offer to start editing.
  2. Enter your offer title (e.g., "50% OFF TODAY!").
  3. Enter your offer description (e.g., "Use code PIZZA50").
  4. Click "Redeploy Now" to publish changes.

Change Language

  1. Send /language to see available languages.
  2. Select your preferred language.
  3. Click "Apply Now" to republish your site in the new language.

Customize the Site

Pizza Menu

Use the Web App button during onboarding to enter your pizzas, prices, and categories. You can update and republish at any time by using /customize.

Site Logo

Go to /customize → "Change Logo" and upload your logo image. The bot will resize it automatically.

About Us Section

Use /customize → "Edit About Us" to add a personal description and image for your restaurant.

Social Pages

Add your Facebook, Instagram, and X (Twitter) links during onboarding or via /customize.

Edit Location

Use /customize → "Edit Location" to update your address. The map on your website will update automatically.

Contact Support

  1. Send /support to open the help desk.
  2. Select the topic that matches your issue.
  3. Describe your problem in detail.
  4. The admin will respond directly to you in Telegram.
  5. Use "My Ticket History" to view past conversations.

Frequently Asked Questions

How much does it cost?

Creating a basic website is free! Premium features (custom domain, advanced templates, offers) require a subscription.

How do I update my menu?

Use /customize → "Edit Menu" to add, remove, or modify your pizza items.

Can I have multiple websites?

Currently, each Telegram account can have one website. Contact support if you need additional sites.

How do customers order?

Your website has a WhatsApp button that allows customers to send orders directly to your phone number.

Is my website mobile-friendly?

Yes! All templates are fully responsive and look great on phones, tablets, and computers.