llms.txt

# PageKit Project Analysis

This document provides a comprehensive analysis of the PageKit project, designed to serve content from git repositories as websites, similar to GitHub Pages. It is built with Python, FastAPI, and intended for Kubernetes deployment.

## Overview

PageKit is a web server that interprets the hostname of an incoming HTTP request to determine which git repository to serve content from. For a request to `org-name.pages.yourdomain.com`, the server looks for a repository named `git-pages` within the `org-name` organization on your git instance.

## Core Components

1. **`pagekit/config.py`**: Manages application configuration using Pydantic Settings. It defines environment variables such as `REPO_URL`, `REPO_TOKEN`, `REPO_DEFAULT`, and `DEBUG`.

2. **`pagekit/main.py`**: The main application file that sets up the FastAPI app and handles HTTP requests. It routes requests to the appropriate content in git repositories based on the hostname.

3. **`pagekit/utils.py`**: Contains utility functions for interacting with git. This includes fetching file metadata and raw content from git repositories, as well as a custom Jinja2 loader for loading templates directly from git.

4. **`Dockerfile`**: Defines the Docker image for the application, specifying the base image, dependencies, and startup command.

5. **`Makefile`**: Provides shortcuts for common tasks like building the environment, building the Docker image, and running the application.

6. **`pyproject.toml`**: Defines the project's dependencies and metadata for Poetry, the Python package manager used in this project.

7. **`README.md`**: Provides an overview of the project, how it works, and instructions for getting started with deployment.

## Configuration

The application is configured via environment variables:

- `REPO_URL`: The full URL to your git instance (e.g., `https://git.example.com`).
- `REPO_TOKEN`: A git API token with at least read-access to the repositories you want to serve.
- `REPO_DEFAULT`: The name of the repository to serve for each organization. Defaults to `pagekit`.
- `DEBUG`: Enables debug logging when set to `true`.

## Technologies Used

- **Python**: The core programming language for the application.
- **FastAPI**: A modern, fast (high-performance) web framework for building APIs with Python 3.7+ based on standard Python type hints.
- **Uvicorn**: An ASGI server implementation for Python, used to serve the FastAPI application.
- **Requests**: A simple, yet elegant HTTP library for Python, used for making HTTP requests to the git API.
- **Jinja2**: A modern and designer-friendly templating language for Python, used for rendering HTML templates.
- **Markdown**: A Python library for parsing Markdown files and converting them to HTML.
- **Cachetools**: A collection of caching algorithms and data structures for Python, used to cache git API responses.
- **Pydantic**: Data validation and settings management using Python type hints, used for configuration.

## How It Works

1. The server receives an HTTP request and extracts the hostname.
2. It parses the hostname to determine the organization and repository name.
3. It uses the git API to fetch file metadata from the specified repository.
4. Based on the file type:
   - Markdown files (`.md`) are converted to HTML and rendered with a Jinja2 template. Frontmatter is extracted for metadata.
   - Other files (CSS, JS, images) are streamed directly to the client with the appropriate content type.
5. Templates are also loaded from the same git repository, allowing for dynamic content rendering.

This architecture allows organizations to create and manage their own websites by simply adding content to their `pagekit` repository.