Skip to content

Audit and fix repository consistency issues - #339

Draft
jackspiering wants to merge 4 commits into
mainfrom
codex/repository-consistency-audit
Draft

jackspiering wants to merge 4 commits into
mainfrom
codex/repository-consistency-audit

Conversation

@jackspiering

Copy link
Copy Markdown
Collaborator

Repository consistency audit and fixes

Description

Audited all 122 service stacks, the shared template, deployment documentation, the root service catalog, and CI. This PR fixes confirmed functional inconsistencies and documentation drift while preserving service-specific storage, identities, images, credentials, and access patterns.

Key changes include:

  • Fixed Dockge and NetBox Compose validation failures.
  • Corrected confirmed Serve targets and optional port mappings for BentoPDF, BookLore, Ghost, Tracktor, and XWiki.
  • Fixed Dockhand's application healthcheck, Formbricks optional interpolation, SearXNG secret passing, Mattermost path handling, Traefik configuration paths, Caddy socket mounts, and Minecraft's contradictory Serve configuration.
  • Normalized malformed or duplicate dotenv entries and corrected the shared template.
  • Updated 109 service README network namespace examples, host-path setup instructions, the root catalog, local links, and CI Markdown coverage.

Related Issues

  • None.

Verification

  • docker compose config --quiet from each service directory: 121/122 pass with committed values. Seafile is the only expected failure because JWT_PRIVATE_KEY is intentionally empty.
  • The same check with temporary JWT_PRIVATE_KEY=audit-dummy: 122/122 pass with no warnings.
  • docker compose config --format json: 122/122 parse successfully.
  • Embedded Serve JSON: 112 documents parse successfully; Compose service, dependency, and config references have no unresolved targets.
  • rumdl check . --config .markdownlint.yml: passes all 127 Markdown files.
  • Root catalog contains 122 unique links for 122 service directories.
  • git diff --check: passes.
  • No containers were started, images pulled, or Tailnet connections made.

Checklist

  • I have performed a self-review of my code and followed the templates structure.
  • I have added verification that the stack configuration works as expected.
  • I have updated necessary documentation (e.g. frontpage README.md ).
  • I have selected the correct label(s) for this PR.

Additional Context

  • The audit report was used during implementation but is intentionally not included in this repository change.
  • Runtime healthchecks, Tailscale Serve/Funnel behavior, filesystem permissions, hardware access, and application startup remain unverified because this audit does not start containers or connect to a Tailnet.
  • Seafile's required JWT value was supplied only as a temporary validation value and was not committed.

@jackspiering jackspiering added bug Something isn't working documentation Improvements or additions to documentation CI/CD Continuous Integration / Continuous Deployment (CI/CD) labels Sep 14, 2026

@jackspiering jackspiering left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the 177-file diff and pushed three follow-up commits. The review found the following issues in the changed setup guidance and configuration:

  • Caddy hostname changes break the healthcheck (P2). The new README removes the old workaround, but SERVICE=my-proxy makes the check search for my-proxy. The executable remains caddy. Fixed the check to use the process name in c1663ab.
  • Caddy retains a stale socket after a Tailscale restart (P2). The updated socket sharing still binds the individual socket into Caddy. A replacement socket leaves that mount attached to the old inode. A disposable Docker test reproduced this behavior. Commit c1663ab shares the directory instead.
  • Tracktor setup produces an invalid allowed origin (P2). The new instruction asks for the DNS suffix, but entering tail123.ts.net produces https://tracktor.tail123.ts.net.ts.net. The existing environment entry also preserves literal quote characters. Commit 85dce10 clarifies the input and removes those quotes. This matches Tracktor's origin parsing, which trims whitespace but retains quotes.
  • Two catalog links break on GitHub (P3). GitHub preserves the emoji variation selector in the Development Tools and Food & Wellness heading anchors. The replacement links omit it. Commit 40264c7 adds explicit anchors that work with GitHub and the Markdown linter.

Validation:

  • All 122 service configurations parse with Docker Compose 5.5.1, with a temporary dummy JWT supplied for Seafile. All 112 embedded Serve JSON documents parse.
  • All 127 Markdown files pass both the CI-pinned rumdl 0.2.41 and local 0.2.54.
  • Targeted Compose assertions pass for default and renamed Caddy/Tracktor hostnames, the shared socket directory, and unquoted origins with one .ts.net suffix.
  • GitHub rendering preserves both new anchors. All 23 README fragment links match the existing GitHub heading IDs or the new explicit anchors.
  • A network-disabled disposable container using the existing Alpine image confirmed the socket replacement behavior and was removed afterward.
  • git diff --check passes; the working tree is clean.

I found no further blocking issues in the reviewed diff. Full application startup and Tailnet behavior remain unverified. No service stacks were started, images pulled, or Tailnet connections made. GitHub currently reports no check runs for the latest commit, so the validation above is local.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working CI/CD Continuous Integration / Continuous Deployment (CI/CD) documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant