Add runtime acceptance tests for the Nextcloud app image #49

Goal

Add a reusable runtime acceptance test for the Nextcloud app image built by this repository.

The test must answer:

Does the image we are about to publish actually start, install Nextcloud, and provide a working FPM runtime?

This replaces the previous plan to use this issue as a smoke test for the complete Compose stack. The image lifecycle in #47 needs an image-focused gate first. Full-stack integration is a separate concern.

Reference architecture

Follow the same testing direction used by the official Nextcloud container projects:

• Docker Official Images starts the Nextcloud image under test with ephemeral database resources, waits with retry logic, and validates the installed instance with occ;
• the official FPM test also verifies that the FPM runtime accepts FastCGI requests;
• nextcloud/nextcloud-docker-dev builds images first and then starts a real Nextcloud environment before considering the relevant development runtimes healthy.

Do not copy Docker Official Images infrastructure such as bashbrew. Reuse the behavioral contract that matters to this repository.

Test target

The test target is an already-built local image reference supplied to the test command.

Examples:

tests/test-app-image.sh scan/app:amd64
tests/test-app-image.sh scan/app:arm64

The test must not rebuild the image internally. CI must test the exact image produced by the build step.

This allows the same acceptance test to be reused later for stable images and the master-fpm development channel.

Runtime acceptance scenario

For each image under test:

1. create an isolated Docker network;
2. start an ephemeral PostgreSQL container;
3. start the app image with Nextcloud autoinstall variables pointing to that database;
4. wait using retry/readiness logic, not a fixed startup delay;
5. execute occ status as the Nextcloud runtime user;
6. require the instance to report installed: true;
7. execute occ check;
8. verify that the FPM runtime is accepting FastCGI connections;
9. clean up all resources created by the test.

On failure, print useful container logs before cleanup.

Isolation

The acceptance test must:

• use unique test resource names;
• create its own Docker network;
• create only ephemeral containers/resources;
• not use repository bind mounts;
• not use existing application data;
• not depend on the repository Compose stack;
• not remove resources it did not create.

The PostgreSQL container is a test dependency, not a second deployment architecture.

Local execution

Provide one documented command for testing an already-built image.

Also provide a convenience command that builds the current app image and runs the same acceptance test locally.

The acceptance logic itself must remain independent from GitHub Actions.

CI integration

Integrate the acceptance test into the existing image build lifecycle.

For pull requests:

build -> vulnerability scan -> runtime acceptance

For publication:

build -> vulnerability scan -> runtime acceptance -> publish

An image must not be published if runtime acceptance fails.

Run the acceptance test against each architecture that this repository publishes. The test command must stay the same; architecture selection belongs to the built image/runtime invocation.

Out of scope

Do not add in this issue:

• a second Docker Compose stack;
• tests of the repository deployment Compose files;
• Redis integration tests;
• the web image integration test;
• browser/Playwright tests;
• LibreSign-specific behavior;
• a new Dockerfile per Nextcloud major;
• changes to the master-fpm image architecture itself.

Those concerns must be handled separately.

Acceptance criteria

• A reusable test accepts an already-built app image reference.
• The exact image produced by CI is the one tested.
• PostgreSQL and all test resources are ephemeral and isolated.
• Nextcloud is installed automatically.
• Readiness uses retry logic rather than a fixed delay.
• occ status reports installed: true.
• occ check passes.
• FPM accepts a FastCGI request.
• Failures include useful diagnostics.
• Cleanup runs after success and failure.
• The same test works locally and in CI.
• Both published architectures pass runtime acceptance.
• Publication occurs only after vulnerability scanning and runtime acceptance pass.
• No Compose deployment architecture is duplicated.

Relationship to the Epic

This is the first runtime gate for #47.

The test should exist before the generic image-foundation refactor so that the same behavioral contract can validate the current image and then protect the replacement of the version-specific development image.