Merge pull request #191 from godspeedsystems/add/guides

add env

docs/microservices-framework/config-and-mappings/config.md

@@ -1,12 +1,15 @@
 # Config
-## Config structure
 
-The configuration variables, along with their respective values, are specified within YAML files located in the `config/` directory. These variables are easily customizable to align with specific business use cases. The default directory structure is outlined as follows
+The configuration variables, along with their respective values, are specified within YAML files located in the `config/` directory. These variables are easily customizable to align with specific business use cases. 
+### Config structure
+The default directory structure is outlined as follows
 
 ```
 ├── config
 │   ├── custom-environment-variables.yaml
 │   ├── default.yaml
+├
+├── .env
 ```
 
 ### File naming and Load order
@@ -15,29 +18,24 @@ The configuration files under `config/` directory can have specific naming conve
 
 ## Environment variables
 
-**Configuration of enviroment variables can be done in two ways**
+Environment variables in Godspeed are essential for securely managing configuration details like API keys, database URLs, and other sensitive information. Godspeed allows two primary ways to configure and access these variables.
 
-1. The environment variables are defined in yaml files under `config/custom-environment-variables.yaml` file. The default directory structure is given as below:
+> **Note**: For sensitive information such as secrets or passwords, it is recommended to use environment variables in this way to avoid hardcoding values directly in your configuration files.
 
+### Configuration Setup for Environment Variables
 
-```
-├── config
-│   ├── custom-environment-variables.yaml
-```
+Environment variables can be set up using: 
+1. **Define variables** in `config/custom-environment-variables.yaml`.
+2. **Set values** in `.env` or use `export` in the terminal.
+3. **Access variables** using `<% config.variable_path %>` in yaml and `ctx.config` in typeScript workflows.
 
-2. We can also add database connection string and Urls in .env  file is under root folder `/.env`
+### Step 1: Define Environment Variables in YAML Configuration
 
-```
-├── .env
-```
+In the `config/custom-environment-variables.yaml` file, specify the environment variables you want to use across your project. This YAML file **maps environment variables** to meaningful keys, which you’ll use in your code.
 
-:::note
-Any configuration which includes secrets or passwords is recommended to be defined using environment variables only.
-:::
+**Example `custom-environment-variables.yaml`:**
 
-### custom-environment-variables.yaml
-This is a sample for custom environment variables where these variables gets values from environment variables set in the environment. 
-```
+```yaml
 my_datasource:
   base_url: MY_DATASOURCE_BASE_URL
   api_key: MY_DATASOURCE_API_KEY
