laconic-deployer-frontend/readme.md

# Laconic Frontend

## Prerequisites

Ensure you have the following installed:
- [Node.js](https://nodejs.org/) (v18+)
- [pnpm](https://pnpm.io/) (v8+)
- [Git](https://git-scm.com/)
- [ngrok](https://ngrok.com/docs/getting-started/#2-install-the-ngrok-agent-cli)

## Project Structure

This monorepo contains several packages:

- `apps/deploy-fe`: Frontend Next.js application
- `apps/deployer`: Deployment service
- `services/gql-client`: GraphQL client library
- `services/ui`: Shared UI components
- `services/typescript-config`: Shared TypeScript configurations

## Getting Started

The following steps are for running the deploy app locally (using [laconicd mainnet chain](https://laconicd-mainnet-1.laconic.com/status)):

- Clone laconic-wallet-web repo
  ```bash
  git clone https://git.vdb.to/LaconicNetwork/laconic-wallet-web.git
  cd laconic-wallet-web
  ```

- Create .env
  ```bash
  cp .env.example .env
  ```

- Update values in `.env`
  ```
  # Not required since WalletConnect is not used in iframe integration 
  REACT_APP_WALLET_CONNECT_PROJECT_ID=

  REACT_APP_DEFAULT_GAS_PRICE=0.025
  
  # Reference: https://github.com/cosmos/cosmos-sdk/issues/16020
  REACT_APP_GAS_ADJUSTMENT=2
  REACT_APP_LACONICD_RPC_URL=https://laconicd-mainnet-1.laconic.com

  # URL of Deploy app frontend app that will run locally
  REACT_APP_ALLOWED_URLS=http://localhost:3000
  ```

- Install dependencies
  ```bash
  yarn install
  ```

- Build app
  ```bash
  yarn build
  ```

- Set env values in build
  ```bash
  yarn set-env
  ```

- Serve the build
  ```
  # Install package serve globally
  npm install -g serve

  # Serve the wallet build
  serve -s -l 4000 ./build
  ```

  Wallet will run at http://localhost:4000

- In a new terminal, clone repo for backend
  ```bash
  git clone https://git.vdb.to/cerc-io/snowballtools-base.git
  cd snowballtools-base
  ```

- Install deps and build
  ```bash
  yarn && yarn build --ignore frontend
  ```

- Create `packages/backend/environments/local.toml`
  ```bash
  cp packages/backend/environments/local.toml.example packages/backend/environments/local.toml
  ```

- Update values in `packages/backend/environments/local.toml`
  ```toml
  [server]
    host = "127.0.0.1"
    port = 8000
    gqlPath = "/graphql"
    [server.session]
      # Can be set to any random string
      secret = "RpwqcvFkLZ"
      # Frontend webapp URL origin
      appOriginUrl = "http://localhost:3000"
      # Set to true if server running behind proxy
      trustProxy = false
      # Backend URL hostname
      domain = "localhost"
  
  [database]
    dbPath = "db/snowball"
  
  [gitHub]
    webhookUrl = ""
    [gitHub.oAuth]
      clientId = "Ov23lihCWQvOORNxtebD"
      clientSecret = "139de35bdd610628289adcd99bb2c7c962a11c99"
  
  [registryConfig]
    fetchDeploymentRecordDelay = 5000
    checkAuctionStatusDelay = 5000
    restEndpoint = "https://laconicd-mainnet-1.laconic.com"
    gqlEndpoint = "https://laconicd-mainnet-1.laconic.com/api"
    chainId = "laconic-mainnet"
    # Set private key of account laconic13maulvmjxnyx3g855vk0lsv5aptf3rpxskynef
    # This account owns the bond and authority configured below
    privateKey = ""
    bondId = "230cfedda15e78edc8986dfcb870e1b618f65c56e38d2735476d2a8cb3f25e38"
    authority = "laconic"
    [registryConfig.fee]
      gasPrice = "0.001alnt"
  
  [auction]
    commitFee = "1000"
    commitsDuration = "60s"
    revealFee = "1000"
    revealsDuration = "60s"
    denom = "alnt"
  ```

- Run ngrok
  ```bash
  ngrok http 8000
  ```

- Set ngrok URL to `gitHub.webhookUrl` in config `packages/backend/environments/local.toml`
  - Example
    ```toml
    ...
    [gitHub]
      webhookUrl = "https://<ngrok-url>.ngrok-free.app"
    ...
    ```

- Run backend server
  ```bash
  cd packages/backend
  yarn start
  ```

- In a new terminal, clone repo for frontend (laconic-deployer-frontend)
  ```bash
  git clone https://git.vdb.to/NasSharaf/laconic-deployer-frontend.git
  cd laconic-deployer-frontend
  ```

- Install dependencies
  ```bash
  pnpm install
  ```

- Build dependecies for frontend app
  ```bash
  pnpm build:fe-compile
  ```

- Create a `.env.local` file in the `apps/deploy-fe` directory to configure environment variables:
  ```
  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
  CLERK_SECRET_KEY=your_clerk_secret
  NEXT_PUBLIC_WALLET_IFRAME_URL=http://localhost:4000
  NEXT_PUBLIC_LACONICD_CHAIN_ID=laconic-mainnet
  NEXT_PUBLIC_API_URL=http://localhost:8000
  NEXT_PUBLIC_GITHUB_BACKEND_CLIENT_ID=Ov23lihCWQvOORNxtebD
  ```
  Replace `your_clerk_key` and `your_clerk_secret` with actual values (<https://clerk.com/docs/quickstarts/nextjs-pages-router#set-your-clerk-api-keys>)

- Start the development server
  ```bash
  cd apps/deploy-fe
  pnpm dev
  ```

- The deploy frontend app will be now available at <http://localhost:3000>

### Fund wallet account

- Change directory to deployer package
  ```bash
  cd apps/deployer/
  ```

- Setup config for laconic-registry-cli in `packages/deployer/config.yml`
  ```yaml
  services:
    registry:
      rpcEndpoint: https://laconicd-mainnet-1.laconic.com
      gqlEndpoint: https://laconicd-mainnet-1.laconic.com/api
      # Set to private key of an account with funds
      # Private key of account laconic13maulvmjxnyx3g855vk0lsv5aptf3rpxskynef set in deployer backend can be used
      userKey:
      chainId: laconic-testnet-2
      gasPrice: 0.001alnt
  ```

- Get wallet account address at <http://localhost:4000> for `laconicd mainnet` network

- Run command to send tokens
  ```bash
  pnpm laconic registry tokens send --address <ACCOUNT_ADDRESS_FROM_WALLET> --type alnt --quantity 12960
  ```

- To check balance visit <https://explorer.laconic.com/laconic-mainnet/account/ACCOUNT_ADDRESS_FROM_WALLET>

### Misc

- To check for deployments in vaasl : <https://webapp-deployer-ui.apps.vaasl.io/>

- If deployment fails due to low bond balance
  - Change directory to deployer package
    ```bash
    cd apps/deployer/
    ```

  - Check balances
    ```bash
    # Account balance
    yarn laconic registry account get --address laconic13maulvmjxnyx3g855vk0lsv5aptf3rpxskynef

    # Bond balance
    yarn laconic registry bond get --id 230cfedda15e78edc8986dfcb870e1b618f65c56e38d2735476d2a8cb3f25e38
    ```

  - Command to refill bond

    ```bash
    yarn laconic registry bond refill --id 230cfedda15e78edc8986dfcb870e1b618f65c56e38d2735476d2a8cb3f25e38 --type alnt --quantity 10000000
    ```


## Architecture

### Frontend (Next.js App Router)

The frontend is built with:
- Next.js 15 with App Router
- React 19
- Clerk for authentication
- TailwindCSS for styling
- Radix UI components

### Authentication Flow (NEEDS DEVELOPMENT!!!)

1. User authenticates with Clerk (GitHub OAuth)
2. User connects wallet (Sign-In With Ethereum)
3. Backend validates and establishes a session

## Available Scripts

- `pnpm dev`: Start development servers
- `pnpm build`: Build all packages
- `pnpm lint`: Run linting
- `pnpm check-types`: Check TypeScript types

### GitHub Authentication

Make sure you have:
1. Connected your GitHub account in Clerk
2. Provided the necessary permissions for repository access
3. Set a fallback GitHub token in `.env.local` if needed for development

## Test deployment

- Install stack-orchestrator from <https://git.vdb.to/cerc-io/stack-orchestrator#install>

- Build the container for app
  
  ```bash
  laconic-so build-webapp --source-repo <path-to-app-repo>/laconic-deployer-frontend --base-container cerc/nextjs-base
  ```

- Create an env file as described in [previous steps](#3-configure-environment-variables)

- Run the webapp container locally
  
  ```bash
  docker run -p 3000:80 --env-file <path-to-env-file> cerc/laconic-deployer-frontend:local
  ```

- Scripts used for deployment
  - App container build : [build-webapp.sh](./build-webapp.sh)
  - Run app container : [run-webapp.sh](./run-webapp.sh)