qbit-printing/dev

Local Docker development

Use this repository to start a separate QQQ application or run synthetic printing checks. Nothing imports an installed connector's pairing, accesses physical printers, or needs a cloud account. Docker Compose and PowerShell 7.4+ are required; Git identifies the checkout. Docker must support Linux/amd64 containers. The first build downloads pinned public images, Maven dependencies and the verified Windows Core source archive. Java and .NET run inside Docker; neither host SDK is required.

Start, test and stop

From the repository root, the default command runs 65 S3 checks and 40 network jobs, saves protected reports, and removes its containers and synthetic volumes:

pwsh ./dev/Invoke-Dev.ps1 -Action Test

For a persistent development application, start it and keep the state-directory path printed by the command:

pwsh ./dev/Invoke-Dev.ps1 -Action Start
pwsh ./dev/Invoke-Dev.ps1 -Action Test -StateDirectory '<printed state directory>'
pwsh ./dev/Invoke-Dev.ps1 -Action Stop -StateDirectory '<printed state directory>'

Open http://127.0.0.1:19081. The standard QQQ TABLE login username is developer. Read QQQ_ADMIN_PASSWORD from the generated, protected compose.env locally; never paste that file into an issue or commit it. There is no default password. The host provides native printing screens, settings, a dedicated MinIO document bucket and scheduled retention. No printer is enrolled automatically in this host. The test workload uses a separate disposable database and object store.

The current application dependency is QQQ RC.21, which supplies native session login. The optional -Authentik diagnostic still asserts the older RC.20 API 1.8 absence of that feature; it is a retained historical check, not a current RC.21 login test. See provider setup and fixture compatibility. Authentik uses PostgreSQL; the printing host itself uses H2, not PostgreSQL or MySQL.

pwsh ./dev/Invoke-Dev.ps1 -Action Test -Workload 10000

The optional 10,000-job run keeps admission limits enabled, uses eight synthetic clients across two tenants, and reports client process memory, latency and receipt counts. It is a bounded burst, not a day-long soak or physical throughput claim. The default 40-job run measures idle event delivery one job at a time.

Isolation and cleanup

Each environment has a unique qbit-printing-dev-<random> Compose project and matching ownership labels. All published ports bind only to 127.0.0.1: QQQ19081, MinIO19095 and optional Authentik19010. Override them with -QqqPort, -MinioPort and -AuthentikPort when creating a new environment. Occupied ports fail startup; the command never stops another service to free them. PostgreSQL is not published.

State defaults to the current user's application-data directory, outside the checkout, with private filesystem permissions. A custom -StateDirectory must also be outside the checkout. It holds generated fixture credentials, frozen Compose files, ownership records and sanitized result files. Docker administrators can inspect container configuration; use these credentials only for this fixture.

Stop validates container, network and volume ownership before removing that project's resources. It deletes that environment's synthetic databases and objects. It leaves reports and ordinary image/build caches in place and never runs a global prune. A fresh one-command Test performs this cleanup in finally, including on failure. Tests against an existing environment remove only their three test containers; finish with Stop to remove its disposable test volume and the persistent development environment. Do not edit its frozen ownership files.

Images are pinned by digest in Compose/Dockerfiles. Containers have bounded CPU and memory, no automatic restart, and no Docker socket. The default profile has no host credential or source mounts. QQQ/test containers additionally cap process counts. Builds copy only explicit source inputs. The QQQ and MinIO containers share their own network namespace so the existing loopback S3 backend can be used without relaxing production endpoint validation.

What the results mean

• The S3 fixture exercises the actual QQQ StorageAction/S3 backend and AWS SDK, including a multipart-size document, hashes, tenant namespaces, immutable binding checks, retention and unrelated-object preservation.
• The workload uses the real current Java server and pinned Windows Core client: native TABLE authentication, outbound WebSocket notifications, event-driven claims, document downloads and durable server receipts. A fake file printer verifies bytes and rejects duplicate submission. It cannot produce paper.
• The fixture's client receipt journal is intentionally simple; these results do not replace production SQLite crash-recovery tests. MinIO fixture credentials are unrestricted within their owned store and do not qualify production IAM.
• Connections here are HTTP/WebSocket on an isolated local project. TLS, provider browser consent/renewal, real deployment policies and hardware behavior are separate qualifications. No silent bearer-authentication fallback is added.

Results include result.json, server-result.json, s3-results.json and execution.json under a run directory. The persistent host also writes qqq-result.json; optional provider checks write auth-result.json. Treat raw fixture logs as private even though only synthetic accounts/documents are used.

The client Dockerfile pins commit 346fc285198908c47a2ee9db7b9adb53d5e88c3c and verifies its source archive SHA-256 before compilation. The Java image builds this checkout, including local edits, and records its Git HEAD for context; a Git HEAD alone does not certify a dirty tree as that released artifact. This tooling is outside the production JAR and adds no application runtime dependency.

Script regressions

With Pester 5 installed, the initializer and cleanup-ownership tests need no Docker or network. Disable Pester's unrelated registry fixture on Windows:

$configuration = New-PesterConfiguration
$configuration.Run.Path = './dev/tests'
$configuration.Run.Exit = $true
$configuration.TestRegistry.Enabled = $false
Invoke-Pester -Configuration $configuration

Experimental native sign-in

The separate native sign-in profile builds an explicitly selected upstream candidate and uses container-private TLS trust. It mounts only public Caddy configuration and specific protected fixture input/result files. It is opt-in, Test-only, and does not change the default released QQQ dependency.

Continuous integration

Primary Gitea CI runs the shared Maven verification with ui-demo and the pinned protocol fixtures. GitHub Actions were retired for this repository on 2026-11-04. The checked-in .github/workflows/development.yml records the former Windows/Linux Pester, image-build and Docker checks; it is not an active CI guarantee. The commands above remain available for intentional local development checks.

Maven Checkstyle checks all four Java fixture sources in dev/java and dev/native-auth/java during validate. They are deliberately not Maven compiler sources: the ordinary fixture uses the released QQQ tuple, while the native host compiles only inside its explicitly selected candidate image. Both server Dockerfiles copy both roots before Maven runs so neither image can skip this style coverage.

The ten C# fixture files share dev/.editorconfig, strict build properties, central Meziantou 3.0.296, and committed package locks. The existing pinned SDK image contains .NET SDK 10.0.403, matching dev/global.json. Both image builds perform locked, vulnerability-audited restore, warnings-as-errors compilation, formatter verification, and their nine or 12 fake-HTTP discovery cases. Core is still built from the exact public source archive above; no stubs or runtime package dependency were added. For a local build, supply the real pinned Core DLL through -p:CoreAssemblyPath=/absolute/path/Qqq.PrintAgent.Core.dll.

The longer experimental native-auth profile is an explicit local command; it is not silently substituted for the released dependency baseline.