@@ -57,19 +55,83 @@ jwt:
 prisma_secret: PRISMA_SECRET
 ```
 
-For example, `MY_DATASOURCE_BASE_URL` is defined as an environment variable. To specify its value, you need to export this variable in the environment.Enter as given below in the terminal:
-
-```
-$ export MY_DATASOURCE_BASE_URL=https://httpbin.org/
-```
-
-After exporting the environment variable, you can access this variable in your project by using scripting 
-`<% config.my_datasource.base_url %>`
+### Step 2: Set Environment Variable Values
+
+After defining environment variable keys in `custom-environment-variables.yaml`, you can provide actual values in two ways:
+
+1. **Define in `.env` file**:
+   - Open `.env` file and assign values to each variable specified in `custom-environment-variables.yaml`.
+
+     **Example `.env` file:**
+     ```plaintext
+     MY_DATASOURCE_BASE_URL=https://httpbin.org/
+     MY_DATASOURCE_API_KEY=your_api_key_here
+     MY_DATASOURCE_API_TOKEN=your_api_token_here
+     
+     KAFKA_BROKERS=["localhost:9092"]
+     KAFKA_CLIENT_ID=my-kafka-client
+     
+     JWT_ISS=https://your-issuer.com
+     JWT_AUD=https://your-audience.com
+     JWT_SECRET=your_jwt_secret
+     
+     PRISMA_SECRET=your_prisma_secret
+     ```
+
+2. **Set values directly in the environment**:
+    You can export these variables temporarily to environment by following the below syntax, based on the environment you are using:
+    - **For shell/git bash**, use `export` command as:
+      ```bash
+      $ export MY_DATASOURCE_BASE_URL=https://httpbin.org
+      $ export JWT_SECRET=mysecret
+      $ export JWT_ISS= mycompany
+      ```
+    - **For windows powershell**
+      ```
+        $env:JWT_SECRET="mysecret"
+        $env:JWT_ISS="mycompany"
+      ```
 
 :::info To reflect the updated values of the .env variables, you need to export them again after making changes. This ensures that the updated values are accessible and used in your application.
 :::
 
 
+### Step 3: Access Environment Variables in Your Project
+
+Once environment variables are set up, they can be accessed in Godspeed Project as:
+
+- **In Yaml Files**: Use the templating syntax `<% config.variable_path %>` to access the variable.
+
+  **Example**:
+  ```yaml
+  datasource:
+    base_url: <% config.my_datasource.base_url %>
+  ```
+
+- **In TypeScript/JavaScript files**:
+  Use `ctx.config` to access values within your TypeScript workflows.
+
+  **Example TypeScript Workflow**:
+  ```typescript
+  import { GSContext, GSStatus } from "@godspeedsystems/core";
+
+  export default async function myWorkflow(ctx: GSContext, args: any) {
+      const apiKey = ctx.config.my_datasource.api_key;
+      const apiUrl = ctx.config.my_datasource.base_url;
+
+      if (!apiKey || !apiUrl) {
+          throw new GSStatus(false, 500, undefined, "Missing configuration variables");
+      }
+
+      // Use apiKey and apiUrl in your logic
+      console.log("API Key:", apiKey);
+      console.log("API URL:", apiUrl);
+
+      return new GSStatus(true, 200, undefined, { message: "Environment variables accessed successfully" });
+  }
+  ```
+  This setup provides a secure, centralized way to manage sensitive configuration data, making it easy to change values without modifying the source code.
+
 
 ## Static variables
 The static variables as well as their values are defined in yaml files under `config/` directory. These variables can be replaced as per the business use cases. The default directory structure is given as below:

docs/microservices-framework/config-and-mappings/env.md

@@ -0,0 +1,65 @@
+# Environment Variables
+
+In a Godspeed project, the .env file is a standard way to define environment-specific variables. 
+Using this file offers several advantages:
+
+- **Security:** Sensitive information (like API keys and secrets) is stored outside of the codebase, helping prevent accidental exposure.
+- **Environment-Based Configuration:** You can specify different values for variables based on your environment, allowing seamless transitions between development, testing, and production.
+- **Easy Access Across the Project:** The variables defined in .env can be accessed easily in Godspeed configurations, workflows, and scripts.
+
+.env file is placed in the root directory of your project.
+```
+|
+├── .env
+```
+
+> **Note**: For sensitive information such as secrets or passwords, it is recommended to use environment variables in this way to avoid hardcoding values directly in your configuration files.
+
+
+## How to Set Up and Use the .env File
+
+**Define Variables in the .env File:**
+ Add key-value pairs for each environment variable. Here’s an example of what you might define in a Godspeed project:
+
+`.env`
+```
+    # API configurations
+
+    API_URL=https://api.example.com
+    API_KEY=your_api_key_here
+
+    # Database configurations
+    DATABASE_URL=postgres://user:password@localhost:5432/mydatabase
+
+    # JWT Authentication configurations
+    JWT_SECRET=my_jwt_secret
+    JWT_ISSUER=https://my-issuer.com
+    JWT_AUDIENCE=https://my-audience.com
+
+    # Third-party service credentials
+    GOOGLE_CLIENT_ID=your_google_client_id
+    GOOGLE_CLIENT_SECRET=your_google_client_secret
+    GOOGLE_CLIENT_SECRET=your_callback_url
+```
+
+
+ ### To access environment variables directly:
+
+  You can access env variables directly using **process.env** in your code if:  
+
+   - Your application is small or you have **simple configuration needs**.
+   - You want to keep things lightweight without adding external dependencies.
+   - You’re deploying on a platform that easily handles environment variables, such as **cloud services** (AWS, Heroku) or **Docker containers**.
+   - Your configuration is **mostly static** and doesn’t require complex overrides or defaults.
+
+
+  **Syntax to refer to these variables in YAML** 
+  ```
+   <% process.env.VARIABLE_NAME %>   //with scripting
+  ```
+  **Syntax to refer to these variables in typescript**
+
+   ```
+   process.env.VARIABLE_NAME         //without scripting
+
+   ``` 

docs/microservices-framework/how-to/short-faqs.md

@@ -5,54 +5,11 @@
   With `godspeed clean` command you can remove all pre-compiled files from your `/dist` folder. It is useful to clean up the dist folder to remove old references to deleted/renamed files in `src`
 
 
-### How to handle secrets, api keys, connection_urls etc.?
-
-  You can add your own database connection string in .env file which is under root folder /.env
-  Open this file and specify your database connection string here.
-
-  Connection URL format: postgresql://username:password@host:port/database
-  Example : 
-   ```
-    MY_DB_URL: postgresql://postgres:postgres@localhost:5432/test
-   ```
-
-
-###  To access the environment variables defined in config/custom-environment-variables.yaml
+<!-- ### How to handle secrets, api keys, connection_urls etc.?
 
-You can read it in two ways:
-  Option1: directly from env
-  Option2: through config file
-  ```
-    const frontendUrl = process.env.FRONTEND_URL ;
-  ```
-  And then use this variable in your ts code as:
-  ```
-    redirectUrl = `${frontendUrl}/verify?userId=${userId}
-  ```
-  Here, in the above example, we are redirecting user to frontEnd i.e. localhost:3001 passing userId as query parameter 
+ 
+### How to export a variable in environment ? -->
 
-  You need to export this variable in the environment so that the variables can get value from your environment.
-  For Example, below is a sample of custom-environment-variables.yaml 
-  ```
-   jwt:
-    issuer: JWT_ISS
-    audience: JWT_AUD
-    secretOrKey: JWT_SECRET
-  ```
-  To export above defined variables to your environment, use the following syntax based on the environment which you are using:
-  For shell
-   ```
-    $ export JWT_SECRET=mysecret
-    $ export JWT_ISS= mycompany
-   ```
-  For windows powershell
-   ```
-    $env:JWT_SECRET= "mysecret"
-    $env:JWT_ISS= "mycompany"
-     
-   ```
-  After exporting the environment variable, you can access this variable in your project by using 
-  scripting <% config.jwt.issuer %>
 
 ### How to update CRUD APIs after change in db model?
 

sidebars.js

@@ -474,7 +474,7 @@ const sidebars = {
         },
         {
           type: "category",
-          label: "12. Configs and Mappings",
+          label: "12. Config and Mappings",
           items: [
             {
               type: "doc",
@@ -483,7 +483,12 @@ const sidebars = {
             },
             {
               type: "doc",
-              label: "12.2. Mappings",
+              label: "12.2. Env",
+              id: "microservices-framework/config-and-mappings/env",
+            },
+            {
+              type: "doc",
+              label: "12.3. Mappings",
               id: "microservices-framework/config-and-mappings/mappings",
             },
           ],