Metadata-Version: 2.4
Name: obs-git-explorer
Version: 0.1.0
Summary: OBS Git Web Interface for Open Build Service backend and Gitea
Home-page: https://github.com/openSUSE/obs-lite
Author: Adrian Schröter
Author-email: adrian@suse.de
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Framework :: Flask
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask>=2.2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: markdown>=3.4.0
Requires-Dist: yaspin>=2.3.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: redis>=4.5.0
Requires-Dist: flask-socketio>=5.3.0
Requires-Dist: python-socketio>=5.9.0
Requires-Dist: eventlet>=0.33.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# OBS Git Explorer

A lightweight web interface for the Open Build Service (OBS), focusing on **git-managed sources** and providing a modern, streamlined experience for package development workflows.

## Overview

OBS Git Explorer is a read-only web application that provides an intuitive interface to browse and monitor OBS build results with a focus on packages synchronized from Git repositories. It seamlessly integrates with Gitea to provide a unified view of your git repositories and their build status.

## Key Features

### 🔧 Git-Centric Approach

This interface emphasizes a **package-centric approach** for git-based packages. This means all maintained branches are hosted in the same organisation. It seamlessly integrates with Gitea to show repository details, branches, commits, and build status for packages synchronized from git repositories.

### 📦 Legacy Project Support

While the interface excels with git-managed packages, you can also **browse legacy OBS projects** that use traditional source handling. Note that functionality for these legacy projects is limited, as the focus is on modern git-based workflows.

### 🔍 Search and Browse Build Results

The interface is designed to make it easy to **search and browse build results** across projects, repositories, and architectures. The monitor page provides real-time build status updates with efficient filtering and search capabilities.

### 👁️ Read-Only Access

OBS Git Explorer is **read-only by design**. It can be used with any web browser or HTTP client that doesn't attempt modifications. This makes it safe for browsing, monitoring, and analysis without risk of accidental changes.

### API Provider

OBS Git Explorer can be used as api for an OBS instance. It is possible to use it for example to get build logs, run
local builds and do other non-modifing operations.

## Deployment Options

### 🌐 Default Configuration

By default, the interface connects to the **official openSUSE OBS instance** at `api.opensuse.org`, making it immediately useful for openSUSE development. It is using your local osc authentification cookie by default.

### 💻 Local Deployment

The interface can be run **locally on your machine** and configured to connect to any OBS API endpoint. This is perfect for:

- Development and testing workflows
- Connecting to custom OBS instances
- Private or internal build services
- Offline work with local OBS backends

### 🖥️ Local OBS Backend

If you have a **local OBS instance** running, the interface can connect directly to it, providing the same intuitive git-centric experience for your local build infrastructure.

## Running Locally

### Prerequisites

- Python 3.13 or higher
- pip (Python package manager)

### Installation

1. Clone or download the repository:
   ```bash
   cd /path/to/obs-lite-flask
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

   Or install required packages manually:
   ```bash
   pip install flask requests markupsafe markdown
   ```

### Quick Start

Run the application with default settings (connects to api.opensuse.org),
using your osc login cookie:

```bash
python obs_git_explorer.py --read-osc-cookie
```

Then open your browser and navigate to:
```
http://localhost:5000
```

### Configuration Options

#### Using Command-Line Arguments

```bash
# Connect to a custom OBS server
python obs_git_explorer.py --gitea-url https://gitea.example.com --backend-url https://api.example.com/

# Connect to a local OBS source server, using openSUSE gitea server
python obs_git_explorer.py --backend-url http://localhost:5352/

# Specify also a custom Gitea server
python obs_git_explorer.py --backend-url http://localhost:5352/ --gitea-url https://gitea.example.com --gitea-org my_default_organisation

# Change port and host. Use 0.0.0.0 to make it accessable from all networks.
python obs_git_explorer.py --host 127.0.0.1 --port 8080

# Enable debug mode
python obs_git_explorer.py --debug

# Use authentication
python obs_git_explorer.py --username myuser --password mypass

# Use OSC cookie (read from ~/.local/state/osc/cookiejar)
python obs_git_explorer.py --read-osc-cookie

# Use SSH signature authentication (like osc)
python obs_git_explorer.py --ssh-auth --ssh-user myuser --ssh-key ~/.ssh/id_rsa
```

#### Using Configuration File

Create a configuration file at `~/.config/obs-lite/config.ini`:

```ini
[server]
host = 127.0.0.1
port = 5000
debug = false

[backend]
url = https://api.opensuse.org/

# Authentication (choose one method)
# Read OSC cookie
read_osc_cookie = true

# Or use HTTP Basic Auth
# username = myuser
# password = mypass

# Or use SSH signature auth
# ssh_enabled = true
# ssh_user = myuser
# ssh_key_path = ~/.ssh/id_rsa

[gitea]
url = https://src.opensuse.org
organization = pool

