forked from cerc-io/snowballtools-base
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. ---
This commit is contained in:
Vivian Phung
GitHub
parent
af31fac3ee
commit
a4d9211ffe
223
README.md
223
README.md
@ -1,220 +1,23 @@
|
|||||||
# snowballtools-base
|
# 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
|
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
|
|
||||||
```
|
|
||||||
|
|||||||
@ -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)
|
||||||
|
|||||||
@ -1,9 +1,11 @@
|
|||||||
# deployer
|
# deployer
|
||||||
|
|
||||||
- Install dependencies
|
- Install dependencies
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yarn
|
yarn
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
brew install jq # if you do not have jq installed already
|
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`
|
- To deploy frontend app to `dashboard.staging.apps.snowballtools.com`
|
||||||
|
|
||||||
```
|
```bash
|
||||||
./deploy-frontend.staging.sh
|
./deploy-frontend.staging.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
- To deploy frontend app to `dashboard.apps.snowballtools.com`
|
- To deploy frontend app to `dashboard.apps.snowballtools.com`
|
||||||
|
|
||||||
```
|
```bash
|
||||||
./deploy-frontend.sh
|
./deploy-frontend.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -27,6 +29,7 @@
|
|||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
- Any config env can be updated in [records/application-deployment-request.yml](records/application-deployment-request.yml)
|
- Any config env can be updated in [records/application-deployment-request.yml](records/application-deployment-request.yml)
|
||||||
|
|
||||||
```yml
|
```yml
|
||||||
record:
|
record:
|
||||||
...
|
...
|
||||||
@ -35,6 +38,7 @@
|
|||||||
LACONIC_HOSTED_CONFIG_app_server_url: https://snowballtools-base-api-001.apps.snowballtools.com
|
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
|
- On changing `LACONIC_HOSTED_CONFIG_app_github_clientid`, the GitHub client ID and secret need to be changed in backend config too
|
||||||
|
|
||||||
## Troubleshoot
|
## Troubleshoot
|
||||||
@ -44,6 +48,7 @@
|
|||||||
|
|
||||||
- If deployment fails due to low bond balance
|
- If deployment fails due to low bond balance
|
||||||
- Check balances
|
- Check balances
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Account balance
|
# Account balance
|
||||||
yarn laconic cns account get
|
yarn laconic cns account get
|
||||||
@ -51,7 +56,9 @@
|
|||||||
# Bond balance
|
# Bond balance
|
||||||
yarn laconic cns bond get --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32
|
yarn laconic cns bond get --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32
|
||||||
```
|
```
|
||||||
|
|
||||||
- Command to refill bond
|
- Command to refill bond
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yarn laconic cns bond refill --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32 --type aphoton --quantity 10000000
|
yarn laconic cns bond refill --id 99c0e9aec0ac1b8187faa579be3b54f93fafb6060ac1fd29170b860df605be32 --type aphoton --quantity 10000000
|
||||||
```
|
```
|
||||||
|
|||||||
@ -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)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user