Skip to content

Document asset bridging retention in configuration help - #1998

Open
Harsh23Kashyap wants to merge 1 commit into
basecamp:mainfrom
Harsh23Kashyap:patch-1
Open

Harsh23Kashyap wants to merge 1 commit into
basecamp:mainfrom
Harsh23Kashyap:patch-1

Conversation

@Harsh23Kashyap

@Harsh23Kashyap Harsh23Kashyap commented Nov 15, 2026 •

Copy link
Copy Markdown

Refs #1976.

Document the asset retention boundary in kamal docs: bridging uses assets extracted from the current and immediately previous images. After A, B and C deploy, files found only in A are unavailable, even with a larger retain_containers value. The help also explains the lazy-loaded JS case and points applications needing longer retention to persistent asset storage or an asset origin/CDN.

This changes configuration help only. It does not change retention behavior or update the separate documentation website.

Verification on Ruby 3.4.7 / Linux:

  • Executed the current sync_asset_volumes and clean_up_assets commands against real temporary directories for A/B/C, twice before editing and in 20 fresh processes afterward. A's volume has A, B's has A+B, and C's has B+C but no A, including with retain_containers: 99.
  • bin/test test/commands/app_test.rb test/configuration_test.rb: 144 runs, 220 assertions, no failures, errors or skips.
  • bundle exec bin/kamal docs includes the new text. bundle exec rubocop: 178 files, no offenses. git diff --check passes.

The lifecycle probe ran the generated filesystem commands locally, not Docker, SSH, a browser SPA or a CDN. The full and Docker integration suites were not run.

RetriggerView in GreptileConfidence Score: 5/5 Tier: plus

The PR appears safe to merge.

Summary

Updates configuration help to explain asset bridging’s two-image retention window.

  • The configuration help explains how long bridged assets stay available.

The documented boundary matches the asset-copy and cleanup code. This review checked source code; it did not run tests.

Reviews (2) · Last reviewed commit: "Document asset bridging retention in con..." · Reviewed by Greptile

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approved

No active review issues are reported for this configuration-help update clarifying asset retention limits and longer-retention options.

No open issues 🎉

What changed in this PR

Clarifies asset bridging retention in kamal docs, addressing #1976. This updates configuration help only; runtime behavior and the separate documentation website are unchanged.

Changes:

  • Explains that bridging includes assets from the current and immediately previous images, regardless of retain_containers.
  • Describes the risk of 404s for older, never-fetched lazy-loaded JavaScript files.
  • Recommends persistent storage or an asset origin/CDN for longer retention.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File Description
lib/​kamal/​configuration/​docs/​configuration.yml Adds help text covering retention limits, lazy-loaded assets, and longer-retention options.

Review effort: Balanced

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