More comprehensive getting started guide

[coeit]

Summary

The current "New Zendro project from scratch" documentation should be more comprehensive for new users. It is missing some information / needs better wording and could be separated into a Quickstart and Getting started guide. This is probably best achieved through different pages. These two guides should be the first thing a user sees/clicks when arriving on the home page and as such should be more visible (consider adding big colorful buttons?)

Quickstart

The Quickstart should be as concise as possible in describing setting up a new Zendro instance with default parameters. It uses pre-defined datamodels, database and environment variables to describe how to set up zendro instance in as few steps as possible.

Getting started

A more detailed Guide on how to set up zendro for different zendro applications:

• using your own datamodels
• connect to your own database

This guide should give clear instructions on how and where to configure:

• data-model definitions
• environment files that need to be edited
• environment variable explanations
• database config file

A few shortcomings of the current guide that should be fixed:

• Rename section "Create code for Graphql-server" to "Generate the necessary code" or something alike
• In the above section make clear that we strongly recommend to supply the -m switch to include the migrations. Should be part of the quickstart example. Give a short sentence about when not to use -m (Using your own database,...)
• add a little friendly hint that after starting zendro some patience is required, because (i) migrations, (ii) react component building

[coeit]

Comprehensive list of environment variables:

GraphQL server

Mandatory

• ALLOW_ORIGIN - Sets the Access-Control-Allow-Origin header to the specified value.

Optional (without defaults)

• MAIL_SERVICE - For bulk add operations, the email service to use for sending progress reports.
• MAIL_HOST - Email service host (usually SMTP config).
• MAIL_ACCOUNT - Sender email account address.
• MAIL_PASSWORD - Sender email account password.
• OAUTH2_TOKEN_URI - Endpoint of OAuth2 token service
• OAUTH2_PUBLIC_KEY- OAuth2 service public key used to encrypt / verify tokens
• OAUTH2_CLIENT_ID- GraphQL server OAuth2 Client ID
• GRAPHIQL_REDIRECT_URI- RedirectURI of the graphiql-auth client, used to migrate the default keycloak OAuth2 service
• SPA_REDIRECT_URI- RedirectURI of the single-page-app client, used to migrate the default keycloak OAuth2 service

Optional (with sensible defaults)

• ERROR_LOG - Debug logs verbosity. Can be either "verbose" or "compact". Default value is compact.
• EXPORT_TIME_OUT - Maximum amount of time in milliseconds before the server throws a timeout error when exporting data. Default is 3600.
• LIMIT_RECORDS - Maximum number of records that each request can return, default value is 10000.
• PORT - The port where the app is listening, default value is 3000
• POST_REQUEST_MAX_BODY_SIZE - Maximum size of the GraphQL request in MB. Default is 1mb.
• MAX_TIME_OUT - Maximum number of milliseconds that a zendro server will wait to connect with another zendro server. Default value is 2000.
• REQUIRE_SIGN_IN - Boolean to toggle the required sign in to the graphql server. Default is true.
• SALT_ROUNDS - Number of salt rounds when hashing a new password. Default is 10.

Single-page-app

Mandatory

• NEXT_PUBLIC_ZENDRO_GRAPHQL_URL - GraphQL endpoint address. Used to send data queries and mutations.
• NEXT_PUBLIC_ZENDRO_EXPORT_URL - Endpoint export address. Used to request table downloads in CSV format.
• NEXT_PUBLIC_ZENDRO_METAQUERY_URL - GraphQL meta-query endpoint address. Used to send meta- queries and mutations.
• NEXT_PUBLIC_ZENDRO_MAX_UPLOAD_SIZE - Maximum allowed upload size in megabytes.
• NEXT_PUBLIC_ZENDRO_MAX_RECORD_LIMIT - Maximum number of records that can be returned per request.
• ZENDRO_DATA_MODELS - relative path from the root of the directory to your models folder

Mandatory (OAuth2)

• OAUTH2_ISSUER - OAuth2 Issuer URL
• OAUTH2_TOKEN_URI - Endpoint of OAuth2 token service
• OAUTH2_CLIENT_ID - SPA OAuth2 Client ID
• OAUTH2_CLIENT_SECRET - SPA OAuth2 Client Secret
• NEXTAUTH_URL - When deploying to production, set the NEXTAUTH_URL environment variable to the canonical URL of your site.
• NEXTAUTH_SECRET - Used to encrypt the NextAuth.js JWT, and to hash email verification tokens.

Graphiql-auth

Mandatory

• NEXT_PUBLIC_ZENDRO_GRAPHQL_URL - GraphQL endpoint address. Used to send data queries and mutations.
• NEXT_PUBLIC_ZENDRO_METAQUERY_URL - GraphQL meta-query endpoint address. Used to send meta- queries and mutations.

Mandatory (OAuth2)

• OAUTH2_ISSUER - OAuth2 Issuer URL
• OAUTH2_TOKEN_URI - Endpoint of OAuth2 token service
• OAUTH2_CLIENT_ID - SPA OAuth2 Client ID
• OAUTH2_CLIENT_SECRET - SPA OAuth2 Client Secret
• NEXTAUTH_URL - When deploying to production, set the NEXTAUTH_URL environment variable to the canonical URL of your site.
• NEXTAUTH_SECRET - Used to encrypt the NextAuth.js JWT, and to hash email verification tokens.