diff options
| -rw-r--r-- | README.cgit (renamed from README) | 0 | ||||
| -rw-r--r-- | README.md | 221 | ||||
| -rw-r--r-- | docker-compose.yaml | 8 |
3 files changed, 224 insertions, 5 deletions
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 |