diff --git a/.github/workflows/beta-release.yaml b/.github/workflows/beta-release.yaml index e412b50..054b272 100644 --- a/.github/workflows/beta-release.yaml +++ b/.github/workflows/beta-release.yaml @@ -8,6 +8,8 @@ on: jobs: release-management: runs-on: ubuntu-latest + # Observed fleet-wide: n=26 runs, max 0.7 min; bounded loosely at 45 min because a spurious release failure is expensive + timeout-minutes: 45 steps: - name: Checkout Code diff --git a/.github/workflows/branch-protection.yml b/.github/workflows/branch-protection.yml new file mode 100644 index 0000000..7ef08ce --- /dev/null +++ b/.github/workflows/branch-protection.yml @@ -0,0 +1,11 @@ +name: Branch Protection + +on: + pull_request: + branches: [main, beta] + +permissions: {} + +jobs: + branch-protection: + uses: ConductionNL/.github/.github/workflows/branch-protection.yml@main diff --git a/.github/workflows/build-exapp.yaml b/.github/workflows/build-exapp.yaml new file mode 100644 index 0000000..fbf9930 --- /dev/null +++ b/.github/workflows/build-exapp.yaml @@ -0,0 +1,62 @@ +name: Build and Push ExApp Docker Image + +on: + push: + branches: + - main + - beta + tags: + - 'v*' + pull_request: + branches: + - main + +env: + REGISTRY: ghcr.io + IMAGE_NAME: conductionnl/opentalk-exapp + +jobs: + build: + runs-on: ubuntu-latest + # No successful runs observed yet (multi-arch docker build); bounded loosely at 30 min + timeout-minutes: 30 + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to Container Registry + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=raw,value=latest,enable={{is_default_branch}} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: . + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml new file mode 100644 index 0000000..1330004 --- /dev/null +++ b/.github/workflows/code-quality.yml @@ -0,0 +1,46 @@ +name: Code Quality + +on: + push: + branches: [main, beta, development, feature/**, bugfix/**, hotfix/**] + pull_request: + types: [opened, reopened] + branches: [main, beta, development] + workflow_dispatch: + +concurrency: + group: quality-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + +# Permission CEILING for the called quality pipeline. GitHub statically +# validates the called workflow's declared job permissions against this +# grant — even for jobs that are disabled — so it must cover the maximum +# any nested job declares: journeydoc-capture (contents+actions write), +# update-baseline / features-extract (contents write), and the Quality +# Report PR comment (issues / pull-requests write). +permissions: + contents: write + actions: write + issues: write + pull-requests: write + +jobs: + quality: + if: github.event_name != 'push' || github.event.created != true + uses: ConductionNL/.github/.github/workflows/quality.yml@main + with: + app-name: opentalk + # composer.json pins config.platform.php to 8.3 + php-version: "8.3" + # PHP-only ExApp: no package.json, so all npm-side checks are off + # (enable-npm gates the npm legs of security/license; enable-frontend + # gates Vue Quality and custom frontend checks). + enable-npm: false + enable-frontend: false + # The SBOM job invokes `composer CycloneDX:make-sbom`, which this repo + # does not ship — enable once cyclonedx/cyclonedx-php-composer is added + # to require-dev. + enable-sbom: false + # No openspec/specs and no docs/features.json yet — the features check + # would fail on every PR comparing "" against "[]". + enable-features-extract: false diff --git a/.github/workflows/pull-request-from-branch-check.yaml b/.github/workflows/pull-request-from-branch-check.yaml new file mode 100644 index 0000000..6fdef61 --- /dev/null +++ b/.github/workflows/pull-request-from-branch-check.yaml @@ -0,0 +1,34 @@ +name: Branch Protection + +on: + pull_request: + branches: + - main + - beta + +jobs: + check-branch: + runs-on: ubuntu-latest + # Observed fleet-wide: n=123 runs, max 0.1 min + timeout-minutes: 10 + steps: + - name: Check branch + run: | + TARGET="${{ github.base_ref }}" + SOURCE="${{ github.head_ref }}" + + if [[ "$TARGET" == "main" ]]; then + if [[ "$SOURCE" != "beta" ]] && ! [[ "$SOURCE" =~ ^hotfix ]]; then + echo "Error: Pull requests to main must come from 'beta' or a branch starting with 'hotfix'" + echo "Source branch: $SOURCE" + exit 1 + fi + elif [[ "$TARGET" == "beta" ]]; then + if [[ "$SOURCE" != "development" ]] && ! [[ "$SOURCE" =~ ^hotfix ]]; then + echo "Error: Pull requests to beta must come from 'development' or a branch starting with 'hotfix'" + echo "Source branch: $SOURCE" + exit 1 + fi + fi + + echo "Branch check passed: $SOURCE -> $TARGET" diff --git a/.github/workflows/pull-request-lint-check.yaml b/.github/workflows/pull-request-lint-check.yaml new file mode 100644 index 0000000..8fc0dfe --- /dev/null +++ b/.github/workflows/pull-request-lint-check.yaml @@ -0,0 +1,35 @@ +name: Lint Check + +on: + pull_request: + branches: + - development + - main + +jobs: + lint-check: + runs-on: ubuntu-latest + # Observed fleet-wide: n=176 runs, median 0.6 min, max 1.4 min + timeout-minutes: 15 + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Check for package.json + id: has_pkg + run: | + if [ -f package.json ]; then + echo "exists=true" >> "$GITHUB_OUTPUT" + else + echo "exists=false" >> "$GITHUB_OUTPUT" + echo "::notice::No package.json found at repo root; lint-check is a no-op for this repo." + fi + + - name: Install dependencies + if: steps.has_pkg.outputs.exists == 'true' + run: npm i + + - name: Linting + if: steps.has_pkg.outputs.exists == 'true' + run: npm run lint diff --git a/.github/workflows/push-development-to-beta.yaml b/.github/workflows/push-development-to-beta.yaml new file mode 100644 index 0000000..ed2628b --- /dev/null +++ b/.github/workflows/push-development-to-beta.yaml @@ -0,0 +1,46 @@ +name: Create PR to Beta + +permissions: + contents: write + pull-requests: write + +on: + push: + branches: + - development + +jobs: + create-pr: + runs-on: ubuntu-latest + # Observed fleet-wide: n=152 runs, max 5.6 min + timeout-minutes: 20 + steps: + - name: Checkout Code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Create or update PR to beta + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Check if beta branch exists + if ! git ls-remote --heads origin beta | grep -q beta; then + echo "Beta branch does not exist yet. Creating from development..." + git push origin origin/development:refs/heads/beta + fi + + # Check if a PR already exists + EXISTING_PR=$(gh pr list --base beta --head development --state open --json number --jq '.[0].number' || echo "") + + if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then + echo "PR #$EXISTING_PR already exists, it will auto-update with new commits" + else + gh pr create \ + --base beta \ + --head development \ + --title "Release: merge development into beta" \ + --body "Automated PR to sync development changes to beta for beta release. + + Merging this PR will trigger the beta release workflow." + fi diff --git a/.github/workflows/release-workflow.yaml b/.github/workflows/release-workflow.yaml index 2cdb0fa..ac46d78 100644 --- a/.github/workflows/release-workflow.yaml +++ b/.github/workflows/release-workflow.yaml @@ -15,6 +15,8 @@ on: jobs: release-management: runs-on: ubuntu-latest + # Observed fleet-wide: n=26 runs, max 0.7 min; bounded loosely at 45 min because a spurious release failure is expensive + timeout-minutes: 45 steps: - name: Checkout Code diff --git a/.github/workflows/unstable-release.yaml b/.github/workflows/unstable-release.yaml new file mode 100644 index 0000000..59b7a75 --- /dev/null +++ b/.github/workflows/unstable-release.yaml @@ -0,0 +1,179 @@ +name: Unstable Release + +on: + push: + branches: + - development + +jobs: + release-management: + runs-on: ubuntu-latest + # Observed fleet-wide: n=26 runs, max 0.7 min; bounded loosely at 45 min because a spurious release failure is expensive + timeout-minutes: 45 + steps: + + - name: Checkout Code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + ssh-key: ${{ secrets.DEPLOY_KEY }} + + - name: Set app env + run: | + echo "APP_NAME=${GITHUB_REPOSITORY##*/}" >> $GITHUB_ENV + + - name: Get current version and append unstable suffix + id: increment_version + run: | + git fetch origin main + main_version=$(git show origin/main:appinfo/info.xml | grep -oP '(?<=)[^<]+' || echo "") + current_version=$(grep -oP '(?<=)[^<]+' appinfo/info.xml || echo "") + + IFS='.' read -ra main_version_parts <<< "$main_version" + next_patch=$((main_version_parts[2] + 1)) + + unstable_counter=1 + if [[ $current_version =~ -unstable\.([0-9]+)$ ]]; then + current_patch=$(echo $current_version | grep -oP '^[0-9]+\.[0-9]+\.(\d+)' | cut -d. -f3) + if [ "$current_patch" -eq "$next_patch" ]; then + unstable_counter=$((BASH_REMATCH[1] + 1)) + fi + fi + + unstable_version="${main_version_parts[0]}.${main_version_parts[1]}.${next_patch}-unstable.${unstable_counter}" + + echo "NEW_VERSION=$unstable_version" >> $GITHUB_ENV + echo "new_version=$unstable_version" >> $GITHUB_OUTPUT + echo "Main version: $main_version" + echo "Current version: $current_version" + echo "Using unstable version: $unstable_version" + + - name: Update version in info.xml + run: | + sed -i "s|.*|${{ env.NEW_VERSION }}|" appinfo/info.xml + + - name: Commit version update + run: | + git config --local user.email "action@github.com" + git config --local user.name "GitHub Action" + + if git diff --quiet && git diff --cached --quiet; then + echo "No changes to commit" + else + git add appinfo/info.xml + git commit -m "Bump unstable version to ${{ env.NEW_VERSION }} [skip ci]" + git push + fi + + - name: Prepare Signing Certificate and Key + run: | + echo "${{ secrets.NEXTCLOUD_SIGNING_CERT }}" > signing-cert.crt + echo "${{ secrets.NEXTCLOUD_SIGNING_KEY }}" > signing-key.key + + - name: Install npm dependencies + uses: actions/setup-node@v3 + with: + node-version: '18.x' + + - name: Set up PHP and install extensions + uses: shivammathur/setup-php@v2 + with: + php-version: '8.2' + extensions: zip, gd + + - run: npm ci + - run: npm run build + - run: composer install --no-dev --optimize-autoloader --classmap-authoritative + + - name: Copy the package files into the package + run: | + mkdir -p package/${{ github.event.repository.name }} + rsync -av --progress \ + --exclude='/package' \ + --exclude='/.git' \ + --exclude='/.github' \ + --exclude='/.cursor' \ + --exclude='/.vscode' \ + --exclude='/node_modules' \ + --exclude='/src' \ + --exclude='/tests' \ + --exclude='/package.json' \ + --exclude='/package-lock.json' \ + --exclude='/composer.json' \ + --exclude='/composer.lock' \ + --exclude='/phpcs.xml' \ + --exclude='/phpmd.xml' \ + --exclude='/psalm.xml' \ + --exclude='/phpunit.xml' \ + --exclude='/.phpunit.cache' \ + --exclude='.phpunit.result.cache' \ + --exclude='/jest.config.js' \ + --exclude='/webpack.config.js' \ + --exclude='/tsconfig.json' \ + --exclude='/.babelrc' \ + --exclude='/.eslintrc.js' \ + --exclude='/.prettierrc' \ + --exclude='/stylelint.config.js' \ + --exclude='/.gitignore' \ + --exclude='/.gitattributes' \ + --exclude='/signing-key.key' \ + --exclude='/signing-cert.crt' \ + ./ package/${{ github.event.repository.name }}/ + + - name: Create Tarball + run: | + cd package && tar -czf ../nextcloud-release.tar.gz ${{ github.event.repository.name }} + + - name: Sign the TAR.GZ file with OpenSSL + run: | + openssl dgst -sha512 -sign signing-key.key nextcloud-release.tar.gz | openssl base64 -out nextcloud-release.signature + + - name: Upload tarball as artifact + uses: actions/upload-artifact@v4 + with: + name: nextcloud-release-${{ env.NEW_VERSION }} + path: | + nextcloud-release.tar.gz + nextcloud-release.signature + retention-days: 30 + + - name: Git Version + id: version + uses: codacy/git-version@2.7.1 + with: + release-branch: development + + - name: Upload Unstable Release + uses: ncipollo/release-action@v1.12.0 + with: + tag: v${{ env.NEW_VERSION }} + name: Unstable Release ${{ env.NEW_VERSION }} + draft: false + prerelease: true + skipIfReleaseExists: true + + - name: Attach tarball to GitHub release + uses: svenstaro/upload-release-action@v2 + with: + repo_token: ${{ secrets.GITHUB_TOKEN }} + file: nextcloud-release.tar.gz + asset_name: ${{ env.APP_NAME }}-${{ env.NEW_VERSION }}.tar.gz + tag: v${{ env.NEW_VERSION }} + overwrite: true + + - name: Upload app to Nextcloud appstore + uses: nextcloud-releases/nextcloud-appstore-push-action@a011fe619bcf6e77ddebc96f9908e1af4071b9c1 + with: + app_name: ${{ env.APP_NAME }} + appstore_token: ${{ secrets.NEXTCLOUD_APPSTORE_TOKEN }} + download_url: https://github.com/${{ github.repository }}/releases/download/v${{ env.NEW_VERSION }}/${{ env.APP_NAME }}-${{ env.NEW_VERSION }}.tar.gz + app_private_key: ${{ secrets.NEXTCLOUD_SIGNING_KEY }} + nightly: true + + - name: Verify release + run: | + echo "App version: ${{ env.NEW_VERSION }}" + echo "Tarball contents:" + tar -tvf nextcloud-release.tar.gz | head -50 + echo "info.xml contents:" + tar -xOf nextcloud-release.tar.gz ${{ env.APP_NAME }}/appinfo/info.xml diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..6cc8f68 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,78 @@ +# OpenTalk ExApp for Nextcloud +# Wraps OpenTalk video conferencing with AppAPI integration +# +# OpenTalk is a secure video conferencing solution that requires: +# - PostgreSQL database +# - Redis cache +# - Keycloak for authentication +# - LiveKit for WebRTC media +# +# See: https://docs.opentalk.eu/ + +FROM python:3.11-slim AS builder + +# Install build dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + && rm -rf /var/lib/apt/lists/* + +# Install Python dependencies for ExApp wrapper +WORKDIR /app +COPY requirements.txt . +RUN pip install --no-cache-dir --target=/app/deps -r requirements.txt + +# Get OpenTalk controller from upstream image +FROM registry.opencode.de/opentalk/controller:v0.31.0-3 AS opentalk-base + +# Get OpenTalk web frontend from upstream image +FROM registry.opencode.de/opentalk/web-frontend:v2.6.2-1 AS frontend-base + +# Production image +FROM python:3.11-slim + +# Install runtime dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + curl \ + tini \ + libpq5 \ + ca-certificates \ + && rm -rf /var/lib/apt/lists/* + +# Copy OpenTalk controller binary from upstream +COPY --from=opentalk-base /controller/opentalk-controller /usr/local/bin/opentalk-controller + +# Copy OpenTalk web frontend static files +COPY --from=frontend-base /usr/share/nginx/html /app/frontend + +# Copy Python dependencies +COPY --from=builder /app/deps /usr/local/lib/python3.11/site-packages + +# Set up ExApp wrapper +WORKDIR /app +COPY ex_app /app/ex_app +COPY img/ /app/ex_app/img/ +COPY entrypoint.sh /entrypoint.sh +RUN chmod +x /entrypoint.sh + +# Create config and data directories +RUN mkdir -p /etc/opentalk /var/lib/opentalk +COPY controller.toml /etc/opentalk/controller.toml + +# Environment variables (set by AppAPI) +ENV APP_HOST=0.0.0.0 +ENV APP_PORT=23000 +ENV PYTHONUNBUFFERED=1 + +# OpenTalk configuration +# All service config (oidc, livekit, database, redis) is in controller.toml +# Env vars with OPENTALK_CTRL_ prefix override entire TOML sections, so avoid setting them here +ENV OPENTALK_PORT=11311 + +# Expose ports: 9000 for AppAPI, 11311 for OpenTalk controller +EXPOSE 9000 11311 + +# Health check - just verify the wrapper is responding (any status is ok during init) +HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \ + CMD curl -s http://localhost:${APP_PORT:-9000}/heartbeat | grep -q status || exit 1 + +ENTRYPOINT ["/usr/bin/tini", "--", "/entrypoint.sh"] diff --git a/LICENSE b/LICENSE index 261eeb9..6d8cea4 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,190 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +EUROPEAN UNION PUBLIC LICENCE v. 1.2 +EUPL © the European Union 2007, 2016 + +This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined below) which is provided under the +terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such +use is covered by a right of the copyright holder of the Work). +The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following +notice immediately following the copyright notice for the Work: + Licensed under the EUPL +or has expressed by any other means his willingness to license under the EUPL. + +1.Definitions +In this Licence, the following terms have the following meaning: +— ‘The Licence’:this Licence. +— ‘The Original Work’:the work or software distributed or communicated by the Licensor under this Licence, available +as Source Code and also as Executable Code as the case may be. +— ‘Derivative Works’:the works or software that could be created by the Licensee, based upon the Original Work or +modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work +required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in +the country mentioned in Article 15. +— ‘The Work’:the Original Work or its Derivative Works. +— ‘The Source Code’:the human-readable form of the Work which is the most convenient for people to study and +modify. +— ‘The Executable Code’:any code which has generally been compiled and which is meant to be interpreted by +a computer as a program. +— ‘The Licensor’:the natural or legal person that distributes or communicates the Work under the Licence. +— ‘Contributor(s)’:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to +the creation of a Derivative Work. +— ‘The Licensee’ or ‘You’:any natural or legal person who makes any usage of the Work under the terms of the +Licence. +— ‘Distribution’ or ‘Communication’:any act of selling, giving, lending, renting, distributing, communicating, +transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential +functionalities at the disposal of any other natural or legal person. + +2.Scope of the rights granted by the Licence +The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for +the duration of copyright vested in the Original Work: +— use the Work in any circumstance and for all usage, +— reproduce the Work, +— modify the Work, and make Derivative Works based upon the Work, +— communicate to the public, including the right to make available or display the Work or copies thereof to the public +and perform publicly, as the case may be, the Work, +— distribute the Work or copies thereof, +— lend and rent the Work or copies thereof, +— sublicense rights in the Work or copies thereof. +Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the +applicable law permits so. +In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed +by law in order to make effective the licence of the economic rights here above listed. +The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the +extent necessary to make use of the rights granted on the Work under this Licence. + +3.Communication of the Source Code +The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as +Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with +each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to +the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to +distribute or communicate the Work. + +4.Limitations on copyright +Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the +exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations +thereto. + +5.Obligations of the Licensee +The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those +obligations are the following: + +Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to +the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the +Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work +to carry prominent notices stating that the Work has been modified and the date of modification. + +Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this +Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless +the Original Work is expressly distributed only under this version of the Licence — for example by communicating +‘EUPL v. 1.2 only’. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the +Work or Derivative Work that alter or restrict the terms of the Licence. + +Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both +the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done +under the terms of this Compatible Licence. For the sake of this clause, ‘Compatible Licence’ refers to the licences listed +in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with +his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail. + +Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide +a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available +for as long as the Licensee continues to distribute or communicate the Work. +Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names +of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and +reproducing the content of the copyright notice. + +6.Chain of Authorship +The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or +licensed to him/her and that he/she has the power and authority to grant the Licence. +Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or +licensed to him/her and that he/she has the power and authority to grant the Licence. +Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions +to the Work, under the terms of this Licence. + +7.Disclaimer of Warranty +The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work +and may therefore contain defects or ‘bugs’ inherent to this type of development. +For the above reason, the Work is provided under the Licence on an ‘as is’ basis and without warranties of any kind +concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or +errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this +Licence. +This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work. + +8.Disclaimer of Liability +Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be +liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the +Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss +of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However, +the Licensor will be liable under statutory product liability laws as far such laws apply to the Work. + +9.Additional agreements +While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services +consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole +responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify, +defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by +the fact You have accepted any warranty or additional liability. + +10.Acceptance of the Licence +The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ placed under the bottom of a window +displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of +applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms +and conditions. +Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You +by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution +or Communication by You of the Work or copies thereof. + +11.Information to the public +In case of any Distribution or Communication of the Work by means of electronic communication by You (for example, +by offering to download the Work from a remote location) the distribution channel or media (for example, a website) +must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence +and the way it may be accessible, concluded, stored and reproduced by the Licensee. + +12.Termination of the Licence +The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms +of the Licence. +Such a termination will not terminate the licences of any person who has received the Work from the Licensee under +the Licence, provided such persons remain in full compliance with the Licence. + +13.Miscellaneous +Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the +Work. +If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or +enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid +and enforceable. +The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of +the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence. +New versions of the Licence will be published with a unique version number. +All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take +advantage of the linguistic version of their choice. + +14.Jurisdiction +Without prejudice to specific agreement between parties, +— any litigation resulting from the interpretation of this License, arising between the European Union institutions, +bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice +of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union, +— any litigation arising between other parties and resulting from the interpretation of this License, will be subject to +the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business. + +15.Applicable Law +Without prejudice to specific agreement between parties, +— this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat, +resides or has his registered office, +— this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside +a European Union Member State. + + + Appendix + +‘Compatible Licences’ according to Article 5 EUPL are: +— GNU General Public License (GPL) v. 2, v. 3 +— GNU Affero General Public License (AGPL) v. 3 +— Open Software License (OSL) v. 2.1, v. 3.0 +— Eclipse Public License (EPL) v. 1.0 +— CeCILL v. 2.0, v. 2.1 +— Mozilla Public Licence (MPL) v. 2 +— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3 +— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software +— European Union Public Licence (EUPL) v. 1.1, v. 1.2 +— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+). + +The European Commission may update this Appendix to later versions of the above licences without producing +a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the +covered Source Code from exclusive appropriation. +All other changes or additions to this Appendix require the production of a new EUPL version. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..73eb358 --- /dev/null +++ b/Makefile @@ -0,0 +1,24 @@ +.PHONY: build push test clean + +APP_ID = opentalk +REGISTRY = ghcr.io +IMAGE = conductionnl/$(APP_ID)-exapp +VERSION ?= latest + +build: + docker build -t $(REGISTRY)/$(IMAGE):$(VERSION) . + +push: build + docker push $(REGISTRY)/$(IMAGE):$(VERSION) + +test: + docker run --rm -it \ + -e APP_ID=$(APP_ID) \ + -e APP_VERSION=0.1.0 \ + -e APP_SECRET=test \ + -e NEXTCLOUD_URL=http://localhost \ + -p 9000:9000 \ + $(REGISTRY)/$(IMAGE):$(VERSION) + +clean: + docker rmi $(REGISTRY)/$(IMAGE):$(VERSION) || true diff --git a/README.md b/README.md index 8fb0739..9fecd34 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,339 @@ -# OpenTalk for Nextcloud +

