[Request]: Explain APP_KEYS environment variable in the docs

[NicoHof]

Summary

When creating a new project this was automatically generated in config/server.js

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

I am currently trying to deploy Strapi on Render. Documentation for this is fine so far. But deployment fails due to the error, that "APP_KEYS" env variable is missing. The APP_KEYS is stored in .env file. So far so good. So I fixed it by adding "APP_KEYS" to my env settings

But the main question is: what is this variable there for?

Why aren't they mentioned in the server.js docs here? https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/configurations/required/server.html#available-options

Or am I missing some documentation for this?

Why is it needed?

Documentation for "APP_KEYS" env variable. What is this for? Can it be omitted? Do I need to change this for different deployments?

Suggested solution(s)

Update those docs: https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/configurations/required/server.html#available-options

or link to the existing docs there (I cannot find)

Related issue(s)/PR(s)

No response

[stb13579]

Hello @NicoHof. I am a technical writer at Strapi. Thank you for bringing this issue to our attention. The APP_KEYS environment variable was included in the v4.0.6 migration. There is some information available in the migration guide . I will work with my colleagues to add the documentation to the main developer docs as well.

Thanks again for your participation.

[mkmarkop]

Are there any updates on this?

[cwray-tech]

Plus one on this. For me, I wanted to work on the same project I built using quick start and came up on this issue after running yarn develop.

The error messages are not very clear that this needs to be set in the env, and I think there should be a command like "npx Strapi generate:keys" to create a secure key when setting up a project.

[owenduncansnobel]

Ya I just had the same problem. When following the deploy to Heroku with Postgres it has you set up the config and .envs for everything but does not mention setting the APP_KEYS. It should probably mention that you need to add the APP_KEYS to the Heroku config

[stb13579]

Hello @NicoHof, Thanks again for raising this issue. The server.js file documentation is updated with PR #799 to include the app.keys parameter. We are continuing to evaluate where we can improve the documentation, so feedback such as this is really appreciated. @owen-duncan-snobel I split your comment into a new GitHub issue and will look into it shortly.

[NicoHof]

@StrapiShaun Thank you for linking the PR and updating the Docs with the hint to "koa"! :)

I think its not your job to explain how koa works so the updated readme in your PR is sufficient.

But as I am not familiar with koa I was still a bit confused why there are multiple keys needed and digged a bit in koa and found some kind of helpful stack overflow question. https://stackoverflow.com/questions/35362507/why-need-more-than-one-secret-key-on-koa

So for all who land here and search for a further explanation maybe this ressource helps... To sum it up: u can use multiple app keys for a "soft" secret key rotation. Add a new key and remove the oldest one. But it can also be just one key in the array if you do not care about it.

[bbbco]

Even though it's "not your job to explain how koa works", it might be helpful to explain why one might add more than one key (i.e., key rotation). Otherwise, this is not straightforward to the initial reader.