# Getting started

Ensure you have the following pre-requisites installed and ready:

• Bun v1.0+ (required - only supported runtime and package manager)
• PostgreSQL 11+ running locally on port 5432, with a default admin user called postgres.
• Foundry for smart contract development.
• Git for version control.

Clone or fork the QuickDapp repository from GitHub:

git clone https://github.com/QuickDapp/quickdapp-v3.git
cd quickdapp-v3

In the project folder, let's install the dependencies:

bun install

By default, QuickDapp assumes the existence of a PostgreSQL database. The default connection parameters (defined in the .env file) are:

• host: localhost
• port: 5432
• user: postgres
• db: quickdapp_dev

If you haven't already, create the quickdapp_dev database, ensuring the postgres user has full system-level privileged access to it:

psql -U postgres -c 'CREATE DATABASE quickdapp_dev'

Let's get the dev database setup:

bun run db push

This command uses DrizzleORM to set up your database schema based on the definitions in src/server/db/schema.ts.

QuickDapp includes a sample ERC-20 token factory contract for local development. The contracts are located in the sample-contracts/ directory and use a simple factory pattern (not Diamond Standard).

If you haven't installed Foundry yet:

curl -L https://foundry.paradigm.xyz | bash
foundryup

In a new terminal, start the local Hardhat development node:

cd sample-contracts
bun devnet.ts

This starts a local blockchain on http://localhost:8545 with pre-funded test accounts.

In another terminal, deploy the ERC-20 factory contract:

cd sample-contracts
bun deploy.ts

This will:

• Build the contracts using Foundry
• Deploy the ERC-20Factory contract to your local node
• Automatically save the contract address to ../.env.local

The factory contract allows you to deploy custom ERC-20 tokens through the QuickDapp interface.

The local blockchain pre-funds test accounts using this mnemonic:

test test test test test test test test test test test junk

Import this mnemonic into your browser wallet (like MetaMask) to access pre-funded test accounts.

You'll also need to add the local network to your wallet:

• Network Name: Localhost 8545
• RPC URL: http://localhost:8545
• Chain ID: 31337
• Currency Symbol: ETH

Now start the QuickDapp development server:

bun run dev

This will:

• Start the backend server on http://localhost:3000
• GraphQL endpoint at http://localhost:3000/graphql and health at http://localhost:3000/health
• Start the Vite frontend development server on http://localhost:5173
• Generate contract ABIs and copy static assets
• Enable hot reload for both frontend and backend changes

The development server provides live reloading for an optimal development experience.

Goto http://localhost:5173 in your Metamask-enabled browser to interact with the dapp!

The development setup includes:

• Full Web3 wallet integration via RainbowKit
• GraphQL API with authentication
• Real-time WebSocket connections
• Background job processing
• Comprehensive logging

QuickDapp includes a basic test framework. Run tests with:

bun run test

You can add your own tests to the tests/ directory. The test framework includes database isolation, server lifecycle management, and GraphQL testing utilities.

The following steps all deal with deploying our dapp to production.

We will do the following:

• Deploy smart contracts to Sepolia test network.
• Build the application for production.
• Deploy using Docker containers or binary builds.
• Use a hosted PostgreSQL database as the production database.

We will setup a PostgreSQL database for production use. You can use any PostgreSQL hosting service such as:

• DigitalOcean Managed Databases
• AWS RDS
• Railway
• Supabase

Once you have your production database connection string, add it to your .env.production file (or create a production environment file):

DATABASE_URL="postgresql://user:password@host:5432/database"

Now setup the production database schema:

bun run db migrate

Deploy the ERC-20 factory contract to Sepolia testnet for production use.

1. Get Sepolia ETH from the Sepolia faucet
2. Get a Sepolia RPC endpoint from Alchemy or Infura

Add these to your shell environment or .env.production:

CHAIN=sepolia
CHAIN_RPC_ENDPOINT="https://sepolia.infura.io/v3/your-api-key"
SERVER_WALLET_PRIVATE_KEY="0x..." # Your deployment wallet private key

cd sample-contracts
bun deploy.ts

This will:

• Deploy the ERC-20Factory contract to Sepolia
• Save the contract address to ../.env.production
• Display the deployed contract address

The deployed factory address will be automatically saved to your environment configuration for production use.

Note: This step is optional, and is useful if you want to debug some production issues locally

In the project folder, build the production apps:

bun run build
# Optionally bundle client into server static assets so server serves the SPA:
# bun run build --bundle

Now, run the production apps:

bun run prod

Now goto http://localhost:3000 in your Metamask-enabled browser to interact with the dapp. You will need to connect to the Sepolia test network in your wallet.

QuickDapp supports several deployment options:

Option A: Binary deployment Build a self-contained binary with embedded assets:

bun run build
# Binaries are created automatically in dist/binaries/

Option B: Docker deployment Build and run as Docker containers:

docker build -t quickdapp .
docker run -p 3000:3000 quickdapp

See the deployment documentation for detailed guides on various deployment strategies.

Congratulations! your dapp is now available on the web in production mode.

Now that you have QuickDapp running, explore the documentation to learn about:

• Backend architecture - Understanding the ServerApp pattern and database layer
• Frontend development - Building React components and Web3 integrations
• Worker system - Adding background jobs and cron tasks
• Command line tools - Development and deployment commands
• Testing - Writing and running tests