From a8e1af2c13244693472bcc77889164fb1f6224aa Mon Sep 17 00:00:00 2001 From: defiQUG Date: Wed, 3 Dec 2025 21:42:21 -0800 Subject: [PATCH] Add environment configuration examples and quick start guide - Add backend/.env.example with all required and optional variables - Add frontend/.env.example with Next.js public variables - Create QUICK_START.md for team onboarding - Include submodule cloning instructions --- QUICK_START.md | 200 +++++++++++++++++++++++++++++++++++++++++++ backend/.env.example | 25 ++++++ 2 files changed, 225 insertions(+) create mode 100644 QUICK_START.md create mode 100644 backend/.env.example diff --git a/QUICK_START.md b/QUICK_START.md new file mode 100644 index 0000000..9b71649 --- /dev/null +++ b/QUICK_START.md @@ -0,0 +1,200 @@ +# ASLE Quick Start Guide + +Get up and running with the ASLE platform in minutes. + +## Prerequisites + +- Node.js 20+ +- Docker and Docker Compose (optional, for local services) +- PostgreSQL 15+ (or use Docker) +- Git with submodule support + +## Step 1: Clone Repository + +```bash +# Clone with submodules (IMPORTANT!) +git clone --recurse-submodules https://github.com/Order-of-Hospitallers/asle.git +cd asle + +# If you already cloned without submodules: +git submodule update --init --recursive +``` + +## Step 2: Start Infrastructure + +```bash +# Start PostgreSQL and Redis (if using Docker) +docker-compose up -d postgres redis +``` + +Or install PostgreSQL locally and create a database: +```bash +createdb asle +``` + +## Step 3: Backend Setup + +```bash +cd backend + +# Install dependencies +npm install + +# Copy environment file +cp .env.example .env + +# Edit .env with your configuration +# Minimum required: +# - DATABASE_URL +# - JWT_SECRET +# - RPC_URL +# - DIAMOND_ADDRESS (after deploying contracts) + +# Generate Prisma client +npm run prisma:generate + +# Run database migrations +npm run prisma:migrate + +# Initialize database +npm run setup:db + +# Create admin user +npm run setup:admin + +# Start backend (development) +npm run dev +``` + +Backend will run on `http://localhost:4000` + +## Step 4: Frontend Setup + +```bash +cd ../frontend + +# Install dependencies +npm install + +# Copy environment file +cp .env.example .env.local + +# Edit .env.local with your configuration +# Minimum required: +# - NEXT_PUBLIC_API_URL +# - NEXT_PUBLIC_DIAMOND_ADDRESS +# - NEXT_PUBLIC_RPC_URL + +# Start frontend (development) +npm run dev +``` + +Frontend will run on `http://localhost:3000` + +## Step 5: Deploy Contracts (Optional) + +```bash +cd ../contracts + +# Install Foundry dependencies +forge install + +# Build contracts +forge build + +# Run tests +forge test + +# Deploy (see DEPLOYMENT.md for details) +forge script script/Deploy.s.sol:DeployScript --rpc-url $RPC_URL --broadcast --private-key $PRIVATE_KEY +``` + +## Step 6: Access the Application + +- **Frontend Dashboard**: http://localhost:3000 +- **Admin Dashboard**: http://localhost:3000/admin +- **User DApp**: http://localhost:3000/dapp +- **Backend API**: http://localhost:4000/api +- **GraphQL Playground**: http://localhost:4000/graphql + +## Common Issues + +### Submodules Not Cloned + +If you see empty `contracts/` or `frontend/` directories: + +```bash +git submodule update --init --recursive +``` + +### Database Connection Error + +1. Verify PostgreSQL is running +2. Check `DATABASE_URL` in `backend/.env` +3. Ensure database exists: `createdb asle` + +### Port Already in Use + +Change `PORT` in `backend/.env` or kill the process: +```bash +lsof -i :4000 +kill -9 +``` + +### Missing Dependencies + +```bash +# Backend +cd backend && npm install + +# Frontend +cd frontend && npm install + +# Contracts +cd contracts && forge install +``` + +## Next Steps + +1. **Configure Environment**: Update all `.env` files with your API keys and configuration +2. **Deploy Contracts**: Deploy smart contracts to your target network +3. **Set Up KYC/AML**: Configure KYC/AML provider credentials (optional) +4. **Configure Push Notifications**: Set up push notification providers (optional) +5. **Review Documentation**: See [README.md](./README.md) and [DEPLOYMENT.md](./DEPLOYMENT.md) + +## Development Workflow + +### Making Changes + +1. **Backend Changes**: Edit files in `backend/src/`, changes auto-reload with `npm run dev` +2. **Frontend Changes**: Edit files in `frontend/app/` or `frontend/components/`, changes auto-reload +3. **Contract Changes**: Edit files in `contracts/src/`, run `forge build` and `forge test` + +### Running Tests + +```bash +# Backend tests +cd backend && npm test + +# Contract tests +cd contracts && forge test +``` + +### Database Migrations + +```bash +cd backend +npm run prisma:migrate dev --name migration_name +``` + +## Production Deployment + +See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed production deployment instructions. + +## Getting Help + +- **Documentation**: See `docs/` directory +- **API Reference**: See [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) +- **Project Structure**: See [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) +- **Submodules**: See [SUBMODULE_SETUP.md](./SUBMODULE_SETUP.md) + diff --git a/backend/.env.example b/backend/.env.example new file mode 100644 index 0000000..280e0ed --- /dev/null +++ b/backend/.env.example @@ -0,0 +1,25 @@ +# ASLE Backend Environment Configuration +# Copy this file to .env and fill in your values + +# REQUIRED +DATABASE_URL="postgresql://user:password@localhost:5432/asle?schema=public" +JWT_SECRET="your-super-secret-jwt-key-change-this-in-production" +PORT=4000 +NODE_ENV=development +LOG_LEVEL=info +RPC_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY" +DIAMOND_ADDRESS="0x0000000000000000000000000000000000000000" +CHAIN_ID=1 + +# OPTIONAL: Push Notifications +# FIREBASE_SERVICE_ACCOUNT="path/to/service-account.json" +# ONESIGNAL_APP_ID="your-onesignal-app-id" +# ONESIGNAL_API_KEY="your-onesignal-api-key" + +# OPTIONAL: KYC/AML Providers +# SUMSUB_APP_TOKEN="your-sumsub-app-token" +# JUMIO_API_TOKEN="your-jumio-api-token" +# VERIFF_API_KEY="your-veriff-api-key" + +# OPTIONAL: Redis +# REDIS_URL="redis://localhost:6379"