Moving Between Self-Hosted Servers

Safely migrate your bot between different self-hosted Telegram Bot API server instances

Migration Scenarios

You may need to move your bot between self-hosted servers in several situations:

• Infrastructure changes: Migrating to new hardware or cloud providers
• Disaster recovery: Moving to a backup server after an outage
• Load balancing: Redistributing bots across multiple server instances
• Environment transitions: Moving from development to production

If the same bot is logged in on multiple servers simultaneously, update delivery is not guaranteed. Always properly deregister from the old server before starting on the new one.

Understanding the Data Directory

Each bot stores its data in a subdirectory named after the bot’s user ID within the server’s working directory (default: /data).

/data/
├── 123456789/          # Bot user ID subdirectory
│   ├── photos/
│   ├── videos/
│   ├── documents/
│   └── ...             # Other bot-specific data
├── 987654321/          # Another bot's subdirectory
└── logs/
    └── telegram-bot-api.log

The bot user ID is different from the bot token. You can find it by calling getMe on your bot or extracting it from the first part of your bot token (before the colon).

Migration Procedure

1. Call logOut on the old server

   First, deregister your bot from the current server by calling logOut:

   curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/logOut
   

   This prevents the old server from receiving any new updates and prepares the bot for migration.

   Do not skip this step. Running the same bot on multiple servers will cause unpredictable behavior and update loss.

2. Optional: Clean up webhook and close connection

   To minimize update loss during migration, perform these additional cleanup steps:

   # Delete webhook configuration
   curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/deleteWebhook
   
   # Close the bot connection gracefully
   curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/close
   

   Calling deleteWebhook and close helps ensure a clean shutdown and reduces the risk of losing updates during the transition.

3. Stop the old server container

   Ensure the old server is fully stopped before moving data:

   docker stop telegram-bot-api
   

   This prevents file corruption during the data transfer.

4. Transfer the bot subdirectory

   Move the bot’s data directory from the old server to the new server.

   If servers are on the same host:

   # Copy the bot subdirectory
   cp -r ./old-data/<BOT_USER_ID> ./new-data/<BOT_USER_ID>
   

   If servers are on different hosts:

   # On the old server, create an archive
   tar -czf bot-data.tar.gz -C /path/to/old-data <BOT_USER_ID>
   
   # Transfer to new server
   scp bot-data.tar.gz user@new-server:/path/to/new-data/
   
   # On the new server, extract
   tar -xzf bot-data.tar.gz -C /path/to/new-data/
   

   Using Docker volumes:

   # On the old server
   docker cp telegram-bot-api:/data/<BOT_USER_ID> ./bot-backup/
   
   # Transfer to new server, then:
   docker cp ./bot-backup/<BOT_USER_ID> new-telegram-bot-api:/data/
   

   Ensure the bot subdirectory has the correct ownership and permissions on the new server. The directory should be readable and writable by the user running the Telegram Bot API server (typically botapi with UID 1000).

   # Set correct ownership (if needed)
   chown -R 1000:1000 /path/to/new-data/<BOT_USER_ID>
   
5. Start the new server

   Launch the Telegram Bot API server on the new host:

   docker run -d --name telegram-bot-api \
     --env-file .env \
     -p 8081:8081 -p 8082:8082 \
     -v "$(pwd)/new-data:/data" \
     ragnarok22/telegram-bot-api-docker
   

   The server will automatically detect the existing bot data in the transferred subdirectory.

6. Update bot client configuration

   Point your bot application to the new server:

   # Update base URL to new server address
   app = ApplicationBuilder().token("YOUR_BOT_TOKEN").base_url(
       "http://new-server:8081/bot"
   ).build()
   

   Restart your bot application after updating the configuration.

Verification Steps

After completing the migration, verify everything is working correctly:

1. Check bot identity

   curl http://new-server:8081/bot<TOKEN>/getMe
   

   Verify the response contains the correct bot information.

2. Verify webhook configuration

   If using webhooks, check and reconfigure if necessary:

   # Check current webhook
   curl http://new-server:8081/bot<TOKEN>/getWebhookInfo
   
   # Set webhook if needed
   curl -X POST http://new-server:8081/bot<TOKEN>/setWebhook \
     -d "url=https://your-domain.com/webhook"
   
3. Test file access

   If your bot stores files, verify they are accessible:

   # List bot directory contents (inside container)
   docker exec telegram-bot-api ls -la /data/<BOT_USER_ID>/
   

   Send a file to your bot and ensure it’s stored correctly in the new location.

4. Monitor logs

   Check the server logs for any errors:

   # View container logs
   docker logs telegram-bot-api
   
   # View API server logs
   docker exec telegram-bot-api tail -f /data/logs/telegram-bot-api.log
   

Preventing Update Loss

To minimize the risk of losing updates during migration:

1. Schedule during low-activity periods: Migrate when your bot has minimal traffic
2. Use close method: Call close before logOut to gracefully shut down the connection
3. Quick transition: Minimize the time between logging out of the old server and starting the new one
4. Monitor update IDs: Track the last received update ID before and after migration to detect any gaps
5. Test in development: Practice the migration process with a test bot first

Telegram’s update delivery system is designed to be resilient. Brief disconnections during migration typically don’t result in lost updates, as Telegram will retry delivery to the new server once it’s online.

Rollback Procedure

If issues arise after migration, you can roll back to the old server:

1. Log out from new server

   curl http://new-server:8081/bot<TOKEN>/logOut
   
2. Restart old server

   Start the old server with the original data:

   docker start telegram-bot-api
   
3. Revert bot client

   Update your bot application to point back to the old server.

Common Issues

• Permission denied errors: Ensure the bot subdirectory has correct ownership (UID 1000 for the botapi user)
• Bot data not found: Verify the subdirectory name matches the bot’s user ID exactly
• Updates not arriving: Confirm you called logOut on the old server and the new server is properly started
• File paths broken: If using local mode, ensure TELEGRAM_LOCAL is set consistently on the new server

Next Steps

• Review environment variables for server configuration
• Set up health checks for your new server
• Configure volume mounts to protect bot data