Hamster Keys Generator

Table of Contents

• Project Description
• Main Features
• Installation
• Environment Configuration
• Running with Docker
• Commands
• Continuous Integration/Continuous Deployment (CI/CD)
• Project Structure
• Contributing
• License

Project Description

The Hamster Keys Generator project is a system that automatically generates promo codes for various games. User interaction is handled through a Telegram bot, while code generation and management, using proxy servers to send requests to game APIs, ensure seamless integration with game platforms. A PostgresSQL database is used for storing promo codes, and sessions and requests are processed asynchronously with the aiohttp library. The system uses a Redis database for session management and caching to improve performance.

The project utilizes:

• Alembic for database migrations,
• SQLAlchemy for database interaction,
• Aiogram for working with the Telegram API,
• Docker for containerization.

Main Features:

Farmer

• Automatic promo code generation and database storage for games.
  • Easily generate promo codes for multiple games and automatically save them in the database.
• Detailed logging and error handling.
  • All stages of the generation process are logged for transparency, and in case of errors, the farmer automatically restarts on a timed schedule.
• Proxy support for API requests.
  • Ensures reliable API access even when geographical restrictions or rate limits are in place.

Telegram Bot

• Key distribution.
  • Quick access for users to claim keys via a multilingual interface.
• Admin commands.
  • Manage users and bot settings with powerful admin tools.
• Request rate-limiting.
  • Controls the number of promo code requests per user to prevent abuse.
• Boosted key counts (POPULARITY_COEFFICIENT).
  • Displays inflated key counts to attract more users.
• Multilingual support.
  • Easy switching between languages for a global audience.
  • Supported languages: en, ru, uk, sk, es, fr, tr, ar, de, fa, ur, hi
• Donation system (XTR stars).
  • Users can donate using fixed or custom amounts of Telegram stars.
  • Includes payment confirmation, cancellation, and refund options.
• Referral links.
  • Add your referral links: Promote your projects by adding referral links. Encourage users to invite others and get bonuses in return.
• Achievement system.
  • Track user progress: Users can unlock achievements based on their activity and receive special rewards as they progress.

Redis Integration

• Session and caching management.
  • Redis is used to manage sessions and cache frequently used data, providing faster access and reducing the load on the PostgreSQL database.

Installation

Requirements

• Python 3.10+
• PostgreSQL 16.3+
• Docker (for deployment using Docker Compose)

Installing Dependencies

Install the required dependencies with:

pip install -r requirements.txt

Environment Configuration

Create a .env file in the project root directory based on the provided .env.example file. Fill it with the following parameters:

DATABASE_NAME=your_database_name
DATABASE_USER=your_database_user
DATABASE_PASSWORD=your_database_password
DATABASE_HOST=your_database_host
DATABASE_PORT=your_database_port

BOT_TOKEN=your_telegram_bot_token
GROUP_CHAT_ID=your_group_chat_id
POPULARITY_COEFFICIENT=1

REDIS_HOST=your_redis_host
REDIS_PORT=your_redis_port
REDIS_DB=0

Running with Docker

1. Build and start the containers using Docker Compose:

docker-compose up -d postgres redis

2. Apply migrations and set up the database:

alembic upgrade head

Running the Bot

After setting up the database and configuration, you can start the bot with Python:

python bot/main.py

Running the Farmer

The farmer can be started as a separate process:

python app/main.py

Logging

Logs are saved in the logs directory. Log files are rotated when they reach 10 MB, with up to 5 backup copies retained.

Commands

User Commands

• /start – Start the bot
• /change_lang – Change the language
• /paysupport – Support via donations

Admin Commands

• /admin – Open admin panel

Continuous Integration/Continuous Deployment (CI/CD)

This project uses GitHub Actions for:

• Linting with Flake8 on every push,
• Building and deploying when changes are pushed to the main branch,
• Auto-release creation for new tags.

Configuration

Make sure to configure the following GitHub Secrets for deployment:

• HOST: The remote server host.
• USERNAME: The SSH username.
• PORT: The SSH port.
• SSHKEY: The private SSH key for connecting to the remote server.

Project Structure

.
├── app                  # Logic of generating promo codes
│   ├── main.py
│   ├── game_promo_manager.py
│   ├── games.py
│   ├── database.py
│   ├── models/
│   └── proxies.txt
├── bot                  # Telegram bot
│   ├── main.py
│   ├── config.py
│   ├── redis_client.py
│   ├── handlers/
│   ├── translations/
│   └── keyboards/
├── alembic              # Database migrations
│   ├── versions/
│   └── env.py
├── backups              # Database backups
├── redis.conf           # Redis configuration file
├── docker-compose.yml   # Docker configuration
├── requirements.txt     # Project dependencies
├── .env                 # Environment Configuration
└── README.md            # Project Description

Contributing

We welcome contributions to Hamster-code-generator. To contribute:

1. Fork the repository.
2. Create a new branch for your changes.
3. Make your changes and commit them to your branch.
4. Update your branch from the main repository:

   git fetch upstream
   git merge upstream/main

5. Submit a pull request.

We will review your pull request and provide feedback as needed.

License

This project is licensed under the MIT License. See the LICENSE file for more information.