Setting Environment Variables

To deploy Shape Docs or contribute to the codebase, you must set the required environment variables.

You can find these variables in the .env.example file and the table below.

To set the environment variables locally, copy the .env.example file to .env.local and update the values accordingly.

Environment Variable	Example Value	Description
SHAPE_DOCS_BASE_URL	http://localhost:3000	Base URL for the Shape Docs application.
SHAPE_DOCS_PROJECT_CONFIGURATION_FILENAME	.shape-docs.yml	Filename for the Shape Docs project configuration.
NEXT_PUBLIC_SHAPE_DOCS_TITLE	Shape Docs	Title for Shape Docs.
NEXT_PUBLIC_SHAPE_DOCS_DESCRIPTION	Documentation for Shape's APIs	Description for Shape Docs.
NEXTAUTH_URL_INTERNAL	http://localhost:3000	Internal URL for NextAuth.
NEXTAUTH_SECRET	Use [openssl rand -base64 32] to generate a 32 bytes value.	Secret for NextAuth.
REDIS_URL	localhost	URL for Redis.
POSTGRESQL_HOST	localhost	Host for PostgreSQL.
POSTGRESQL_USER	dbuser	Username for PostgreSQL.
POSTGRESQL_DB	db	Database name for PostgreSQL.
REPOSITORY_NAME_SUFFIX	-openapi	Suffix for repository names.
GITHUB_WEBHOOK_SECRET	Secret specified when [[creating the GitHub App	Creating a GitHub App]].
GITHUB_WEBHOK_REPOSITORY_ALLOWLIST		Comma-separated allowlist for GitHub webhook repositories. See the Restricting Webhooks article for more information.
GITHUB_WEBHOK_REPOSITORY_DISALLOWLIST		Comma-separated disallowlist for GitHub webhook repositories. See the Restricting Webhooks article for more information.
GITHUB_CLIENT_ID	Client ID of the GitHub App created according to this article.	Client ID for GitHub App.
GITHUB_CLIENT_SECRET	Client secret of the GitHub App created according to this article.	Client secret for GitHub App.
GITHUB_APP_ID	ID of the GitHub App created according to this article.	App ID for GitHub App.
GITHUB_PRIVATE_KEY_BASE_64	Base 64 encoded version of the private key obtained when creating the GitHub App according to this article.	Base64 encoded private key for GitHub App.

The GitHub private key residing in GITHUB_PRIVATE_KEY_BASE_64 must be PKCS8. When creating a private key through the GitHub App settings, you'll obtain a PKCS1 key. The key must manually be converted from PKCS1 to PKCS8 before base64 encoding it. This can be done as follows:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt \
  -in private-key-pkcs1.pem \
  -out private-key-pkcs8.pem

The key can then be base 64 encoded as follows:

base64 -i ~/Downloads/private-key-pkcs8.pem | pbcopy

The output can be assigned to the GITHUB_PRIVATE_KEY_BASE_64 environment variable.