Skip to content

Make installing the proxy from a repository archive the documented way - #108

Merged
sgiehl merged 1 commit into
masterfrom
make-install-method-safe
Aug 17, 2026
Merged

sgiehl merged 1 commit into
masterfrom
make-install-method-safe

Conversation

@sgiehl

@sgiehl sgiehl commented Aug 17, 2026 •

Copy link
Copy Markdown
Member

Why

The README documents git clone as one of the installation methods. A checkout contains a lot that an installation does not need — the test suite, the CI configuration, the coding standard rules and the git metadata itself — and none of that belongs in a public web root. Installing from an archive keeps the installed directory to the files the proxy actually consists of.

What

  • .gitattributes: export-ignore for tests/, .github/, phpcs.xml, .editorconfig, .gitignore, .gitattributes, .php-version and composer.lock. git archive output — and the source archives GitHub attaches to releases and serves from /archive/ — then contain only LICENSE, README.md, composer.json, config.php.example, the four entry points and plugins/HeatmapSessionRecording/configs.php. composer.json is kept deliberately: dropping it would break Composer-based consumption and it only lists dependency names.
  • README: the source archive becomes the documented installation method, with a curl … | tar xz --strip-components=1 recipe and an update instruction noting that config.php is not part of the archive and is left untouched, while extracting over an existing installation never removes files. The clone instructions move to the contributing section as a development checkout, and the installation section points installations that contain a tests/ directory at cleaning it up.
  • tests/server/matomo.php: this stand-in for a Matomo server is only meaningful together with the test configuration, so it now runs only when the loaded config points at tests/server/ and returns 403 otherwise — the same gate .github/config.php already uses for its test-only header hooks. Its non-image responses also get an explicit text/plain content type plus nosniff instead of falling back to whatever the web server assumes. A new test covers the refusal, via a new X-Test-Non-Test-Config hook in the test configuration.

Notes

  • export-ignore only affects archives generated after this is merged, so the archives of the existing tags still contain the development files. The README therefore points at the master archive, which is clean as soon as this lands. Once a tag is cut on top of this, the README can document the tagged archive as the primary download.
  • The README's copy of the test config.php is kept in sync with .github/config.php by hand; that duplication predates this PR, but is worth replacing with a pointer at some point.

Tests

vendor/bin/phpunit -c tests/phpunit.xml.dist — 95 passed, 254 assertions, including the new one. Verified that the new test fails when the check in tests/server/matomo.php is removed, and that git archive output matches the file list above. vendor/bin/phpcs is clean.

@sgiehl
sgiehl force-pushed the make-install-method-safe branch from 41aba21 to 3a8f417 Compare August 17, 2026 09:10
A repository checkout contains a lot that an installation does not need: the
test suite, the CI configuration, coding standard rules and the git metadata
itself. Installing from an archive instead keeps the installed directory to
the files the proxy actually consists of.

- mark the development-only files as export-ignore, so `git archive` output
  and the source archives GitHub attaches to releases contain only the files
  that belong in a web root
- document the source archive as the way to install the proxy, and move the
  clone instructions to the contributing section
- run the tests/server/ stand-in only for the test configuration it belongs
  to, give its non-image responses an explicit content type, and cover that
  with a test
@sgiehl
sgiehl force-pushed the make-install-method-safe branch from 3a8f417 to c12a81b Compare August 17, 2026 09:23
@sgiehl
sgiehl requested a review from a team August 17, 2026 09:38
Comment thread .gitattributes
@sgiehl
sgiehl merged commit ecbc1a3 into master Aug 17, 2026
8 checks passed
@sgiehl
sgiehl deleted the make-install-method-safe branch August 17, 2026 14:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants