cityhive

CityHive is an experimental aiohttp-based microservice designed to explore modern Python web development patterns, architecture, and DevOps practices in an urban beehive management context. It uses a lightweight asynchronous web framework, PostgreSQL with an async ORM, and Docker for production-like environment orchestration. The MCP server entry point is intended to be run via uv (Python/uv) package management, enabling easy execution of the CityHive server and its tooling. Once running, CityHive exposes REST endpoints for interacting with the beehive simulation and provides an environment suitable for testing deployment workflows and structural patterns emphasized in the project docs.

To run CityHive via MCP, install the required environment, start the service with uvx cityhive (as configured in mcp_config), and then interact with the HTTP API at the configured host/port (default http://localhost:8080). The project emphasizes a clean architectural approach, so you’ll find clearly separated domain, application, and infra layers, with asynchronous database access and structured logging. Typical workflows include performing migrations, running tests, and exercising the API endpoints to simulate urban beehive management scenarios. Be sure to provide a proper DATABASE_URL before running to ensure the application can connect to PostgreSQL.

Prerequisites:

• Python 3.12+
• Docker and Docker Compose
• Git

1. Install Python and Docker

   • Ensure Python 3.12+ is installed on your system.
   • Install Docker and Docker Compose following your OS guidelines.

2. Clone the repository

   git clone https://github.com/sergeyklay/cityhive.git
   cd cityhive
   

3. Set up dependencies and run via uvx

   • CityHive is intended to be run using the uvx command for Python/uv packaging.
   • If you don’t have uvx installed yet, install uv by following the project’s guidance.
   • Run CityHive with uvx (CityHive package name assumed to be cityhive):

   uvx cityhive
   

4. Configure environment variables

   • Create a local environment file or export variables for the database and server:

   export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/cityhive"
   export APP_HOST="0.0.0.0"
   export APP_PORT="8080"
   

   • Ensure PostgreSQL is running and accessible with the provided credentials.

5. Start the application with Docker (optional for production-like setup)

   docker compose up --build
   

6. Verify installation

   • After startup, verify the service is reachable at http://localhost:8080
   • Run tests if desired:

   make test
   

Tips and common issues:

• Ensure Python 3.12+ is used; some dependencies may require newer asyncio features.
• If uvx cityhive fails to start, double-check DATABASE_URL connectivity and that PostgreSQL is running.
• When using Docker, make sure the Docker daemon has enough resources (CPU/RAM) allocated for the database and server.
• The project uses Docker Compose for production-like workflows; use docker compose up --build to reproduce a full stack locally.
• Check docs/ for architecture and coding standards to understand the intended layer structure and patterns used by CityHive.
• Logging is structured in JSON; review log output for tracing and debugging in development and CI environments.