|
| 1 | +# 🚀 QNet Explorer Deployment Guide |
| 2 | + |
| 3 | +## 📋 Overview |
| 4 | + |
| 5 | +The QNet Explorer is a Next.js-based blockchain explorer that provides a web interface for interacting with the QNet blockchain. After the project restructuring, all components are properly organized and ready for deployment. |
| 6 | + |
| 7 | +## 🏗️ Architecture |
| 8 | + |
| 9 | +``` |
| 10 | +QNet Explorer |
| 11 | +├── Frontend (Next.js) - Port 3000 |
| 12 | +│ ├── Web Interface |
| 13 | +│ ├── API Routes (/api/*) |
| 14 | +│ └── Real-time Updates |
| 15 | +└── Backend Integration |
| 16 | + ├── QNet Node API (Port 8545) |
| 17 | + ├── Blockchain Data |
| 18 | + └── WebSocket Connections |
| 19 | +``` |
| 20 | + |
| 21 | +## 🖥️ Local Development |
| 22 | + |
| 23 | +### Prerequisites |
| 24 | + |
| 25 | +- Node.js 18+ |
| 26 | +- npm or yarn |
| 27 | +- Git |
| 28 | + |
| 29 | +### Quick Start |
| 30 | + |
| 31 | +```bash |
| 32 | +# Clone repository |
| 33 | +git clone https://github.com/AIQnetLab/QNet-Blockchain.git |
| 34 | +cd QNet-Blockchain/applications/qnet-explorer/frontend |
| 35 | + |
| 36 | +# Install dependencies |
| 37 | +npm install |
| 38 | + |
| 39 | +# Start development server |
| 40 | +npm run dev |
| 41 | + |
| 42 | +# Access at http://localhost:3000 |
| 43 | +``` |
| 44 | + |
| 45 | +### Development Scripts |
| 46 | + |
| 47 | +```bash |
| 48 | +# Development with hot reload |
| 49 | +npm run dev |
| 50 | + |
| 51 | +# Development with Turbopack (faster) |
| 52 | +npm run dev:turbo |
| 53 | + |
| 54 | +# Build for production |
| 55 | +npm run build |
| 56 | + |
| 57 | +# Start production server |
| 58 | +npm start |
| 59 | + |
| 60 | +# Lint and format code |
| 61 | +npm run lint |
| 62 | +npm run format |
| 63 | +``` |
| 64 | + |
| 65 | +## 🌐 Production Deployment |
| 66 | + |
| 67 | +### Method 1: Simple Deployment Scripts |
| 68 | + |
| 69 | +#### Windows |
| 70 | +```bash |
| 71 | +# Run the deployment script |
| 72 | +deploy.bat |
| 73 | +``` |
| 74 | + |
| 75 | +#### Linux/macOS |
| 76 | +```bash |
| 77 | +# Make script executable |
| 78 | +chmod +x deploy.sh |
| 79 | + |
| 80 | +# Run deployment |
| 81 | +./deploy.sh |
| 82 | +``` |
| 83 | + |
| 84 | +### Method 2: Docker Deployment |
| 85 | + |
| 86 | +```bash |
| 87 | +# Build and run with Docker Compose |
| 88 | +docker-compose up -d |
| 89 | + |
| 90 | +# Check status |
| 91 | +docker-compose ps |
| 92 | + |
| 93 | +# View logs |
| 94 | +docker-compose logs -f |
| 95 | +``` |
| 96 | + |
| 97 | +### Method 3: Manual Deployment |
| 98 | + |
| 99 | +```bash |
| 100 | +# Install dependencies |
| 101 | +npm install |
| 102 | + |
| 103 | +# Build for production |
| 104 | +npm run build |
| 105 | + |
| 106 | +# Start production server |
| 107 | +npm start |
| 108 | +``` |
| 109 | + |
| 110 | +## 🔧 Configuration |
| 111 | + |
| 112 | +### Environment Variables |
| 113 | + |
| 114 | +Create `.env.local` file: |
| 115 | + |
| 116 | +```bash |
| 117 | +# API Configuration |
| 118 | +NEXT_PUBLIC_API_URL=http://localhost:8545 |
| 119 | +NEXT_PUBLIC_WS_URL=ws://localhost:8545/ws |
| 120 | + |
| 121 | +# Network Configuration |
| 122 | +NEXT_PUBLIC_NETWORK=mainnet |
| 123 | +NEXT_PUBLIC_CHAIN_ID=1 |
| 124 | + |
| 125 | +# Feature Flags |
| 126 | +NEXT_PUBLIC_ENABLE_FAUCET=true |
| 127 | +NEXT_PUBLIC_ENABLE_DAO=true |
| 128 | +NEXT_PUBLIC_ENABLE_STAKING=true |
| 129 | + |
| 130 | +# Analytics (Optional) |
| 131 | +NEXT_PUBLIC_GA_ID=your-google-analytics-id |
| 132 | +``` |
| 133 | + |
| 134 | +### Production Environment |
| 135 | + |
| 136 | +```bash |
| 137 | +# Production API endpoints |
| 138 | +NEXT_PUBLIC_API_URL=https://api.qnet.io |
| 139 | +NEXT_PUBLIC_WS_URL=wss://api.qnet.io/ws |
| 140 | +NEXT_PUBLIC_NETWORK=mainnet |
| 141 | + |
| 142 | +# Security |
| 143 | +NEXT_PUBLIC_ENABLE_ANALYTICS=true |
| 144 | +NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn |
| 145 | +``` |
| 146 | + |
| 147 | +## 📊 Monitoring |
| 148 | + |
| 149 | +### Health Checks |
| 150 | +```bash |
| 151 | +# Check application |
| 152 | +curl http://localhost:3000/api/health |
| 153 | + |
| 154 | +# Check specific endpoints |
| 155 | +curl http://localhost:3000/api/verify-build |
| 156 | +``` |
| 157 | + |
| 158 | +### Log Management |
| 159 | + |
| 160 | +```bash |
| 161 | +# PM2 logs |
| 162 | +pm2 logs qnet-explorer |
| 163 | + |
| 164 | +# Docker logs |
| 165 | +docker logs qnet-explorer |
| 166 | + |
| 167 | +# Nginx logs |
| 168 | +sudo tail -f /var/log/nginx/access.log |
| 169 | +sudo tail -f /var/log/nginx/error.log |
| 170 | +``` |
| 171 | + |
| 172 | +### Performance Monitoring |
| 173 | + |
| 174 | +```bash |
| 175 | +# PM2 monitoring |
| 176 | +pm2 monit |
| 177 | + |
| 178 | +# System resources |
| 179 | +htop |
| 180 | +df -h |
| 181 | +free -h |
| 182 | +``` |
| 183 | + |
| 184 | +### Backup & Updates |
| 185 | + |
| 186 | +```bash |
| 187 | +# Backup current deployment |
| 188 | +tar -czf qnet-explorer-backup-$(date +%Y%m%d).tar.gz /home/qnet/QNet-Blockchain |
| 189 | + |
| 190 | +# Update deployment |
| 191 | +cd /home/qnet/QNet-Blockchain |
| 192 | +git pull origin master |
| 193 | +cd applications/qnet-explorer/frontend |
| 194 | +npm ci --only=production |
| 195 | +npm run build |
| 196 | +pm2 restart qnet-explorer |
| 197 | +``` |
| 198 | + |
| 199 | +## 🔒 Security Considerations |
| 200 | + |
| 201 | +### SSL/TLS Configuration |
| 202 | + |
| 203 | +```bash |
| 204 | +# Install Certbot for Let's Encrypt |
| 205 | +sudo apt install certbot python3-certbot-nginx |
| 206 | + |
| 207 | +# Obtain SSL certificate |
| 208 | +sudo certbot --nginx -d your-domain.com |
| 209 | + |
| 210 | +# Auto-renewal |
| 211 | +sudo crontab -e |
| 212 | +# Add: 0 12 * * * /usr/bin/certbot renew --quiet |
| 213 | +``` |
| 214 | + |
| 215 | +### Firewall Configuration |
| 216 | + |
| 217 | +```bash |
| 218 | +# Configure UFW |
| 219 | +sudo ufw allow ssh |
| 220 | +sudo ufw allow 80 |
| 221 | +sudo ufw allow 443 |
| 222 | +sudo ufw enable |
| 223 | +``` |
| 224 | + |
| 225 | +### Security Headers |
| 226 | + |
| 227 | +Add to Nginx configuration: |
| 228 | + |
| 229 | +```nginx |
| 230 | +add_header X-Frame-Options "SAMEORIGIN" always; |
| 231 | +add_header X-XSS-Protection "1; mode=block" always; |
| 232 | +add_header X-Content-Type-Options "nosniff" always; |
| 233 | +add_header Referrer-Policy "no-referrer-when-downgrade" always; |
| 234 | +add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always; |
| 235 | +``` |
| 236 | + |
| 237 | +## 🚀 Available Features |
| 238 | + |
| 239 | +### Web Interface |
| 240 | +- **Blockchain Explorer**: Browse blocks, transactions, addresses |
| 241 | +- **Real-time Updates**: Live blockchain data |
| 242 | +- **Node Dashboard**: Monitor node status |
| 243 | +- **Wallet Integration**: Connect wallets |
| 244 | + |
| 245 | +### API Endpoints |
| 246 | +- `/api/activate` - Node activation |
| 247 | +- `/api/dao/proposals` - DAO proposals |
| 248 | +- `/api/dao/vote` - DAO voting |
| 249 | +- `/api/faucet/claim` - Token faucet |
| 250 | +- `/api/node/activate` - Node activation |
| 251 | +- `/api/verify-build` - Build verification |
| 252 | + |
| 253 | +### Advanced Features |
| 254 | +- **Matrix Rain Animation**: Quantum-themed UI effects |
| 255 | +- **Dark/Light Theme**: User preference themes |
| 256 | +- **Responsive Design**: Mobile and desktop optimized |
| 257 | +- **Performance Optimized**: Fast loading and rendering |
| 258 | + |
| 259 | +## 🔧 Troubleshooting |
| 260 | + |
| 261 | +### Common Issues |
| 262 | + |
| 263 | +#### Port Already in Use |
| 264 | +```bash |
| 265 | +# Find process using port 3000 |
| 266 | +sudo lsof -i :3000 |
| 267 | +# Kill process |
| 268 | +sudo kill -9 <PID> |
| 269 | +``` |
| 270 | + |
| 271 | +#### Build Failures |
| 272 | +```bash |
| 273 | +# Clear cache and rebuild |
| 274 | +rm -rf .next node_modules |
| 275 | +npm install |
| 276 | +npm run build |
| 277 | +``` |
| 278 | + |
| 279 | +#### API Connection Issues |
| 280 | +```bash |
| 281 | +# Check QNet node is running |
| 282 | +curl http://localhost:8545/health |
| 283 | + |
| 284 | +# Check network connectivity |
| 285 | +telnet localhost 8545 |
| 286 | +``` |
| 287 | + |
| 288 | +### Performance Issues |
| 289 | + |
| 290 | +```bash |
| 291 | +# Increase Node.js memory limit |
| 292 | +export NODE_OPTIONS="--max-old-space-size=4096" |
| 293 | + |
| 294 | +# Enable production optimizations |
| 295 | +export NODE_ENV=production |
| 296 | +``` |
| 297 | + |
| 298 | +## 📞 Support |
| 299 | + |
| 300 | +- **GitHub Issues**: https://github.com/AIQnetLab/QNet-Blockchain/issues |
| 301 | +- **Documentation**: See `/documentation` directory |
| 302 | +- **Community**: Join our Discord/Telegram |
| 303 | + |
| 304 | +--- |
| 305 | + |
| 306 | +**The QNet Explorer is fully functional and ready for deployment!** |
0 commit comments