h2orb 0.1.1__tar.gz

h2orb-0.1.1/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.gitignore
+.env
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__
+*.py[cod]
+*.egg-info
+build
+dist
+.coverage
+htmlcov
+docs/aqua-api/swagger.json

h2orb-0.1.1/.env.example

@@ -0,0 +1,16 @@
+ARB_APP_NAME=H2ORB – H2O Result Browser
+ARB_ENVIRONMENT=development
+ARB_HOST=127.0.0.1
+ARB_PORT=8000
+ARB_LOG_LEVEL=INFO
+
+ARB_AQUA_BASE_URL=https://aqua.example.invalid
+ARB_AQUA_WEB_BASE_URL=https://app.aqua-cloud.io/aquaWebNG
+ARB_NOISE_MARKER=[NOISE]
+ARB_AQUA_USERNAME=
+ARB_AQUA_PASSWORD=
+ARB_AQUA_VERIFY_TLS=true
+# Optional inside a container, for example: /certificates/company-ca.pem
+# ARB_AQUA_CA_BUNDLE=/certificates/company-ca.pem
+ARB_AQUA_TIMEOUT_SECONDS=30
+ARB_AQUA_MAX_CONNECTIONS=20

h2orb-0.1.1/.gitea/workflows/docker-publish.yaml

@@ -0,0 +1,108 @@
+name: Verify and publish Docker image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docker-publish-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  IMAGE_NAME: hrabovszki/h2orb
+  DOCKER_HOST: tcp://192.168.1.123:2375
+  DOCKER_CLI_VERSION: 28.3.3
+
+jobs:
+  verify:
+    name: Verify Python project
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Docker CLI
+        shell: bash
+        run: |
+          mkdir -p "$RUNNER_TEMP/docker-cli"
+          curl --fail --silent --show-error --location \
+            "https://download.docker.com/linux/static/stable/x86_64/docker-${DOCKER_CLI_VERSION}.tgz" \
+            | tar --extract --gzip --strip-components=1 --directory "$RUNNER_TEMP/docker-cli"
+          echo "$RUNNER_TEMP/docker-cli" >> "$GITHUB_PATH"
+          "$RUNNER_TEMP/docker-cli/docker" version
+
+      - name: Run tests and Ruff with Python 3.12
+        run: docker build --target verify --tag h2orb:verify .
+
+  image:
+    name: Build and publish linux/amd64 image
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Docker CLI
+        shell: bash
+        run: |
+          mkdir -p "$RUNNER_TEMP/docker-cli"
+          curl --fail --silent --show-error --location \
+            "https://download.docker.com/linux/static/stable/x86_64/docker-${DOCKER_CLI_VERSION}.tgz" \
+            | tar --extract --gzip --strip-components=1 --directory "$RUNNER_TEMP/docker-cli"
+          echo "$RUNNER_TEMP/docker-cli" >> "$GITHUB_PATH"
+          "$RUNNER_TEMP/docker-cli/docker" version
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Generate image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' }}
+            type=sha,prefix=sha-,format=short,enable=${{ github.ref == 'refs/heads/main' }}
+            type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-') }}
+            type=semver,pattern={{major}},enable=${{ startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-') }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-') }}
+          labels: |
+            org.opencontainers.image.title=H2ORB
+            org.opencontainers.image.description=Result browser and reporting tool for test-management data
+            org.opencontainers.image.licenses=LicenseRef-H2ORB-Community
+            org.opencontainers.image.revision=${{ github.sha }}
+
+      - name: Build and publish image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Update Docker Hub overview
+        uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5.0.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ env.IMAGE_NAME }}
+          short-description: A result browser and reporting tool for test-management data.
+          readme-filepath: ./README.md

h2orb-0.1.1/.gitea/workflows/pypi.yaml

