Local Setup & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Local setup for the CodeBot project involves configuring three primary components: the Telegram Bot core, the Flask-based Webapp, and the underlying storage layers (MongoDB and Redis). This guide details the environment requirements, installation steps, and service execution strategies for developers working in a local or cloud-based development environment.
The architecture separates concerns between the Telegram Interface, the Command Processing Layer, and the Web Application, all of which rely on shared infrastructure services such as MongoDB for data persistence and Redis for caching and rate limiting.
System Prerequisites and Environment
The project requires a modern Python environment and specific database services to function correctly. Python 3.11+ is required, with version 3.12 recommended for optimal compatibility.
Core Dependencies
| Component | Requirement | Purpose |
|---|---|---|
| Python | 3.11+ (3.12 Recommended) | Main application runtime |
| MongoDB | Local or Atlas Instance | Primary data persistence for snippets and users |
| Redis | Optional (Recommended) | Used for rate limiting and performance caching |
| Telegram Bot | Bot Token | API access for the Telegram interface |
Sources: CLOUD.md:16-20, webapp/README.md:121-125
Installation Flow
The following diagram illustrates the sequence for setting up a local development environment.
A concise flow showing the transition from initial cloning to running both the bot and web interfaces.
Sources: CLOUD.md:23-45, webapp/README.md:128-143
Component Configuration
Configuration is managed primarily through environment variables defined in a .env file. A template is provided via .env.example.
Minimum Required Variables
Developers must configure the following keys at a minimum to start the services:
| Service | Environment Variable | Description |
|---|---|---|
| Bot Core | BOT_TOKEN | Telegram Bot API token |
| Data | MONGODB_URL | Connection string for MongoDB |
| Webapp | SECRET_KEY | Encryption key for Flask sessions |
| Webapp | WEBAPP_URL | The public or local URL of the web app |
Sources: CLOUD.md:47-65, webapp/README.md:204-227
Service Execution
CodeBot provides multiple entry points depending on the developer's focus (Bot vs. Webapp).
Running the Bot
The bot can be started directly using the Python interpreter. For detailed debugging, the LOG_LEVEL environment variable can be set to DEBUG.
# Standard start
python main.py
# Verbose debugging
LOG_LEVEL=DEBUG python main.py
Sources: CLOUD.md:23-28
Running the Web Application
The web application is a Flask-based service located in the webapp/ directory. It can be run standalone or via wrapper scripts designed for production-like environments.
# Simple local start
cd webapp
python app.py
# Production-friendly wrapper
./scripts/start_webapp.sh
Sources: CLOUD.md:31-37, webapp/README.md:139-143
Integrated Execution
To run the webapp and the AI explain service together, the project provides a consolidated script: ./scripts/run_all.sh.
Sources: CLOUD.md:39-40
Testing and Documentation
The project utilizes pytest for its testing suite. Local testing requires specific environment flags to bypass production components like the activity reporter or the live database if mocks are preferred.
Test Execution Sequence
Showing the steps to initialize and run the automated test suite.
Sources: CLOUD.md:68-81
Documentation Build
API documentation is managed via Sphinx. A utility script, build_docs.sh, automates the process of cleaning old builds and generating new HTML documentation.
# Build project documentation
./build_docs.sh
This script checks for Sphinx, installs missing requirements from docs/requirements.txt, and generates the HTML output in docs/_build/html/index.html.
Sources: build_docs.sh:1-35
Development Guidelines
When contributing locally, developers should adhere to the following safety and style rules:
- Conventional Commits: Use tags like
feat,fix,docs, andrefactorin commit messages. - File I/O: Only perform test/script I/O under
/tmpusing thetmp_pathwrapper. - CI/CD Safety: Avoid using
sudo, interactive commands (e.g.,git rebase -i), or pushing to remote unless requested by the project workflows.
Sources: CLOUD.md:8-14, CLOUD.md:88-99
Establishing a local setup allows for a robust development lifecycle, ensuring that all components from the snippet repository core to the web-based dashboard are functional and testable before deployment.
Sources: webapp/README.md:230-245