docs(readme): add docker-optimized usage guide

* Introduces a detailed `README.md` covering installation,
  configuration, architecture, and development workflow for the Dockerized
  Git web interface.
* Updates repository documentation to highlight containerized deployment,
  Lighttpd proxy integration, syntax highlighting, and markdown rendering.
* Refines `docker-compose.yaml` volume mounts for clarity and optional config.

Relates to improved onboarding and deployment consistency.

3 files changed, 224 insertions, 5 deletions

diff --git a/README b/README.cgit
index 7a6b4a4..7a6b4a4 100644
--- a/README
+++ b/README.cgit
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ea62330
--- /dev/null
+++ b/README.md
@@ -0,0 +1,221 @@
+# CGit - Dockerized Git Web Interface
+
+This repository contains a customized version of [cgit](https://git.zx2c4.com/cgit/about/) - a fast web interface for Git repositories, optimized for Docker deployment with Lighttpd and Gitea integration.
+
+## 🎯 Key Features
+
+- **Docker-Optimized**: Fully containerized solution with multi-stage builds
+- **Lighttpd Integration**: Lightweight web server with CGI support and Git HTTP proxy
+- **Syntax Highlighting**: Highlight v4 integration for code display
+- **Markdown Rendering**: Automatic formatting of README and documentation files
+- **URL Normalization**: Automatic lowercase conversion for repository URLs
+- **Git Upgrade to v2.51.2**: Updated Git submodule for latest features and fixes
+
+## 🚀 Installation & Usage
+
+### Prerequisites
+- Docker and Docker Compose
+- Git repositories in `repos/` directory
+- Optional: Gitea or similar Git backend on port 3000
+
+### Quick Start (Production)
+
+```bash
+# Clone repository
+git clone <repository-url>
+cd cgit
+
+# Initialize Git submodules
+git submodule update --init --recursive
+
+# Build and start containers
+docker-compose up -d
+```
+
+Access the cgit interface at `http://localhost:8080`
+
+### Development Mode
+
+```bash
+# Use development Dockerfile
+docker-compose -f docker-compose.dev.yaml up -d
+
+# Follow logs
+docker-compose -f docker-compose.dev.yaml logs -f
+
+# Rebuild after changes
+docker-compose -f docker-compose.dev.yaml up -d --build
+```
+
+Changes to Lua scripts and filters take effect immediately in development mode.
+
+### Building from Source
+
+```bash
+# Build cgit locally
+make NO_REGEX=NeedsStartEnd LUA_PKGCONFIG=lua5.4 -j$(nproc)
+
+# Install
+sudo make install
+```
+
+## ⚙️ Configuration
+
+### Repository Settings (`cgitrc`)
+
+Key configuration options:
+
+```ini
+# Repository directory
+scan-path=/repositories
+
+# Cache settings (0 = disabled for development)
+cache-size=0
+
+# Enable commit graph visualization
+enable-commit-graph=1
+
+# Syntax highlighting filter
+source-filter=/usr/lib/cgit/filters/syntax-highlighting.sh
+
+# About page formatting (Markdown, RST, etc.)
+about-filter=/usr/lib/cgit/filters/about-formatting.sh
+
+# Clone URL template
+clone-url=https://git.bktus.com/$CGIT_REPO_URL.git
+
+# Statistics
+max-stats=year
+
+# Display local time instead of UTC
+local-time=1
+```
+
+### Repository List (`cgitrepos`)
+
+Define individual repositories in `/etc/cgitrepos`:
+
+```ini
+repo.url=project-name
+repo.path=/repositories/project-name.git
+repo.desc=Project description
+repo.owner=Owner Name
+```
+
+### Lighttpd Proxy Architecture
+
+Git HTTP requests (clone/fetch) are automatically proxied to the backend:
+
+```
+Client → Lighttpd (Port 80) → Gitea/Backend (Port 3000)
+```
+
+**Features:**
+- Read access via cgit interface
+- Write access via backend server
+- Seamless integration with Gitea/GitLab/etc.
+- Method restriction (GET/POST only)
+- URL normalization and lowercase enforcement
+
+### URL Normalization
+
+The system automatically handles URL normalization:
+
+1. **Lua Redirect** (`redirect_lower_url.lua`): Converts uppercase URLs to lowercase
+2. **Clone URL Normalization**: All generated clone URLs are lowercase
+3. **Query String Preservation**: Redirects maintain query parameters
+
+Example:
+```
+/GpgFrontend/about → 301 Redirect → /gpgfrontend/about
+```
+
+## 🔧 Development
+
+### Filter Customization
+
+Filters are located in `filters/`:
+- `syntax-highlighting.sh`: Code highlighting with inline CSS
+- `about-formatting.sh`: README/documentation formatting
+- `email-gravatar.py`: Gravatar avatar integration
+- `commit-links.sh`: Commit message link generation
+
+### Lua Scripts
+
+Lua scripts in `lua/`:
+- `redirect_lower_url.lua`: URL normalization and lowercase redirect
+
+### Adding New Filters
+
+1. Create filter script in `filters/`
+2. Make it executable: `chmod +x filters/your-filter.sh`
+3. Configure in `cgitrc`:
+   ```ini
+   source-filter=/usr/lib/cgit/filters/your-filter.sh
+   ```
+
+## 📁 Directory Structure
+
+```
+cgit/
+├── cgit.c                      # Main program (modified)
+├── cgit.css                    # Stylesheet
+├── cgitrc                      # Main configuration (customized)
+├── cgitrepos                   # Repository list
+├── Dockerfile                  # Production image (Alpine-based)
+├── Dockerfile.dev              # Development image (Ubuntu-based)
+├── docker-compose.yaml         # Production setup
+├── docker-compose.dev.yaml     # Development setup
+├── lighttpd.conf               # Web server config (with proxy)
+├── filters/                    # Filter scripts
+│   ├── syntax-highlighting.sh
+│   ├── about-formatting.sh
+│   └── ...
+├── lua/                        # Lua extensions
+│   └── redirect_lower_url.lua
+├── repos/                      # Git repositories
+├── git/                        # Git submodule (v2.46.0)
+└── .github/
+    └── workflows/              # CI/CD workflows
+```
+
+## 🐛 Known Limitations
+
+- Cache disabled in current configuration (development mode)
+- Proxy only handles GET/POST requests
+- Backend server must be accessible on configured port
+- URL normalization is case-insensitive (by design)
+
+## � CI/CD
+
+The repository includes a GitHub Actions workflow:
+- Automated Docker image builds
+- Reusable `docker-build` workflow
+- Registry configuration via secrets
+- Multi-architecture support (optional)
+
+## 📚 Additional Resources
+
+- **Original cgit Documentation**: See `README.cgit`
+- **cgitrc Man Page**: Run `man cgitrc` or see `cgitrc.5.txt`
+- **Official cgit Site**: https://git.zx2c4.com/cgit/about/
+- **Git Submodule**: https://git.bktus.com (mirror)
+
+## 📝 License
+
+CGit is licensed under the GNU General Public License v2. See `COPYING` for details.
+
+## 👤 Author
+
+**Modifications by Saturneric**
+- Docker deployment optimization
+- Gitea proxy integration
+- URL normalization system
+- CI/CD pipeline
+- Enhanced syntax highlighting
+
+---
+
+**Root Title**: Git Repos of Saturneric  
+**Root Description**: Hosting opensource projects related to Saturneric  
+**Clone URL**: `https://git.bktus.com/$CGIT_REPO_URL.git`
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 7767331..98ed42c 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -6,8 +6,6 @@ services:
     ports:
       - "8080:80"
     volumes:
-      - ./cgit:/usr/share/webapps/cgit/cgit.cgi
-      - ./repos:/home/git/repositories
-      - ./lighttpd.conf:/etc/lighttpd/lighttpd.conf:ro
-      - ./cgitrc:/etc/cgitrc:ro
-      - ./cgitrepos:/etc/cgitrepos:ro
\ No newline at end of file
+      - ./repos:/repositories:ro
+      # - ./cgitrc:/etc/cgitrc:ro # optional
+      # - ./cgitrepos:/etc/cgitrepos:ro # optional