Setting Environment Variables

To deploy Framna 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	Value	Description
FRAMNA_DOCS_BASE_URL	https://docs.example.com/	Domain name Framna Docs is deployed on.
FRAMNA_DOCS_TITLE	Framna Docs	Title of the site.
FRAMNA_DOCS_DESCRIPTION	Documentation for Framna's APIs	Metadata description of the site.
FRAMNA_DOCS_HELP_URL	https://github.com/shapehq/framna-docs/wiki	Link to website where users can learn more about Framna Docs.
FRAMNA_DOCS_PROJECT_CONFIGURATION_FILENAME	.framna-docs.yml	Filename for the project configuration file residing in the repository. See the Adding Documentation to Framna Docs for more information.
NEXTAUTH_URL	https://example.com	URL on which Framna Docs is hosted.
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 the PostgreSQL database.
POSTGRESQL_PASSWORD		Password for the PostgreSQL database.
POSTGRESQL_DB	framna-docs	Database name for PostgreSQL.
REPOSITORY_NAME_SUFFIX	-openapi	Suffix for repository names. Framna Docs only considers repositories with this suffix.
HIDDEN_REPOSITORIES	acme/foo-openapi	Full name of repositories to hide from the project list.
NEW_PROJECT_TEMPLATE_REPOSITORY	shapehq/starter-openapi	Repository on GitHub to use as a template when creating new projects.
PROXY_API_MAXIMUM_FILE_SIZE_IN_MEGABYTES	10	Maximum allowed size of files to be downloaded through the /api/proxy endpoint, specified in megabytes.
PROXY_API_TIMEOUT_IN_SECONDS	30	Maximum time to spend downloading a file through the /api/proxy endpoint, specified in seconds.
GITHUB_WEBHOOK_SECRET	Secret specified when creating the GitHub App.	Secret for GitHub webhooks.
GITHUB_WEBHOK_REPOSITORY_ALLOWLIST		Comma-separated allowlist for GitHub webhook repositories. See the Limiting Pull Request Comments article for more information.
GITHUB_WEBHOK_REPOSITORY_DISALLOWLIST		Comma-separated disallowlist for GitHub webhook repositories. See the Limiting Pull Request Comments 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.
ENCRYPTION_PUBLIC_KEY_BASE_64	Base 64 encoded version of the public key. Instructions below.	Public key used for encrypting remote specification credentials
ENCRYPTION_PRIVATE_KEY_BASE_64	Base 64 encoded version of the private key. Instructions below.	Private key used for decrypting remote specification credentials

GITHUB_PRIVATE_KEY_BASE_64

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 private-key-pkcs8.pem | pbcopy

The output can be assigned to the GITHUB_PRIVATE_KEY_BASE_64 environment variable.

ENCRYPTION_PUBLIC_KEY_BASE_64 & ENCRYPTION_PRIVATE_KEY_BASE_64

This key pair can be generated with the following openssl commands:

openssl genrsa -out private-key.pem 2048

openssl rsa -in private-key.pem -pubout -out public-key.pem

The key must then be base64 encoded before assigned to the environment variables:

base64 -i private-key.pem | pbcopy

base64 -i public-key.pem | pbcopy