From a4d9211ffecc2e11af61a5c9483708d2fcdfe08e Mon Sep 17 00:00:00 2001 From: Vivian Phung Date: Sat, 22 Jun 2024 18:07:47 -0400 Subject: [PATCH] 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 | 223 +++--------------------------------- packages/backend/README.md | 77 ++++++++++++- packages/deployer/README.md | 11 +- packages/frontend/README.md | 79 +++++++++---- 4 files changed, 154 insertions(+), 236 deletions(-) diff --git a/README.md b/README.md index 557b96ea..7a080386 100644 --- a/README.md +++ b/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 - git clone git@github.com:snowball-tools/snowballtools-base.git - cd snowballtools-base - ``` +### Install dependencies -- Install dependencies in root +In the root of the project, run: - ```bash - yarn - ``` +```zsh +yarn +``` -- Build packages +### Build backend - ```bash - yarn build --ignore frontend - ``` +```zsh +yarn build --ignore-frontend +``` -Let us assume the following domains for backend and frontend - - Backend server: `api.snowballtools.com` - - Frontend app: `dashboard.snowballtools.com` +### Environment variables, running the development server, and deployment -- Configuration Files - - - 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//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//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 = - ``` - - - 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 = - ``` - - - 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 = - ``` - - - 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 - ``` +Follow the instructions in the README.md files of the [backend](packages/backend/README.md) and [frontend](packages/frontend/README.md) packages. diff --git a/packages/backend/README.md b/packages/backend/README.md index a91d0bb1..7c80b1c2 100644 --- a/packages/backend/README.md +++ b/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) diff --git a/packages/deployer/README.md b/packages/deployer/README.md index 8081ec0a..b5866c7e 100644 --- a/packages/deployer/README.md +++ b/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 ``` diff --git a/packages/frontend/README.md b/packages/frontend/README.md index 9d0b4bcd..d98a4dbf 100644 --- a/packages/frontend/README.md +++ b/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 -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh +### Install dependencies -## 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: - -- 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, - }, -}; +```zsh +yarn ``` -- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked` -- 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 +### Build backend + +```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)