[ssl]
# SSL certificate verification
verify = /etc/ssl/ca-bundle.pem
# verify = true
# verify = false

[features]
enable_gitea_iframe = false
```

Then run:
```bash
python obs_git_explorer.py --config-file ~/.config/obs-lite/config.ini
```

Or if using the default location:
```bash
python obs_git_explorer.py
```

See `config.ini.example` for complete configuration reference.

### Daemon Cache Mode (Optional)

For production deployments with high traffic, you can enable **daemon cache mode** to improve performance by offloading cache updates to a background process:

1. Enable daemon mode in your config:
```ini
[cache]
daemon_mode = true
```

2. Run the cache daemon as a background service:
```bash
# Run manually
obs-git-cache-daemon --config-file ~/.config/obs-lite/config.ini

# Or as systemd service (recommended)
sudo cp obs-git-cache-daemon.service.example /etc/systemd/system/obs-git-cache-daemon.service
sudo systemctl enable obs-git-cache-daemon
sudo systemctl start obs-git-cache-daemon
```

3. Run the web application (which now uses read-only cache):
```bash
gunicorn -c gunicorn.conf.py obs_git_explorer.wsgi:app
```

**How it works:**
- **Daemon mode OFF (default):** Web app updates caches on-demand when users access pages
- **Daemon mode ON:** Web app reads from cache only; daemon listens to OBS `/lastevents` and updates caches in real-time when changes occur
- The daemon uses event-driven updates via `/lastevents` endpoint with `client=obs-lite` and `obsname=HOSTNAME`
- Events are tracked using the sync number, ensuring no events are missed
- This provides near-instant cache updates while keeping web app response times consistent

**Event-driven architecture:**
- Daemon connects to OBS `/lastevents` endpoint
- Backend returns events with a sync number
- Daemon processes relevant events (project/package changes)
- Updates affected caches immediately
- Uses sync number on next call to get only new events
- Fallback to periodic refresh on errors

**When to use:**
- High-traffic deployments with many concurrent users
- When cache updates cause noticeable delays in web responses
- Production environments where consistent response times matter
- When you want real-time cache updates instead of periodic polling

### SPDX Product Tracking (Optional)

The daemon can scan local directories for SPDX JSON files to track product builds:

1. Configure SPDX directories in your config:
```ini
[spdx]
# Directories to scan for SPDX JSON files (comma-separated)
directories = /srv/www/htdocs/spdx,/var/lib/obs/spdx

# Scan interval in seconds (default: 3600 = 1 hour)
scan_interval = 3600
```

2. SPDX files are expected to have a `name` field with format:
   ```
   NAME-VERSION-ARCHITECTURE-BUILD_NUMBER
   ```
   Example: `openSUSE-Tumbleweed-DVD-x86_64-20231201`

3. The daemon will:
   - Scan configured directories for `*.spdx.json` and `*.spdx` files recursively
   - Parse the product name, version, architecture, and build number
   - Store this information in the cache for later use
   - Rescan periodically based on the configured interval

## Use Cases

- **Package Maintainers:** Monitor build status across multiple repositories and architectures
- **Developers:** Track git-synchronized packages and their build results
- **Release Managers:** Get an overview of project health and build failures
- **Contributors:** Browse packages and understand build dependencies
- **CI/CD Integration:** Read-only API access for automation and monitoring

## Technical Details

- **Backend:** Flask web framework
- **Caching:** SQLite-based per-backend caching for performance
- **Authentication:** Supports OSC cookies, HTTP Basic Auth, and SSH signature authentication
- **API Access:** Read-only proxy to OBS API endpoints
- **Gitea Integration:** API-based integration with Gitea for repository information

## Security

This application is **read-only by design**:
- Only GET requests are allowed
- POST, PUT, PATCH, and DELETE requests are blocked
- No modifications can be made to OBS backend
- Safe for public access and monitoring

## Examples


### Use with your osc again Official openSUSE OBS
```bash
python obs_git_explorer.py --read-osc-cookie
```

### Connect to Local OBS Instance Backend
```bash
python obs_git_explorer.py --backend-url http://localhost:5352/
```

### Connect to Custom OBS with Authentication
```bash
python obs_git_explorer.py \
  --backend-url https://build.example.com/ \
  --username myuser \
  --password mypass \
  --gitea-url https://git.example.com \
  --gitea-org myorg
```

## Build Badge Examples


![Build results simple](https://gitexplorer.opensuse.org/badge/home:adrianSuSE:obs-git.svg)
![Build results table](https://gitexplorer.opensuse.org/badge/home:adrianSuSE:obs-git/_table.svg)

The table is currently limited by 50 packages, but it prefers failed and active builds.
See the api documentation how to apply filters on them.

## License

This software is under GPLv3.

## Support

For issues, feature requests, or contributions, please visit the project repository.