+ OpenTalk logo +

-Nextcloud integration app for [OpenTalk](https://opentalk.eu/) video conferencing. +

OpenTalk

-## About This App +

+ GDPR-compliant video conferencing for Nextcloud -- secure meetings, screen sharing, and end-to-end encryption via the Nextcloud AppAPI +

-This is a **Nextcloud wrapper app** that provides integration between Nextcloud and an external OpenTalk server. It does not contain the OpenTalk video conferencing platform itself - it connects your Nextcloud instance to a running OpenTalk deployment. +

+ Latest release + License +

-**For OpenTalk server documentation, see:** https://docs.opentalk.eu/ +--- + +> **IMPORTANT DISCLAIMER** +> +> This repository contains only a **Nextcloud ExApp wrapper** for [OpenTalk](https://opentalk.eu/), developed and maintained by [Conduction B.V.](https://conduction.nl). The wrapper packages the upstream OpenTalk controller as a containerized application managed by Nextcloud's AppAPI. +> +> **OpenTalk itself is developed by [OpenTalk GmbH](https://opentalk.eu/).** +> +> Conduction does **NOT** provide: +> - Support, SLAs, or guarantees for the OpenTalk platform +> - Licensing or pricing for OpenTalk +> - Bug fixes or feature development for the upstream OpenTalk controller +> - Any warranty regarding OpenTalk's functionality or fitness for purpose +> +> **For OpenTalk support, licensing, pricing, and services, contact [OpenTalk GmbH](https://opentalk.eu/) directly.** +> +> For issues specific to the **Nextcloud wrapper** (AppAPI integration, container lifecycle, proxy layer), you may open an issue on [this repository](https://github.com/ConductionNL/opentalk/issues). + +## What is OpenTalk? + +[OpenTalk](https://opentalk.eu/) is a secure, open-source video conferencing platform developed in Germany by [OpenTalk GmbH](https://opentalk.eu/) with a strong focus on data protection and GDPR compliance. It is designed as a sovereign alternative to commercial cloud-based video conferencing solutions, keeping all communication data under your own control. + +Key capabilities of the OpenTalk platform: + +- **Secure Video and Audio Conferencing** -- High-quality WebRTC-based meetings via LiveKit +- **Screen Sharing** -- Present your screen or individual application windows +- **End-to-End Encryption** -- Optional E2EE for maximum confidentiality +- **OIDC / Keycloak Authentication** -- Enterprise single sign-on integration +- **Moderation Tools** -- Meeting controls, waiting rooms, and participant management +- **Recording** -- Server-side meeting recording (when configured) +- **Data Sovereignty** -- Self-hosted, no data leaves your infrastructure + +For full documentation, see [docs.opentalk.eu](https://docs.opentalk.eu/). ## What This App Does -- Adds an OpenTalk entry to the Nextcloud navigation -- Provides a UI within Nextcloud for starting and joining video conferences -- Integrates OpenTalk authentication with Nextcloud users -- Allows inviting Nextcloud users to OpenTalk conferences +This Nextcloud ExApp (External Application) wraps the upstream OpenTalk controller in a container that Nextcloud manages through the [AppAPI](https://github.com/nextcloud/app_api) framework. Specifically, this wrapper: + +- Packages the OpenTalk controller binary from the official upstream image +- Implements AppAPI lifecycle endpoints (`/heartbeat`, `/init`, `/enabled`) +- Starts and manages the OpenTalk controller process inside the container +- Proxies all requests from Nextcloud to the OpenTalk controller +- Provides seamless **iframe-embedded** experience inside Nextcloud (no new tabs) +- Handles **automatic Keycloak SSO** via the Keycloak ExApp -- users are pre-authenticated without browser-side OIDC redirects +- Reports health status back to Nextcloud + +

+ OpenTalk running inside Nextcloud as an embedded iframe +
+ OpenTalk dashboard running seamlessly inside a Nextcloud iframe +

+ +This app does **not** modify or extend the OpenTalk platform itself. It only provides the integration layer between Nextcloud and the upstream OpenTalk controller. ## Requirements -- Nextcloud 28 or higher -- PHP 8.0 or higher -- A running [OpenTalk server](https://opentalk.eu/) instance +| Dependency | Version | Notes | +|-----------|---------|-------| +| Nextcloud | 30 -- 33 | | +| [AppAPI](https://apps.nextcloud.com/apps/app_api) | latest | Must be installed and configured with a deploy daemon | +| Docker | -- | Required for ExApp container deployment | +| PostgreSQL | 14+ | OpenTalk database backend | +| Redis | 6+ | Caching and session management | +| [Keycloak ExApp](https://github.com/ConductionNL/keycloak-nextcloud) | latest | Shared OIDC provider -- syncs Nextcloud users to Keycloak | +| LiveKit | 1.x | WebRTC media server for video/audio | ## Installation -### From the Nextcloud App Store +### Via Nextcloud App Store -Search for "OpenTalk" in your Nextcloud app store and click Install. +1. Ensure **AppAPI** is installed and configured with a deploy daemon +2. Install the **Keycloak ExApp** first (required for authentication) +3. Search for **OpenTalk** in the Nextcloud External Apps section +4. Click **Install** -- Nextcloud will pull and start the container automatically -### Manual Installation +### Manual Registration -1. Download the latest release from [GitHub Releases](https://github.com/ConductionNL/opentalk/releases) -2. Extract to your Nextcloud `apps` or `custom_apps` directory -3. Enable the app: `occ app:enable opentalk` +```bash +# Register the ExApp with AppAPI +docker exec -u www-data nextcloud php occ app_api:app:register \ + opentalk your_daemon_name \ + --info-xml /path/to/appinfo/info.xml \ + --force-scopes + +# Enable the ExApp +docker exec -u www-data nextcloud php occ app_api:app:enable opentalk +``` ## Configuration -After installation, configure the OpenTalk server URL in the Nextcloud admin settings. +Configure via Nextcloud Admin Settings or container environment variables. All environment variables are defined in `appinfo/info.xml` and passed through by AppAPI. -## Development +### OpenTalk Controller -```bash -# Install dependencies -composer install -npm install +| Variable | Description | +|----------|-------------| +| `OPENTALK_CTRL_DATABASE__URL` | PostgreSQL connection string (e.g., `postgres://user:pass@host:5432/opentalk`) | +| `OPENTALK_CTRL_REDIS__URL` | Redis connection string (e.g., `redis://localhost:6379/`) | +| `OPENTALK_CTRL_OIDC__AUTHORITY` | Keycloak OIDC provider URL (auto-configured when using Keycloak ExApp) | +| `OPENTALK_CTRL_LIVEKIT__SERVICE_URL` | LiveKit WebRTC server URL | +| `OPENTALK_CTRL_LIVEKIT__API_KEY` | LiveKit API key | +| `OPENTALK_CTRL_LIVEKIT__API_SECRET` | LiveKit API secret | + +### Keycloak Integration -# Build frontend -npm run build +| Variable | Description | +|----------|-------------| +| `KEYCLOAK_EXAPP_URL` | URL of the Keycloak ExApp container (e.g., `http://keycloak-container:23002`) | +| `KEYCLOAK_API_SECRET` | Shared secret for ExApp-to-ExApp auth (must match Keycloak ExApp) | +| `KEYCLOAK_REALM` | Keycloak realm name (default: `commonground`) | +| `KEYCLOAK_BROWSER_URL` | Browser-accessible Keycloak URL for OIDC config (default: `http://localhost:8180`) | -# Watch for changes -npm run watch +## Architecture -# Run linting -composer phpcs -npm run lint +### Component Overview + +The OpenTalk ExApp orchestrates seven components to deliver embedded video conferencing inside Nextcloud: + +| Component | Image / Technology | Role | Port | +|-----------|-------------------|------|------| +| **FastAPI Wrapper** | Python / nc_py_api | AppAPI lifecycle, auth proxy, frontend serving | 23005 (ExApp) | +| **OpenTalk Controller** | `registry.opencode.de/opentalk/controller` | Meeting management, signaling, REST API | 11311 (internal) | +| **OpenTalk Frontend** | React SPA (bundled) | Meeting UI, dashboard, settings | Served by wrapper | +| **Keycloak ExApp** | `ghcr.io/conductionnl/keycloak-nextcloud` | OIDC identity provider, user sync from Nextcloud | 23002 (ExApp), 8080 (KC) | +| **LiveKit** | `livekit/livekit-server` | WebRTC SFU -- routes video/audio/screen streams between participants | 7880 (API), 7881 (WS) | +| **Redis** | `redis:7-alpine` | Session cache, pub/sub for controller events | 6379 | +| **MinIO** | `minio/minio` | S3-compatible object storage for file uploads and meeting assets | 9000 | +| **PostgreSQL** | Shared with Nextcloud | Persistent storage for meetings, users, recordings | 5432 | + +### Infrastructure Diagram + +```mermaid +graph TB + subgraph "Browser" + NC["Nextcloud UI"] + IF["OpenTalk iframe"] + end + + subgraph "Nextcloud Server" + AA["AppAPI Proxy
Adds CSP nonce + auth headers"] + end + + subgraph "OpenTalk ExApp Container" + FW["FastAPI Wrapper
Port 23005
Auth proxy, frontend serving,
AppAPI lifecycle"] + OT["OpenTalk Controller
Port 11311
Meeting signaling, REST API,
room management"] + TCP["TCP Proxy
localhost:8180 → keycloak:8080
OIDC issuer URL consistency"] + FE["OpenTalk Frontend
React SPA
Meeting UI, dashboard"] + end + + subgraph "Supporting Services" + KC["Keycloak ExApp
Port 23002 / 8080
OIDC provider, user sync,
token API"] + LK["LiveKit Server
Port 7880 / 7881
WebRTC SFU for
video/audio streams"] + RD["Redis
Port 6379
Session cache,
pub/sub events"] + MN["MinIO
Port 9000
Object storage for
file uploads"] + PG["PostgreSQL
Port 5432
Meetings, users,
recordings"] + end + + NC -->|"iframe src"| AA + AA -->|"AUTHORIZATION-APP-API"| FW + FW -->|"Serves static files"| FE + FW -->|"Proxies /v1/* API calls"| OT + FW -->|"GET /api/auth/token"| KC + IF -->|"WebSocket wss://"| LK + OT -->|"Room signaling"| LK + OT -->|"Session data"| RD + OT -->|"File uploads"| MN + OT -->|"Meetings DB"| PG + OT -->|"Token validation"| TCP + TCP -->|"OIDC introspection"| KC + KC -->|"Identity DB"| PG + + style FW fill:#4a9,stroke:#333,color:#fff + style OT fill:#369,stroke:#333,color:#fff + style KC fill:#c63,stroke:#333,color:#fff + style LK fill:#96c,stroke:#333,color:#fff + style RD fill:#d44,stroke:#333,color:#fff + style MN fill:#e80,stroke:#333,color:#fff + style PG fill:#36a,stroke:#333,color:#fff ``` -## Related Projects +### Component Details + +#### FastAPI Wrapper (`ex_app/lib/main.py`) + +The Python wrapper is the entry point for all Nextcloud communication. It implements the AppAPI contract and adds the authentication proxy layer. + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/heartbeat` | GET | AppAPI health check -- probes the controller at `localhost:11311` | +| `/init` | POST | Starts controller, rewrites frontend paths, registers top menu | +| `/enabled` | PUT | Starts or stops the controller process | +| `/api/auth/token` | GET | Proxies token request to Keycloak ExApp (container-to-container) | +| `/config.js` | GET | Generates runtime frontend config (OIDC authority, base URL) | +| `/js/opentalk-iframe-loader.js` | GET | Iframe loader injected into the Nextcloud page | +| `/v1/*` | ALL | Proxied to the OpenTalk controller | +| `/*` | GET | Serves static frontend files (SPA fallback to `index.html`) | + +#### OpenTalk Controller + +The upstream [OpenTalk controller](https://gitlab.opencode.de/opentalk/controller) binary runs as a child process managed by the wrapper. It handles all meeting logic, WebRTC signaling via LiveKit, and exposes the REST API at port 11311. -| Project | Description | Links | -|---------|-------------|-------| -| **OpenTalk** | Video conferencing platform | [Website](https://opentalk.eu/) / [Docs](https://docs.opentalk.eu/) / [GitLab](https://gitlab.opencode.de/opentalk) | -| **Open Register** | Nextcloud register management | [GitHub](https://github.com/ConductionNL/openregister) | +Configuration lives in `controller.toml` with sections for: +- **`[database]`** -- PostgreSQL connection for meeting persistence +- **`[redis]`** -- Session cache and event pub/sub +- **`[oidc]`** -- Keycloak authority URL (overridden at runtime via TCP proxy) +- **`[oidc.frontend]`** -- Public OIDC client (`opentalk`) for browser flows +- **`[oidc.controller]`** -- Confidential OIDC client (`opentalk-controller`) for server-side token introspection +- **`[livekit]`** -- WebRTC media server connection (public + service URLs) +- **`[minio]`** -- S3 object storage for file uploads + +#### LiveKit Server + +[LiveKit](https://livekit.io/) is an open-source WebRTC Selective Forwarding Unit (SFU). It routes video, audio, and screen-sharing streams between meeting participants without mixing -- enabling low-latency, high-quality conferencing. + +- **Port 7880** -- HTTP API used by the OpenTalk controller for room management +- **Port 7881** -- WebSocket endpoint where browser clients connect for media streams +- **Dev mode** (`--dev`) -- Runs with simplified config; API key `devkey` / secret `secret` + +#### Redis + +Shared Redis instance (`redis:7-alpine`) used by the OpenTalk controller for: +- Session caching and token storage +- Pub/sub event delivery between controller instances +- Also shared with other Common Ground ExApps (OpenZaak, OpenKlant) + +#### MinIO + +S3-compatible object storage (`minio/minio`) for OpenTalk file uploads and meeting assets (recordings, shared files). Accessible at `http://openregister-exapp-minio:9000` with default credentials `minioadmin/minioadmin`. + +#### TCP Proxy (OIDC Issuer Consistency) + +A lightweight TCP proxy thread inside the container forwards `localhost:8180` to `keycloak:8080`. This ensures the OIDC issuer URL (`http://localhost:8180/realms/commonground`) is identical in: +- Keycloak-issued JWT tokens (`iss` claim) +- The OpenTalk controller's OIDC authority configuration +- The browser's OIDC discovery endpoint + +Without this proxy, issuer mismatches would cause token validation failures. + +### Authentication Flow + +The OpenTalk ExApp uses a **server-side token pre-loading** strategy to provide seamless SSO inside a Nextcloud iframe, bypassing browser-side OIDC redirects that CSP would block: + +1. **User clicks OpenTalk** in the Nextcloud top menu +2. Nextcloud loads the **iframe loader script** which creates an iframe pointing to the ExApp +3. The ExApp serves `index.html` with an injected **bootstrap script** (CSP nonce-safe) +4. The bootstrap script calls **`/api/auth/token`** via synchronous XHR (same-origin, Nextcloud session cookie provides auth) +5. The token endpoint calls the **Keycloak ExApp** container-to-container with a shared secret +6. The Keycloak ExApp uses the **direct access grant** to get a Keycloak token for the Nextcloud user +7. Tokens (`access_token`, `refresh_token`, `id_token`) are stored in **localStorage** before the React app initializes +8. The bootstrap also calls **`POST /v1/auth/login`** on the OpenTalk controller for server-side session setup +9. When the React app starts, `hasActiveSession()` finds valid tokens and the user is immediately **authenticated** + +```mermaid +sequenceDiagram + participant B as Browser (iframe) + participant NC as Nextcloud AppAPI + participant FW as FastAPI Wrapper + participant KC as Keycloak ExApp + participant KS as Keycloak Server + participant OT as OpenTalk Controller + + B->>NC: GET /proxy/opentalk/ + NC->>FW: GET / (+ auth headers) + FW-->>NC: index.html + bootstrap script (nonce-safe) + NC-->>B: HTML with CSP nonce + + Note over B: Bootstrap script runs (sync XHR) + + B->>NC: XHR GET /proxy/opentalk/api/auth/token + NC->>FW: GET /api/auth/token (+ auth headers) + FW->>KC: POST /api/token (X-API-SECRET, X-NC-USER-ID) + KC->>KS: POST /token (grant_type=password) + KS-->>KC: access_token, refresh_token, id_token + KC-->>FW: tokens + FW-->>NC: tokens + NC-->>B: tokens + + Note over B: localStorage.setItem("access_token", ...) + Note over B: localStorage.setItem("refresh_token", ...) + Note over B: localStorage.setItem("id_token", ...) + + B->>NC: POST /proxy/opentalk/v1/auth/login {id_token} + NC->>FW: POST /v1/auth/login + FW->>OT: POST /v1/auth/login + OT-->>FW: session created + FW-->>NC: OK + NC-->>B: OK + + Note over B: React app initializes + Note over B: hasActiveSession() = true + Note over B: Dashboard renders +``` + +### Key Design Decisions + +- **Synchronous XHR** for the bootstrap (not async `fetch`) to ensure tokens are in localStorage before the React app's Redux store initializes +- **CSP nonce compliance**: Nextcloud's AppAPI proxy auto-adds nonce attributes to all `""" + html = html.replace( + f' diff --git a/src/main.js b/src/main.js deleted file mode 100644 index 41d545d..0000000 --- a/src/main.js +++ /dev/null @@ -1,12 +0,0 @@ -import Vue from 'vue' -import App from './App.vue' - -Vue.mixin({ methods: { t, n } }) - -const appElement = document.getElementById('opentalk') -if (appElement) { - new Vue({ - el: appElement, - render: h => h(App), - }) -} diff --git a/templates/index.php b/templates/index.php deleted file mode 100644 index a0a8889..0000000 --- a/templates/index.php +++ /dev/null @@ -1,12 +0,0 @@ - - -
-
-
diff --git a/webpack.config.js b/webpack.config.js deleted file mode 100644 index 8fd713e..0000000 --- a/webpack.config.js +++ /dev/null @@ -1,21 +0,0 @@ -const path = require('path') -const webpackConfig = require('@nextcloud/webpack-vue-config') - -const buildMode = process.env.NODE_ENV -const isDev = buildMode === 'development' -webpackConfig.devtool = isDev ? 'cheap-source-map' : 'source-map' - -webpackConfig.stats = { - colors: true, - modules: false, -} - -const appId = 'opentalk' -webpackConfig.entry = { - main: { - import: path.join(__dirname, 'src', 'main.js'), - filename: appId + '-main.js', - }, -} - -module.exports = webpackConfig