Refactor(README.md) (#217)

This pull request refactors the main `README.md` by removing detailed backend and frontend setup instructions and adding separate `README.md` files for the backend and frontend with their specific setup and deployment instructions. This makes the main `README.md` cleaner and directs users to specific READMEs for backend and frontend setups.

---

README.md

@@ -1,220 +1,23 @@
 # snowballtools-base
 
-## Setup
+This is a [yarn workspace](https://yarnpkg.com/features/workspaces) monorepo for the dashboard.
 
-- Clone the `snowballtools-base` repo
+## Getting Started
 
-  ```bash
+### Install dependencies
-  git clone git@github.com:snowball-tools/snowballtools-base.git
-  cd snowballtools-base
-  ```
 
-- Install dependencies in root
+In the root of the project, run:
 
-  ```bash
+```zsh
 yarn
 ```
 
-- Build packages
+### Build backend
 
-  ```bash
+```zsh
-  yarn build --ignore frontend
+yarn build --ignore-frontend
 ```
 
-Let us assume the following domains for backend and frontend
+### Environment variables, running the development server, and deployment
-  - Backend server: `api.snowballtools.com`
-  - Frontend app: `dashboard.snowballtools.com`
 
-- Configuration Files
+Follow the instructions in the README.md files of the [backend](packages/backend/README.md) and [frontend](packages/frontend/README.md) packages.
-
-  - For Backend:
-  
-    ```bash
-    cp packages/backend/environments/local.toml.example packages/backend/environments/local.toml
-    ```
-
-    - Production
-      
-      - Update the following in backend [config file](packages/backend/environments/local.toml)
-        
-        ```toml
-        [server]
-          ...
-          [server.session]
-            # Secret should be changed to a different random string
-            secret = "p4yfpkqnddkui2iw7t6hbhwq74lbqs7sidnc382"
-            # Set URL of the frontend app
-            appOriginUrl = "https://dashboard.snowballtools.com"
-            # Set to true for session cookies to work behind proxy
-            trustProxy = true
-            # Set empty domain when using secure connection
-            domain = ""
-        ```
-      
-      - Set `gitHub.oAuth.clientId` and `gitHub.oAuth.clientSecret` in backend [config file](packages/backend/environments/local.toml)
-        - [OAuth App Creation](https://github.com/organizations/<org>/settings/applications/new)
-          - Homepage URL: `https://dashboard.snowballtools.com`
-          - Authorization callback URL: `https://dashboard.snowballtools.com/organization/projects/create`
-          - Generate a new client secret after app is created
-      
-      - Set `gitHub.webhookUrl` in backend [config file](packages/backend/environments/local.toml)
-      
-        ```toml
-        [gitHub]
-          webhookUrl = "https://api.snowballtools.com"
-        ```
-      
-      - Let us assume domain for Laconicd to be `api.laconic.com` and set the following in backend [config file](packages/backend/environments/local.toml)
-      
-        ```toml
-        [registryConfig]
-          fetchDeploymentRecordDelay = 5000
-          # Use actual port for REST endpoint
-          restEndpoint = "http://api.laconic.com:1317"
-          # Use actual port for GQL endpoint
-          gqlEndpoint = "http://api.laconic.com:9473/api"
-          # Set private key of account to be used in Laconicd
-          privateKey = "0wtu92cd4f1y791ezpjwgzzazni4dmd3q3mzqc3t6i6r9v06ji784tey6hwmnn69"
-          # Set Bond ID to be used for publishing records
-          bondId = "8xk8c2pb61kajwixpm223zvptr2x2ncajq0vd998p6aqhvqqep2reu6pik245epf"
-          chainId = "laconic_9000-1"
-          # Set authority that is existing in the chain
-          authority = "laconic"
-          [registryConfig.fee]
-            amount = "200000"
-            denom = "aphoton"
-            gas = "750000"
-        ```
-
-    - Development
-    
-      - Set `gitHub.oAuth.clientId` and `gitHub.oAuth.clientSecret` in backend [config file](packages/backend/environments/local.toml)
-        - [OAuth App Creation](https://github.com/organizations/<org>/settings/applications/new)
-          - Homepage URL: `http://localhost:3000`
-          - Authorization callback URL: `http://localhost:3000/organization/projects/create`
-          - Generate a new client secret after app is created
-      
-      - Setup Laconicd
-        - Run the laconicd stack following this [doc](https://git.vdb.to/cerc-io/stack-orchestrator/src/branch/main/docs/laconicd-with-console.md)
-        - Get the private key and set `registryConfig.privateKey` in backend [config file](packages/backend/environments/local.toml)
-      
-          ```bash
-          laconic-so deployment --dir laconic-loaded-deployment exec laconicd "laconicd keys export mykey --unarmored-hex --unsafe"
-          # WARNING: The private key will be exported as an unarmored hexadecimal string. USE AT YOUR OWN RISK. Continue? [y/N]: y
-          # 754cca7b4b729a99d156913aea95366411d072856666e95ba09ef6c664357d81
-          ```
-
-        - Set authority in `registryConfig.authority` in backend [config file](packages/backend/environments/local.toml)
-
-        - Run the script to create bond, reserve the authority and set authority bond
-      
-          ```bash
-          yarn test:registry:init
-          # snowball:initialize-registry bondId: 6af0ab81973b93d3511ae79841756fb5da3fd2f70ea1279e81fae7c9b19af6c4 +0ms
-          ```
-      
-          - Get the bond id and set `registryConfig.bondId` in backend [config file](packages/backend/environments/local.toml)
-      
-      - Setup ngrok for GitHub webhooks
-        - [ngrok getting started](https://ngrok.com/docs/getting-started/)
-        - Start ngrok and point to backend server endpoint
-      
-          ```bash
-          ngrok http http://localhost:8000
-          ```
-      
-        - Look for the forwarding URL in ngrok
-      
-          ```bash
-          Forwarding                    https://19c1-61-95-158-116.ngrok-free.app -> http://localhost:8000
-          ```
-      
-        - Set `gitHub.webhookUrl` in backend [config file](packages/backend/environments/local.toml)
-      
-          ```toml
-          [gitHub]
-            webhookUrl = "https://19c1-61-95-158-116.ngrok-free.app"
-          ```
-
-  - For Frontend:
-  
-    ```bash
-    cp packages/frontend/.env.example packages/frontend/.env
-    ```
-
-    - Copy the GitHub OAuth app client ID from previous steps and set it in frontend [.env](packages/frontend/.env) file
-
-      ```env
-      VITE_GITHUB_CLIENT_ID = <CLIENT_ID>
-      ```
-    
-    - Set `VITE_GITHUB_PWA_TEMPLATE_REPO` and `VITE_GITHUB_IMAGE_UPLOAD_PWA_TEMPLATE_REPO` in [.env](packages/frontend/.env) file
-    
-      ```env
-      VITE_GITHUB_PWA_TEMPLATE_REPO = 'cerc-io/test-progressive-web-app'   # Set actual owner/name of the template repo that will be used for creating new repo
-      VITE_GITHUB_IMAGE_UPLOAD_PWA_TEMPLATE_REPO = 'cerc-io/image-upload-pwa-example'  # Set actual owner/name of the template repo that will be used for creating new repo
-      ```
-
-    - Production
-    
-      - Set the following values in [.env](packages/frontend/.env) file
-      
-        ```env
-        VITE_SERVER_URL = 'https://api.snowballtools.com'   # Backend server endpoint
-        ```
-      
-      - Sign in to [wallet connect](https://cloud.walletconnect.com/sign-in) to create a project ID
-        - Create a project and add information to use wallet connect SDK
-          - Add project name and select project type as `App`
-          - Set project home page URL to `https://dashboard.snowballtools.com`
-        - On creation of project, use the `Project ID` and set it in `VITE_WALLET_CONNECT_ID` in [.env](packages/frontend/.env) file
-      
-        ```env
-        VITE_WALLET_CONNECT_ID = <PROJECT_ID>
-        ```
-      
-      - Build the React application
-      
-        ```bash
-        yarn build
-        ```
-      
-      - Use a web server for hosting static built files
-      
-        ```bash
-        python3 -m http.server -d build 3000
-        ```
-
-    - Development
-    
-      - Copy the graphQL endpoint from terminal and add the endpoint in the [.env](packages/frontend/.env) file present in `packages/frontend`
-      
-        ```env
-        VITE_SERVER_URL = 'http://localhost:8000'
-        ```
-      
-      - Sign in to [wallet connect](https://cloud.walletconnect.com/sign-in) to create a project ID.
-        - Create a project and add information to use wallet connect SDK
-          - Add project name and select project type as `App`
-          - Project home page URL is not required to be set
-        - On creation of project, use the `Project ID` and set it in `VITE_WALLET_CONNECT_ID` in [.env](packages/frontend/.env) file
-      
-        ```env
-        VITE_WALLET_CONNECT_ID = <Project_ID>
-        ```
-      
-      - The React application will be running in `http://localhost:3000/`
-
-## Development
-
-- Start the backend server
-
-  ```bash
-  yarn start:backend
-  ```
-
-- Start the frontend
-
-  ```bash
-  yarn start
-  ```

packages/backend/README.md

@@ -1 +1,76 @@
-# Backend for Snowball Tools
+# backend
+
+This backend is a [node.js](https://nodejs.org/) [express.js](https://expressjs.com/) [apollo server](https://www.apollographql.com/docs/apollo-server/) project in a [yarn workspace](https://yarnpkg.com/features/workspaces).
+
+## Getting Started
+
+### Install dependencies
+
+In the root of the project, run:
+
+```zsh
+yarn
+```
+
+### Build backend
+
+```zsh
+yarn build --ignore-frontend
+```
+
+### Environment variables
+
+#### Local
+
+Copy the `envionments/local.toml.example` file to `envionments/local.toml`:
+
+```zsh
+cp envionments/local.toml.example envionments/local.toml
+```
+
+#### Staging environment variables
+
+In the deployment repository, update staging [staging/configmaps/config/prod.toml](https://git.vdb.to/cerc-io/snowballtools-base-api-deployments/src/commit/318c2bc09f334dca79c3501838512749f9431bf1/deployments/staging/configmaps/config/prod.toml)
+
+#### Production environment variables
+
+In the deployment repository, update production [production/configmaps/config/prod.toml](https://git.vdb.to/cerc-io/snowballtools-base-api-deployments/src/commit/318c2bc09f334dca79c3501838512749f9431bf1/deployments/production/configmaps/config/prod.toml)
+
+### Run development server
+
+```zsh
+yarn start
+```
+
+## Deployment
+
+Clone the deployer repository:
+
+```zsh
+git clone git@git.vdb.to:cerc-io/snowballtools-base-api-deployments.git
+```
+
+### Staging
+
+```zsh
+echo trigger >> .gitea/workflows/triggers/staging-deploy
+git commit -a -m "Deploy v0.0.8"  # replace with version number
+git push
+```
+
+### Production
+
+```zsh
+echo trigger >> .gitea/workflows/triggers/production-deploy
+git commit -a -m "Deploy v0.0.8" # replace with version number
+git push
+```
+
+### Deployment status
+
+Dumb for now
+
+- [Staging](https://snowballtools-base-api.staging.apps.snowballtools.com/staging/version)
+- [Production](https://snowballtools-base-api.apps.snowballtools.com/staging/version)
+
+Update version number manually in [routes/staging.ts](/packages/backend/src/routes/staging.ts)

packages/deployer/README.md

@@ -1,9 +1,11 @@
 # deployer
 
 - Install dependencies
+
   ```bash
   yarn
   ```
+
   ```bash
   brew install jq # if you do not have jq installed already
   ```
@@ -12,13 +14,13 @@
 
   - To deploy frontend app to `dashboard.staging.apps.snowballtools.com`
 
-    ```
+    ```bash
     ./deploy-frontend.staging.sh
     ```
   
   - To deploy frontend app to `dashboard.apps.snowballtools.com`
 
-    ```
+    ```bash
     ./deploy-frontend.sh
     ```
 
@@ -27,6 +29,7 @@
 ## Notes
 
 - Any config env can be updated in [records/application-deployment-request.yml](records/application-deployment-request.yml)
+
   ```yml
   record:
     ...
@@ -35,6 +38,7 @@
         LACONIC_HOSTED_CONFIG_app_server_url: https://snowballtools-base-api-001.apps.snowballtools.com
         ...
   ```
+
   - On changing `LACONIC_HOSTED_CONFIG_app_github_clientid`, the GitHub client ID and secret need to be changed in backend config too
 
 ## Troubleshoot
@@ -44,6 +48,7 @@
 
 - If deployment fails due to low bond balance
   - Check balances
+
     ```bash
     # Account balance
     yarn laconic cns account get
@@ -51,7 +56,9 @@
     # Bond balance
     yarn laconic cns bond get --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32
     ```
+
   - Command to refill bond
+
     ```bash
     yarn laconic cns bond refill --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32 --type aphoton --quantity 10000000
     ```

packages/frontend/README.md

@@ -1,30 +1,63 @@
-# React + TypeScript + Vite
+# frontend
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+This is a [vite](https://vitejs.dev/) [react](https://reactjs.org/) [nextjs](https://nextjs.org/) project in a [yarn workspace](https://yarnpkg.com/features/workspaces).
 
-Currently, two official plugins are available:
+## Getting Started
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
+### Install dependencies
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
 
-## Expanding the ESLint configuration
+In the root of the project, run:
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+```zsh
-
+yarn
-- Configure the top-level `parserOptions` property like this:
-
-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-  },
-};
 ```
 
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
+### Build backend
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
+
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+```zsh
+yarn build --ignore-frontend
+```
+
+### Environment variables
+
+#### Local
+
+Copy the `.env.example` file to `.env`:
+
+```zsh
+cp .env.example .env
+```
+
+#### Staging environment variables
+
+Change in [deployer/deploy-frontend.staging.sh](/packages/deployer/deploy-frontend.staging.sh)
+
+#### Production environment variables
+
+Change in [deployer/deploy-frontend.sh](/packages/deployer/deploy-frontend.sh)
+
+### Run development server
+
+```zsh
+yarn dev
+```
+
+## Deployment
+
+From the root of the project, run:
+
+### Staging
+
+```zsh
+cd packages/deployer && ./deploy-frontend.staging.sh
+```
+
+### Production
+
+```zsh
+cd packages/deployer && ./deploy-frontend.sh
+```
+
+### Deployment status
+
+Check the status of the deployment [here](https://webapp-deployer.apps.snowballtools.com)