Table of Contents

AWS S3 Cache Management for Codio

Jason Carroll Updated by Jason Carroll

This article covers the recommended configuration and publishing procedures for the shared Codio stylesheet in AWS S3.

Summary

The GitHub/jsDelivr proof of concept successfully served the shared stylesheet, but it did not remove the browser-cache problem when a stable URL was used. Purging the CDN refreshed jsDelivr’s copy but could not invalidate a copy already held by a learner’s browser.

The recommended approach is to retain the existing centralized AWS S3 stylesheet and configure its HTTP metadata so browsers revalidate it before reuse. This keeps one stable URL across the many Codio units and avoids requiring learners to clear their cache after future stylesheet updates.

Cache-Control: no-cache, must-revalidate
Content-Type: text/css

Cache-Control is HTTP response metadata stored with the S3 object; it cannot be added inside the CSS file. The no-cache directive permits the browser to retain a local copy but requires it to check whether that copy is still current before reuse. If the object is unchanged, S3 can respond with 304 Not Modified. If it changed, the browser receives the updated stylesheet.

This is preferable to no-store for this use case. no-store would prevent normal browser storage and require the entire stylesheet to be downloaded repeatedly, while no-cache allows efficient revalidation.

Method 1: Update metadata on an existing S3 file

Use this method for a stylesheet that is already stored in S3, including the existing shared Codio stylesheet. Amazon S3 changes metadata on an existing object by copying the object back to the same destination with replacement metadata.

  1. Open the AWS Web Console and go to Amazon S3.
  2. Open the bucket containing the stylesheet. 
  3. Navigate to Codio/CSS/ and select the checkbox beside styles.css.
  4. Choose Actions, then Copy.
  5. For the destination, browse to and select the same folder: s3://ecornell/Codio/CSS/.
  6. Under Additional copy settings, choose Specify settings.
  7. In the Metadata section, choose Replace all metadata.
  8. Add system-defined metadata for Cache-Control with the value no-cache, must-revalidate.
  9. Retain or add Content-Type with the value text/css, along with any other existing metadata that must be preserved.
Cache-Control: no-cache, must-revalidate
Content-Type: text/css
  1. Choose Copy and confirm replacement of the object at the same key.
Important caution when replacing metadata
Choosing Replace all metadata may remove existing metadata values that are not entered again during the copy. Before continuing, review the object’s current metadata. For a CSS file, ensure that Content-Type: text/css is retained while adding Cache-Control: no-cache, must-revalidate. If the object contains any other required custom metadata, preserve those values as well.

Method 2: Set metadata while uploading a new or replacement file

Use this method whenever a new stylesheet is uploaded or styles.css is uploaded again to overwrite the existing object.

  1. In the S3 console, open the destination bucket and folder.
  2. Choose Upload and add the local styles.css file.
  3. Open the upload Properties or Metadata settings before completing the upload.
  4. Set Content-Type to text/css.
  5. Set Cache-Control to no-cache, must-revalidate.
  6. Complete the upload and confirm the overwrite if styles.css already exists.
  7. After upload, open the object’s Properties and verify that both metadata values are present.

Critical overwrite behavior

An upload that overwrites styles.css replaces the S3 object. The new upload should not be assumed to retain the prior Cache-Control metadata. If Cache-Control is omitted during that upload, the replacement object may no longer return no-cache, must-revalidate, and the original browser-caching problem can return.

Therefore, the metadata must be supplied or verified every time styles.css is uploaded. This operational requirement should be included in the publishing procedure.

To reduce the chance of metadata being forgotten, use a repeatable AWS CLI command or deployment script instead of relying on manual console settings:

aws s3 cp styles.css s3://ecornell/Codio/CSS/styles.css \  
    --content-type "text/css" \  
    --cache-control "no-cache, must-revalidate"

This command uploads or overwrites styles.css and applies the required metadata in the same operation. The command should be stored in internal deployment documentation or a small approved publishing script.

Comparison of the two S3 workflows

Situation

Required action

Main risk

Existing S3 object

Copy the object to the same key and replace metadata.

Other existing metadata can be lost if it is not included.

New upload

Set Cache-Control and Content-Type in the upload settings.

Publisher may omit the settings.

Overwrite existing file

Upload with the metadata again, then verify it.

Prior Cache-Control should not be assumed to persist.

Automated upload

Use CLI/script flags for both headers.

Script must remain the standard publishing route.

Verification after configuration or upload

The S3 object’s Properties page confirms stored metadata, but the final validation should also confirm the actual HTTP response received by a browser.

  1. Open the stylesheet URL in Chrome.
  2. Open Developer Tools and select the Network panel.
  3. Reload the stylesheet and select its network request.
  4. Under Response Headers, confirm cache-control: no-cache, must-revalidate and content-type: text/css.
  5. Load a Codio unit and establish the current visual state.
  6. Upload a small test change while preserving the metadata.
  7. Use an ordinary page load or ordinary refresh—without clearing cache or performing a hard refresh—and confirm the change appears.
  8. Revert the test change with another correctly configured upload and repeat the ordinary-refresh test.

Transition limitation

Changing the S3 metadata cannot retroactively change the cache instructions attached to a copy that a learner’s browser already stored earlier. Some existing users may temporarily retain the old copy until its previous cache lifetime expires or until one final hard refresh is performed. Once the browser receives the stylesheet with no-cache, must-revalidate, later updates should be revalidated automatically during normal future loads.

This approach also cannot update a page that is already open without a reload. The intended result is that the next normal page load or refresh receives current CSS without requiring the learner to clear browser data.

  • Continue using the existing central S3 stylesheet URL referenced by Codio units.
  • Apply Cache-Control: no-cache, must-revalidate and Content-Type: text/css.
  • Treat the headers as required deployment metadata, not a one-time object setting.
  • Prefer an approved CLI command or script that applies the headers on every upload.
  • If the console is used, verify the object metadata after every overwrite.
  • If CloudFront or another proxy is later placed in front of S3, review its cache policy separately.

AWS references

AWS S3 User Guide — Editing object metadata in the S3 console

AWS CLI Command Reference — aws s3 cp

How did we do?

Setting Up the Class Fork (LTI 1.3)

R Studio - Exclusion List for R Code

Contact