Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added troubleshooting part #72

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+136 −11
Open

Added troubleshooting part #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 135 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Fair fund docs backup

# FairFund - Blockchain-based Community Funding Platform

## Table of Contents
Expand All @@ -11,7 +13,8 @@
7. [Deployment](#deployment)
8. [Future Improvements](#future-improvements)
9. [Contributing](#contributing)
10. [Community](#community)
10. [Troublesooting](#troubleshooting)
11. [Community](#community)

## Introduction

Expand Down Expand Up @@ -84,7 +87,7 @@ FairFund is a blockchain based platform for community-driven funding. Users can
make deploy-sepolia
```

### Frontend
### Frontend

1. **Navigate to the Web App Directory**:

Expand All @@ -107,6 +110,7 @@ FairFund is a blockchain based platform for community-driven funding. Users can
- If using a local instance of PostgreSQL, update the `POSTGRES_PRISMA_URL` and `POSTGRES_URL_NON_POOLING` with the correct connection url for the local postgreSQL.

NextAuth:

- Generate a secure `NEXTAUTH_SECRET` by running the following command in the terminal

```bash
Expand All @@ -115,22 +119,18 @@ FairFund is a blockchain based platform for community-driven funding. Users can

- For local development `NEXTAUTH_URL` will be `http://localhost:3000`

5. **To start local instance of postgreSQL database (with docker)**:

4. **To start local instance of postgreSQL database (with docker)**:

1. Start docker desktop
2. Run `docker compose up`


6. **Run the Development Server**:

5. **Run the Development Server**:

```bash
npm run dev
```


7. **Access the Web App**:
6. **Access the Web App**:

- Open your browser and navigate to `http://localhost:3000`.

Expand Down Expand Up @@ -208,7 +208,7 @@ Smart contract documentation can be found [here](/app/blockchain/README.md).

### Test Deployed Instances

- **Smart Contract**: [Polygon Mainnet](https://polygonscan.com/address/0xb6dc3af544303f41478821c0dfb9af57c278cb34)
- **Smart Contract**: [Polygon Amoy Testnet](https://www.oklink.com/amoy/address/0xde65b790a754720078b5a503783d025f28747246/contract)
- **Frontend**: [FairFund](https://fairfund.stability.nexus)

## Future Improvements
Expand Down Expand Up @@ -242,6 +242,131 @@ We welcome additional suggestions! Join our Discord: [Discord Link](https://disc
10. Open a pull request to the `v2` branch
11. Provide a detailed description of your changes in the PR, including videos and images if applicable

## Troubleshooting

This guide will serve as a solution to the common problems which may arise while setting up the project so follow along-

### Common Setup Issues

NOTE: Always make sure your .env file created in the root folder and has correct credentials for smooth running of the project as followed by the .env.example file

#### 1. Docker Compose Fails to Start PostgreSQL

Case 1: Connection errors in web-app logs

Solutions: Verify Docker Desktop is running

- **Check if port 5432 is occupied:**

\_ **macOS/Linux:** Open your terminal and run the command: `lsof -i :5432`. This command lists any processes using port 5432.

- **Windows:** Open Command Prompt or PowerShell as an administrator and run: `netstat -ano | findstr :5432`. This will show the processes using the port along with their PIDs. You can then use Task Manager to identify and close the process.

- **Verify Docker Compose Installation:** The error "command not found: docker-compose" indicates that Docker Compose isn't installed or accessible.

- **If using Docker Desktop:** Docker Compose is usually included. Ensure it's enabled in Docker Desktop's settings. \* **If using a separate installation:** Follow the official Docker Compose installation guide for your operating system: [https://docs.docker.com/compose/install/]

```
lsof -i :5432
```

Remove existing containers:

```
docker-compose down -v
```

##### Note:

If facing hard times using docker then it would be wise to get postgres connection string and prisma connection url from neon.tech for free. By sigining up and creating a project name of your choice and getting your connection strings.

##### 1.1 Dependency Installation Failures

- Problem: forge install errors
- Solution: Ensure Foundry is updated to latest version

```
foundryup
```

- Verify network connectivity for GitHub dependencies

#### 2. Smart Contract Tests Fail

Case 2: forge test errors
Solutions: Update dependencies

```
forge update

# Restart Anvil chain

pkill anvil && anvil
```

#### 3. Frontend Environment Issues

Case 3: NextAuth/NEXTAUTH_SECRET errors
Solutions: Regenerate secret:

```
openssl rand -base64 32
```

Note: Ensure .env matches .env.example structure

#### 4. Wallet Connection Problems

Case 4: SIWE authentication failures
Solutions:
Clear browser cache
Verify wallet network matches application chain (Amoy Testnet)

### Codebase Assumptions

#### 1. Dependency Versions

The project assumes:
-> Node.js ≥18.x (LTS version recommended)
-> Foundry ≥0.2.0
-> Docker ≥24.0+

#### 2. Blockchain Knowledge

Developers should understand:
-> Foundry Framework
-> Basic Solidity patterns
-> ERC-20 token standards
-> Wallet authentication flows (SIWE)

- Contracts are deployed on Polygon Amoy testnet by default
- Test transactions require MATIC on Amoy network

#### 3. Local Environment

-> PostgreSQL is managed via Docker
-> All blockchain interactions use test ETH sepolia
-> Frontend auto-reloads contract ABIs after make mock-all

#### 4. Testing

-> Smart contracts use Foundry's cheatcodes
-> Frontend tests assume Metamask test accounts
-> End-to-end tests require local Anvil chain

#### 5. Common Configuration Pitfalls

- Anvil local chain must run on default port 8545
- Frontend expects contract ABIs in /web-app/abi/ directory
- All environment variables are case-sensitive

#### 6. Codebase Assumptions

- Foundry v0.2.0+ required for Solidity ^0.8.20 support
- PostgreSQL 15+ required for Prisma ORM compatibility

For additional support reach out to us via discord channel

## Community

- [Stability Nexus](https://docs.stability.nexus/)
Expand Down
2 changes: 1 addition & 1 deletion app/web-app/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ NEXT_PUBLIC_WEBSITE_DESCRIPTION="FairFund is a blockchain based platform for com
NEXT_PUBLIC_NETWORK=foundry
NEXT_PUBLIC_SIGN_IN_STATEMENT="SignIn to FairFund."

# PostgreSQL URLs (Default Docker-based setup uses 'development' password. Use your local PostgreSQL password if running locally)
# PostgreSQL URLs (Default Docker-based setup uses 'development' password. Use your local PostgreSQL password if running locally) Otherwise you can get this string from neon.tech for free.
POSTGRES_PRISMA_URL="postgres://postgres:development@localhost:5432/dev-db"
POSTGRES_URL_NON_POOLING="postgres://postgres:development@localhost:5432/dev-db"

Expand Down