Skip to content

Improve documentation about ASTRO_KEY #11751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve documentation about ASTRO_KEY #11751

wants to merge 1 commit into from
+18 −12

Conversation

dpuscher
Copy link

Description (required)

This PR refines the "Reusing the encryption key" section in the Server Islands guide to enhance clarity and conciseness. The updated content emphasizes the necessity of setting ASTRO_KEY during the build phase.

Related issues & labels (optional)

  • Suggested label: docs

@netlify Netlify
Copy link

netlify bot commented May 23, 2025 •
edited
Loading

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 95f6d8a
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/6835b79b8fa9c200083b3b90
😎 Deploy Preview https://deploy-preview-11751--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@astrobot-houston
Copy link
Contributor

astrobot-houston commented May 23, 2025 •
edited
Loading

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File Note
en/guides/server-islands.mdx Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

@astrobot-houston
Copy link
Contributor

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

  1. Our GitHub bots will run to check your changes.
    If they spot any broken links you will see some error messages on this PR.
    Don’t hesitate to ask any questions if you’re not sure what these mean!

  2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

  3. One or more of our maintainers will take a look and may ask you to make changes.
    We try to be responsive, but don’t worry if this takes a few days.

@dpuscher dpuscher changed the title docs: improve documentation about ASTRO_KEY Improve documentation about ASTRO_KEY May 23, 2025
@dpuscher dpuscher force-pushed the improve-astro-key-doc branch from f9fe6c7 to 6763471 Compare May 23, 2025 13:22
ascorbic
ascorbic reviewed May 23, 2025
View reviewed changes
src/content/docs/en/guides/server-islands.mdx

To solve this, you can create a key with the Astro CLI and then reuse it for all of your deployments. This ensures that each user's frontend is talking to a backend that has the right key.
To ensure both sides use the same key, you must supply the `ASTRO_KEY` environment variable **during the build**. This embeds always the same key into the generated bundle so that encryption and decryption remain in sync.
Copy link
Contributor

Choose a reason for hiding this comment

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

As this is a new paragraph it might be unclear that this only applies if you are doing rolling deployments, and that most users don't need to worry about it.

Copy link
Author

Choose a reason for hiding this comment

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

Agree, I added an additional note that setting an ASTRO_KEY is probably not needed for most users.

ascorbic
ascorbic reviewed May 23, 2025
View reviewed changes
src/content/docs/en/guides/server-islands.mdx

### Generating and configuring a reusable key

Use the Astro CLI to generate a reusable key:
Copy link
Contributor

Choose a reason for hiding this comment

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

I have seen people getting confused, thinking that the required value is just a random string rather than an actual encoded key in a specific format.

Copy link
Author

Choose a reason for hiding this comment

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

True, I adjusted the last section to make clear that the output ASTRO_KEY is not just a random string but an encoded encryption key

@dpuscher dpuscher force-pushed the improve-astro-key-doc branch 3 times, most recently from 8521d5b to cd42c83 Compare May 27, 2025 11:49
@dpuscher dpuscher force-pushed the improve-astro-key-doc branch from cd42c83 to 95f6d8a Compare May 27, 2025 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ascorbic ascorbic ascorbic left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@dpuscher @astrobot-houston @ascorbic