@@ -0,0 +1,41 @@
+name: "Publish H2ORB to PyPI"
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Create build environment
+        shell: bash
+        run: |
+          python3 -m venv "$RUNNER_TEMP/h2orb-build-venv"
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m build
+
+      - name: Validate distributions
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m twine check dist/*
+
+      - name: Upload to PyPI
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

h2orb-0.1.1/.gitea/workflows/testpypi.yaml

@@ -0,0 +1,43 @@
+name: "Publish H2ORB to TestPyPI"
+
+on:
+  push:
+    tags:
+      - "test-v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Create build environment
+        shell: bash
+        run: |
+          python3 -m venv "$RUNNER_TEMP/h2orb-build-venv"
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m build
+
+      - name: Validate distributions
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m twine check dist/*
+
+      - name: Upload to TestPyPI
+        shell: bash
+        run: |
+          . "$RUNNER_TEMP/h2orb-build-venv/bin/activate"
+          python -m twine upload \
+            --repository-url https://test.pypi.org/legacy/ \
+            dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TESTPYPI_TOKEN }}

h2orb-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.codex-tmp/
+.coverage
+htmlcov/
+build/
+dist/
+.env
+.idea/
+.vscode/
+

h2orb-0.1.1/Dockerfile

@@ -0,0 +1,48 @@
+FROM python:3.12-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /build
+
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN python -m pip wheel --wheel-dir /wheels .
+
+
+FROM builder AS verify
+
+COPY tests ./tests
+
+RUN python -m pip install ".[dev]" \
+    && python -m pytest -p no:asyncio \
+    && python -m ruff check .
+
+
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    ARB_HOST=0.0.0.0 \
+    ARB_PORT=8000
+
+RUN groupadd --system h2orb \
+    && useradd --system --gid h2orb --create-home --home-dir /home/h2orb h2orb
+
+WORKDIR /app
+
+COPY --from=builder /wheels /wheels
+RUN python -m pip install /wheels/*.whl \
+    && rm -rf /wheels
+
+USER h2orb
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=3).read()"]
+
+CMD ["python", "-m", "h2orb"]

h2orb-0.1.1/LICENSE

@@ -0,0 +1,77 @@
+H2ORB Community License (Nicht-kommerzielle Nutzung)
+
+Copyright (c) 2026 Zoltán Hrabovszki
+
+1. Begriffe
+
+- "Software": das Projekt "H2ORB – H2O Result Browser" samt zugehöriger Quell- und
+  Binärdateien, Dokumentation und ausgelieferter Container-Images.
+- "Nicht-kommerzielle Nutzung": jede Nutzung zu privaten, akademischen oder
+  öffentlich zugänglichen, nicht-kommerziellen Zwecken ohne direkten oder
+  indirekten Umsatzbezug sowie die reine Evaluierung oder ein Proof of Concept.
+- "Kommerzielle Nutzung": jede Nutzung in oder für ein Produkt, einen Service
+  oder einen Prozess, der direkt oder indirekt Einnahmen generiert oder einer
+  geschäftlichen Tätigkeit dient. Dazu gehören insbesondere bezahlte Projekte,
+  Installationen oder Supportleistungen, Firmenbetrieb für kommerzielle Zwecke,
+  SaaS, Resale sowie kommerziell verwendete Originale, Änderungen, Forks und
+  abgeleitete Werke. Für kommerzielle Nutzung ist eine gesonderte kommerzielle
+  Lizenz erforderlich.
+
+2. Lizenzgewährung (nicht-kommerziell)
+
+Der Rechteinhaber gewährt eine weltweite, nicht-exklusive, nicht übertragbare,
+unentgeltliche Lizenz zur Nutzung, Vervielfältigung, Änderung und Weitergabe
+der Software ausschließlich für nicht-kommerzielle Zwecke, vorausgesetzt, dass
+(a) dieser Lizenztext in Kopien und abgeleiteten Werken enthalten bleibt und
+(b) Urheber- und Hinweistexte nicht entfernt werden.
+
+3. Einschränkungen
+
+- Kommerzielle Nutzung ist ohne kommerzielle Lizenz untersagt.
+- Marken- und Namensrechte werden nicht gewährt.
+- Unterlizenzierung ist nur unter Beibehaltung dieser Bedingungen zulässig.
+- Die Nutzung eines Forks, einer Änderung oder eines abgeleiteten Werks zu
+  kommerziellen Zwecken erfordert ebenfalls eine gesonderte kommerzielle
+  Lizenz des Rechteinhabers.
+
+4. Support
+
+Es besteht kein Anspruch auf Wartung, Support oder Updates.
+
+5. Gewährleistungsausschluss
+
+Die Software wird "wie besehen" ("AS IS") bereitgestellt, ohne ausdrückliche
+oder stillschweigende Gewährleistung. Insbesondere wird keine Gewähr für
+Marktgängigkeit, Eignung für einen bestimmten Zweck, Nichtverletzung von
+Rechten Dritter, Fehlerfreiheit, Richtigkeit oder Verfügbarkeit übernommen.
+
+6. Haftungsbeschränkung
+
+Soweit gesetzlich zulässig, haften der Rechteinhaber und Mitwirkende in keinem
+Fall für Schäden jedweder Art (einschließlich, aber nicht beschränkt auf
+direkte, indirekte, zufällige, besondere, exemplarische oder Folgeschäden,
+entgangenen Gewinn, Produktions- oder Betriebsunterbrechung, Datenverlust oder
+Rechtsverfolgungskosten), die aus der Nutzung, Unmöglichkeit der Nutzung oder
+Leistung der Software entstehen, selbst wenn auf die Möglichkeit solcher
+Schäden hingewiesen wurde.
+
+Unberührt bleiben zwingende Haftungstatbestände (z. B. nach dem
+Produkthaftungsgesetz) sowie die Haftung für Vorsatz, grobe Fahrlässigkeit oder
+für Verletzungen von Leben, Körper oder Gesundheit nach geltendem Recht.
+
+7. Laufzeit und Beendigung
+
+Diese Lizenz gilt bis zu ihrer Beendigung. Bei Verstoß erlischt das
+Nutzungsrecht automatisch; die Nutzung ist einzustellen. Rechte an bereits
+rechtmäßig weitergegebenen Kopien bleiben unberührt.
+
+8. Sonstiges
+
+Es gilt materielles Recht des Sitzstaats des Rechteinhabers unter Ausschluss
+des Kollisionsrechts. Sollte eine Bestimmung unwirksam sein, bleibt der Rest
+wirksam (Salvatorische Klausel).
+
+Kommerzielle Lizenz
+
+Für eine kommerzielle Nutzung (siehe Abschnitt 1) wenden Sie sich bitte an den
+Rechteinhaber, um Konditionen und Lizenzgebühren zu vereinbaren.

h2orb-0.1.1/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.5
+Name: h2orb
+Version: 0.1.1
+Summary: A result browser and reporting tool for test-management data.
+Project-URL: Homepage, https://github.com/Hrabovszki1023/H2ORB
+Project-URL: Repository, https://github.com/Hrabovszki1023/H2ORB.git
+Project-URL: Issues, https://github.com/Hrabovszki1023/H2ORB/issues
+Author: Zoltán Hrabovszki
+License: H2ORB Community License (Nicht-kommerzielle Nutzung)
+        
+        Copyright (c) 2026 Zoltán Hrabovszki
+        
+        1. Begriffe
+        
+        - "Software": das Projekt "H2ORB – H2O Result Browser" samt zugehöriger Quell- und
+          Binärdateien, Dokumentation und ausgelieferter Container-Images.
+        - "Nicht-kommerzielle Nutzung": jede Nutzung zu privaten, akademischen oder
+          öffentlich zugänglichen, nicht-kommerziellen Zwecken ohne direkten oder
+          indirekten Umsatzbezug sowie die reine Evaluierung oder ein Proof of Concept.
+        - "Kommerzielle Nutzung": jede Nutzung in oder für ein Produkt, einen Service
+          oder einen Prozess, der direkt oder indirekt Einnahmen generiert oder einer
+          geschäftlichen Tätigkeit dient. Dazu gehören insbesondere bezahlte Projekte,
+          Installationen oder Supportleistungen, Firmenbetrieb für kommerzielle Zwecke,
+          SaaS, Resale sowie kommerziell verwendete Originale, Änderungen, Forks und
+          abgeleitete Werke. Für kommerzielle Nutzung ist eine gesonderte kommerzielle
+          Lizenz erforderlich.
+        
+        2. Lizenzgewährung (nicht-kommerziell)
+        
+        Der Rechteinhaber gewährt eine weltweite, nicht-exklusive, nicht übertragbare,
+        unentgeltliche Lizenz zur Nutzung, Vervielfältigung, Änderung und Weitergabe
+        der Software ausschließlich für nicht-kommerzielle Zwecke, vorausgesetzt, dass
+        (a) dieser Lizenztext in Kopien und abgeleiteten Werken enthalten bleibt und
+        (b) Urheber- und Hinweistexte nicht entfernt werden.
+        
+        3. Einschränkungen
+        
+        - Kommerzielle Nutzung ist ohne kommerzielle Lizenz untersagt.
+        - Marken- und Namensrechte werden nicht gewährt.
+        - Unterlizenzierung ist nur unter Beibehaltung dieser Bedingungen zulässig.
+        - Die Nutzung eines Forks, einer Änderung oder eines abgeleiteten Werks zu
+          kommerziellen Zwecken erfordert ebenfalls eine gesonderte kommerzielle
+          Lizenz des Rechteinhabers.
+        
+        4. Support
+        
+        Es besteht kein Anspruch auf Wartung, Support oder Updates.
+        
+        5. Gewährleistungsausschluss
+        
+        Die Software wird "wie besehen" ("AS IS") bereitgestellt, ohne ausdrückliche
+        oder stillschweigende Gewährleistung. Insbesondere wird keine Gewähr für
+        Marktgängigkeit, Eignung für einen bestimmten Zweck, Nichtverletzung von
+        Rechten Dritter, Fehlerfreiheit, Richtigkeit oder Verfügbarkeit übernommen.
+        
+        6. Haftungsbeschränkung
+        
+        Soweit gesetzlich zulässig, haften der Rechteinhaber und Mitwirkende in keinem
+        Fall für Schäden jedweder Art (einschließlich, aber nicht beschränkt auf
+        direkte, indirekte, zufällige, besondere, exemplarische oder Folgeschäden,
+        entgangenen Gewinn, Produktions- oder Betriebsunterbrechung, Datenverlust oder
+        Rechtsverfolgungskosten), die aus der Nutzung, Unmöglichkeit der Nutzung oder
+        Leistung der Software entstehen, selbst wenn auf die Möglichkeit solcher
+        Schäden hingewiesen wurde.
+        
+        Unberührt bleiben zwingende Haftungstatbestände (z. B. nach dem
+        Produkthaftungsgesetz) sowie die Haftung für Vorsatz, grobe Fahrlässigkeit oder
+        für Verletzungen von Leben, Körper oder Gesundheit nach geltendem Recht.
+        
+        7. Laufzeit und Beendigung
+        
+        Diese Lizenz gilt bis zu ihrer Beendigung. Bei Verstoß erlischt das
+        Nutzungsrecht automatisch; die Nutzung ist einzustellen. Rechte an bereits
+        rechtmäßig weitergegebenen Kopien bleiben unberührt.
+        
+        8. Sonstiges
+        
+        Es gilt materielles Recht des Sitzstaats des Rechteinhabers unter Ausschluss
+        des Kollisionsrechts. Sollte eine Bestimmung unwirksam sein, bleibt der Rest
+        wirksam (Salvatorische Klausel).
+        
+        Kommerzielle Lizenz
+        
+        Für eine kommerzielle Nutzung (siehe Abschnitt 1) wenden Sie sich bitte an den
+        Rechteinhaber, um Konditionen und Lizenzgebühren zu vereinbaren.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: jinja2<4.0,>=3.1
+Requires-Dist: pydantic-settings<3.0,>=2.6
+Requires-Dist: python-multipart<1.0,>=0.0.12
+Requires-Dist: uvicorn[standard]<1.0,>=0.32
+Provides-Extra: dev
+Requires-Dist: pytest-cov<7.0,>=6.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.3; extra == 'dev'
+Requires-Dist: respx<1.0,>=0.22; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# H2ORB – H₂O Result Browser
+
+A result browser and reporting tool for test-management data. The current integration analyses
+AQUA test results through a server-side REST API proxy: credentials and direct communication with
+AQUA remain on the server, while users work through a browser interface.
+
+H2ORB is an independent project and is not affiliated with or endorsed by any
+test-management vendor.
+
+## Current state
+
+This repository contains a locally runnable FastAPI application with an asynchronous AQUA
+v26.30.0.0 REST client. Projects and folders can be selected in the browser and the application
+loads the corresponding scenarios, test cases, latest executions, and AQUA defects through its
+server-side proxy.
+
+The domain layer already implements the central aggregation rules:
+
+- every test case occurrence is evaluated in its own test scenario;
+- only the latest execution within that scenario is considered;
+- failed executions are classified as `F` (regular defect), `N` (defect marked as noise), or
+  `N?` (not yet linked to a defect);
+- `X` is the derived total of all failed results: `X = F + N + N?`;
+- compact rates and aggregate totals are calculated bottom-up for every tree level.
+
+Results are displayed in a compact German/English desktop interface as an expandable explorer tree.
+Project and folder rows are followed by test
+scenario (`TS`), test case (`TC`), execution (`TE`), and defect (`DF`) nodes. A test case contributes
+exactly one result. Execution and defect detail rows do not contribute additional results. Counts
+are aggregated bottom-up to scenarios, folders, and the selected project. See
+[`docs/result-tree.md`](docs/result-tree.md) for the complete presentation and aggregation rules.
+Passed test cases are grouped below each scenario, while an optional failure-focused view shows
+only `F`, `N`, and `N?` results and automatically opens their containing paths.
+
+The in-page report preview includes AQUA defect descriptions and links to scenarios, test cases,
+executions, and defects. The same report can be downloaded as Markdown. Its complete contract is
+specified in [`docs/report-contract.md`](docs/report-contract.md).
+
+The manual/automated distinction uses AQUA's standard `TestExecutionType` values (`Manual` and
+`Automated`). The application deliberately does not depend on company-specific fields, labels, or
+workflow terminology.
+
+## Screenshots
+
+### Expandable result tree
+
+The desktop-oriented result tree keeps paths, scenarios, test cases, executions, defects, status
+counts, and rates visible in one compact view. Passed test cases are grouped separately below each
+scenario.
+
+![Expandable AQUA result tree](https://raw.githubusercontent.com/Hrabovszki1023/H2ORB/main/docs/images/result-tree.png)
+
+### Failure-focused analysis
+
+The `Nur X-Testfälle` filter hides successful and otherwise irrelevant results. The remaining
+failures can be narrowed further to regular defects (`F`), confirmed noise (`N`), and unclassified
+failure candidates (`N?`).
+
+![Failure-focused result tree with F, N and N? filters](https://raw.githubusercontent.com/Hrabovszki1023/H2ORB/main/docs/images/failure-filter.png)
+
+### Select report summary sections
+
+Folder checkboxes select additional summary rows. The selected root folder is always included as
+the highlighted overall result.
+
+![Selecting folders for the report summary](https://raw.githubusercontent.com/Hrabovszki1023/H2ORB/main/docs/images/summary-selection.png)
+
+### Test completion report
+
+The report combines the selected summary rows with failed test details, latest executions, AQUA
+defects, defect descriptions, and direct links back to AQUA. It can also be downloaded as Markdown.
+
+![AQUA test completion report](https://raw.githubusercontent.com/Hrabovszki1023/H2ORB/main/docs/images/report-preview.png)
+
+## Install from PyPI
+
+Python 3.12 or newer is required:
+
+```powershell
+py -m pip install h2orb
+h2orb
+```
+
+Open <http://127.0.0.1:8000> after configuring the required `ARB_` environment variables.
+
+## Local setup
+
+Python 3.12 or newer is required.
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+Copy-Item .env.example .env
+python -m h2orb
+```
+
+Open <http://127.0.0.1:8000>. API documentation is available at
+<http://127.0.0.1:8000/docs>.
+
+Configuration uses environment variables prefixed with `ARB_`. Do not commit `.env` or real AQUA
+credentials.
+
+## Security notice for the current version
+
+The current version uses the AQUA credentials configured centrally through environment variables.
+Consequently, every person who can reach the H2ORB web interface can read the AQUA projects and test
+data available to that account.
+
+- Run H2ORB only in a trusted internal network.
+- Do not publish port `8000` directly on the Internet.
+- Restrict access with firewall rules; a reverse proxy with HTTPS and access control is recommended.
+- Use a dedicated, read-only AQUA account with only the projects H2ORB is intended to display.
+- Keep `.env`, passwords, certificate keys, and access tokens outside the image and repository.
+- Treat generated reports as potentially confidential test data.
+
+The next version is planned to request personal AQUA credentials and keep separate server-side
+sessions for individual users. Until that authentication is implemented, network-level access
+control is mandatory.
+
+## Docker
+
+### Run the published image
+
+After creating a local `.env` from `.env.example`, pull and run the public `linux/amd64` image:
+
+```powershell
+docker pull hrabovszki/h2orb:main
+docker run --detach --name h2orb `
+  --restart unless-stopped `
+  --env-file .env `
+  --env ARB_HOST=0.0.0.0 `
+  --publish 8000:8000 `
+  hrabovszki/h2orb:main
+```
+
+Use an immutable version or `sha-*` tag for reproducible deployments. The `main` tag tracks the
+latest successful build from the main branch.
+
+### Build locally
+
+Build and start the local container with the existing `.env` configuration:
+
+```powershell
+docker compose up --build -d
+docker compose ps
+```
+
+Open <http://127.0.0.1:8000>. Stop and remove the container with:
+
+```powershell
+docker compose down
+```
+
+The image runs as an unprivileged `h2orb` user, exposes port `8000`, and checks `/health`. The `.env`
+file is excluded from the build context and is injected only when the container starts.
+
+To test the AQUA connection from the built Linux image:
+
+```powershell
+docker compose run --rm h2orb python -m h2orb.check_connection
+```
+
+If AQUA uses an internal certificate authority, mount its PEM bundle read-only and configure the
+path inside the container:
+
+```yaml
+services:
+  h2orb:
+    environment:
+      ARB_AQUA_CA_BUNDLE: /certificates/company-ca.pem
+    volumes:
+      - ./certificates/company-ca.pem:/certificates/company-ca.pem:ro
+```
+
+TLS verification remains enabled. Do not add certificates, `.env`, passwords, or access tokens to
+the image.
+
+### Publish from Gitea to Docker Hub
+
+Gitea Actions verifies the Python project inside a Python 3.12 Docker build stage, then publishes the tested
+`linux/amd64` image as `hrabovszki/h2orb`. Configure these repository secrets in
+Gitea before running `.gitea/workflows/docker-publish.yaml`:
+
+- `DOCKERHUB_USERNAME`: Docker Hub account name
+- `DOCKERHUB_TOKEN`: Docker Hub personal access token with read, write, and delete permissions
+
+A push to `main` publishes the moving `main` tag and an immutable `sha-*` tag. A tag such as
+`v0.1.0` publishes `0.1.0`, `0.1`, `0`, and `latest`. Prerelease tags never move `latest`.
+After a successful image push, the workflow also synchronizes this README and the short description
+to the Docker Hub overview page.
+
+Never store the Docker Hub password or token in Git. Use a scoped access token instead of the
+account password.
+
+## License
+
+H2ORB is source-available under the
+[H2ORB Community License](LICENSE). Non-commercial use is permitted; commercial use
+requires a separate commercial license. This is not an OSI-approved open-source license.
+
+## Development checks
+
+```powershell
+ruff check .
+pytest
+```
+
+## Project structure
+
+```text
+src/h2orb/
+├── api/          # HTTP routes exposed to the browser
+├── aqua/         # AQUA REST API adapter
+├── domain/       # framework-independent models and rules
+├── services/     # application use cases
+├── static/       # browser assets
+└── templates/    # server-rendered HTML
+```
+
+Place the reviewed Swagger reference under `docs/aqua-api/`. Check it for internal host names,
+credentials, tokens, or other sensitive information before committing it.
+
+The current endpoint mapping is documented in `docs/aqua-api/endpoint-mapping.md`.