From 1af90d23e2ecf05927db7259c23f846b8511a129 Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Thu, 7 May 2026 20:22:13 +0000 Subject: [PATCH] docs: refresh readme and legal info --- license | 21 ++++++++++ readme.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 121 insertions(+), 17 deletions(-) create mode 100644 license diff --git a/license b/license new file mode 100644 index 0000000..6f1b27d --- /dev/null +++ b/license @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) Task Venture Capital GmbH + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/readme.md b/readme.md index 2e9c19f..b114d32 100644 --- a/readme.md +++ b/readme.md @@ -1,27 +1,59 @@ -# serve.zone Testing +# @serve.zone/testing -Whole-system integration scenarios for serve.zone components. +The serve.zone integration test harness exercises real cross-repository behavior that is too stateful for individual package tests: Docker Swarm reconciliation, Cloudly registry flows, Coreflow/Coretraffic routing, Corestore volume and backup APIs, Onebox service lifecycle, App Store templates, and BaseOS image pipeline work. -Fast package tests stay in each component repo. This repo is for stateful cross-component tests that need Docker, Swarm, Cloudly, Coreflow, registry behavior, and later Coretraffic routing. +## Issue Reporting and Security + +For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. + +## Purpose + +Component repositories keep their fast unit and package tests locally. This repository is for end-to-end smoke scenarios that intentionally cross package boundaries and touch real infrastructure. Most scenarios allocate temporary ports and write under `testing/.nogit/`, but they also create Docker services, networks, containers, images, or local artifacts during execution. ## Scenarios -- `registry-deploy-on-push`: starts Cloudly with isolated Mongo/S3 helpers, connects Coreflow as a cluster, pushes a Docker image to Cloudly's built-in registry, verifies Cloudly metadata updates, verifies Coreflow creates the workload service, verifies Coretraffic HTTPS routing, then pushes the same tag again and verifies service recreation and routing through the new digest. -- `corestore-volume-driver`: starts Corestore with isolated ports and a temporary Docker plugin socket, verifies the VolumeDriver protocol, snapshots/restores a managed volume through `containerarchive`, checks Coreflow's generated corestore volume mount specs, and verifies Coreflow backup/restore orchestration for volume, database, and object-storage snapshots. -- `onebox-basic-lifecycle`: starts Onebox in dev mode, verifies core services, deploys a workload, checks HTTP plus HTTPS routing through ingress, removes the workload, and verifies cleanup. +| Scenario | Command | What it validates | +| --- | --- | --- | +| `corestore-volume-driver` | `pnpm scenario:corestore-volume-driver` | Corestore control API, Docker VolumeDriver protocol, snapshot/restore through `containerarchive`, Coreflow volume mount generation, backup/restore orchestration, and remote replication against a fake Cloudly API. | +| `registry-deploy-on-push` | `pnpm scenario:registry-deploy-on-push` | Cloudly startup with isolated Mongo/S3 helpers, cluster and registry setup, Docker image push, Cloudly metadata update, Coreflow workload provisioning, Coretraffic HTTPS routing, and same-tag redeploy after digest changes. | +| `onebox-basic-lifecycle` | `pnpm scenario:onebox-basic-lifecycle` | Onebox startup in dev mode, SmartProxy ingress, local registry status, workload deploy/remove, HTTP route check, and HTTPS route check with a temporary certificate. | +| `onebox-backup-restore` | `pnpm scenario:onebox-backup-restore` | Onebox service backup creation through ContainerArchive, image-in-backup metadata, clone restore, environment preservation, and cleanup. | +| `onebox-cloudly-appstore-worker` | `pnpm scenario:onebox-cloudly-appstore-worker` | Cloudly App Store template installation through Onebox, MongoDB and MinIO platform resources, worker bootstrap route availability, backup without app image, and platform-resource restore. | +| `baseos-image-pipeline` | `pnpm scenario:baseos-image-pipeline` | CoreBuild BaseOS raw-image job API, S3 artifact upload, Raspberry Pi image customization, WiFi config, SSH key injection, and baserunner environment generation. | -## Host Run +`pnpm test` runs the core host scenarios. `pnpm test:full` adds the Cloudly App Store worker scenario. The BaseOS image pipeline is intentionally separate because it needs image tooling such as `qemu-img`, `guestfish`, and `xz`. -Requires Docker with Swarm already active. +## Host Requirements + +- Node.js 22-compatible runtime and `pnpm`. +- Deno for Onebox and BaseOS-related scenarios. +- Docker with Swarm already active for Docker-backed scenarios. +- `openssl` and `curl` for routing and certificate smoke checks. +- `qemu-img`, `guestfish`, and `xz` for `baseos-image-pipeline`. + +Bootstrap package dependencies across the workspace before running scenarios: ```bash pnpm bootstrap:components +``` + +Run the default scenario set: + +```bash pnpm test ``` -## Vagrant Run +Run a single scenario: -Requires Vagrant plus a provider on the host. The Vagrant VM installs Docker, Node.js, pnpm, initializes Docker Swarm, and mounts the full `serve.zone` directory at `/serve.zone`. +```bash +pnpm scenario:corestore-volume-driver +pnpm scenario:registry-deploy-on-push +pnpm scenario:onebox-basic-lifecycle +``` + +## Vagrant Runner + +The included `Vagrantfile` creates an Ubuntu 24.04 VM, mounts the full serve.zone workspace at `/serve.zone`, installs Docker, Node.js, Deno, pnpm, image tooling, and initializes Docker Swarm. ```bash pnpm vagrant:up @@ -29,14 +61,65 @@ pnpm vagrant:test pnpm vagrant:destroy ``` -Provider options: +Additional Vagrant commands: -- VirtualBox: install `vagrant` and `virtualbox` on the host. -- libvirt: install `vagrant`, `libvirt`, and the `vagrant-libvirt` plugin on the host. +```bash +pnpm vagrant:test:baseos +pnpm vagrant:test:full +``` Useful environment variables: -- `SERVEZONE_ROOT`: host path mounted as `/serve.zone`. -- `SERVEZONE_VAGRANT_BOX`: defaults to `bento/ubuntu-24.04`. -- `SERVEZONE_VAGRANT_CPUS`: defaults to `4`. -- `SERVEZONE_VAGRANT_MEMORY`: defaults to `8192`. +| Variable | Default | Purpose | +| --- | --- | --- | +| `SERVEZONE_ROOT` | parent of `testing/` | Workspace path mounted into the VM. | +| `SERVEZONE_VAGRANT_BOX` | `bento/ubuntu-24.04` | Base VM image. | +| `SERVEZONE_VAGRANT_CPUS` | `4` | VM CPU count. | +| `SERVEZONE_VAGRANT_MEMORY` | `8192` | VM memory in MB. | +| `SERVEZONE_KEEP_TEST_ARTIFACTS` | unset | Keeps BaseOS image pipeline artifacts when set. | + +## Safety Notes + +- Scenarios refuse to overwrite known pre-existing services such as `onebox-smartproxy` when that would risk clobbering a developer's running environment. +- Docker artifacts are labeled or named with scenario-specific smoke IDs where practical, then cleaned up in `finally` blocks. +- Several scenarios change process environment variables temporarily and restore them afterward. +- The harness is intentionally integration-heavy. A failing scenario often prints Docker service logs, task state, route responses, or artifact details before rethrowing. + +## Project Map + +```text +testing/ +├── package.json +├── tsconfig.json +├── Vagrantfile +├── scripts/ +│ └── provision-vm.sh +└── scenarios/ + ├── baseos-image-pipeline/ + ├── corestore-volume-driver/ + ├── onebox-backup-restore/ + ├── onebox-basic-lifecycle/ + ├── onebox-cloudly-appstore-worker/ + └── registry-deploy-on-push/ +``` + +## License and Legal Information + +This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file. + +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. + +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein. + +Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar. + +### Company Information + +Task Venture Capital GmbH +Registered at District Court Bremen HRB 35230 HB, Germany + +For any legal inquiries or further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.