Skip to main content

Getting Started

This guide will help you set up and run the complete Qprint platform locally for development.

Prerequisites​

Before starting, install the following:

ToolVersionDownload
Go1.21+https://golang.org/dl/
Node.js18+https://nodejs.org/
PostgreSQL12+https://www.postgresql.org/download/
Flutter3.10+https://flutter.dev/docs/get-started/install
GitLatesthttps://git-scm.com/

Platform-Specific Requirements​

For Windows Shopkeeper App Printing:

  • SumatraPDF (required) – Silent printing
  • LibreOffice (optional) – Word/PPT conversion

Quick Start​

1. Clone the Repository​

git clone <repository-url>
cd Qprint_antiGravity

2. Database Setup​

Create the PostgreSQL database:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE filesharing;

# Exit psql
\q

Or use command-line:

psql -U postgres -c "CREATE DATABASE filesharing;"

3. Backend Setup​

cd backend

# Install Go dependencies
go mod download

# Create .env file
# Copy and edit the example below or see Environment Variables docs

Create backend/.env:

PORT=8080
DATABASE_URL=postgres://postgres:password@localhost:5432/filesharing?sslmode=disable
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters-long-here
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

# Payment (Razorpay)
RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxxxxx
RAZORPAY_KEY_SECRET=your_razorpay_secret
RAZORPAY_WEBHOOK_SECRET=your_webhook_secret
RAZORPAY_ENV=test

# Email (Resend API)
RESEND_API_KEY=re_xxxxxxxxxxxxx
FROM_EMAIL=noreply@yourdomain.com
FROM_NAME=Qprint
FRONTEND_URL=http://localhost:3000

# Storage
USE_LOCAL_STORAGE=true
UPLOADS_DIR=uploads

# Environment
ENVIRONMENT=development
TEST_MODE=false

Start the backend:

go run cmd/api/main.go

Expected output:

Loaded and OVERRODE env vars from current directory
Connected to PostgreSQL database
Server running on port 8080

Backend will be available at: http://localhost:8080

4. Frontend Web (Customer Portal)​

cd frontend

# Install dependencies
npm install

# Create .env.local (optional - defaults to localhost:8080)
echo "NEXT_PUBLIC_API_URL=http://localhost:8080" > .env.local
echo "NEXT_PUBLIC_RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxxxxx" >> .env.local

# Start development server
npm run dev

Frontend will be available at: http://localhost:3000

5. Admin Frontend​

cd admin_frontend

# Install dependencies
npm install

# Create .env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8080" > .env.local

# Start development server (runs on port 3001 by default)
npm run dev

Admin panel will be available at: http://localhost:3001

6. Customer App (Flutter - Android/iOS)​

cd customer_app

# Install dependencies
flutter pub get

# Configure Google Maps API key (see GOOGLE_MAPS_SETUP.md)
# Android: android/local.properties
# iOS: ios/Flutter/MapsConfig.xcconfig

# Run on connected device or emulator
flutter run

# Or specify device
flutter run -d android
flutter run -d ios

Configure API URL (optional for dev):

flutter run --dart-define=BASE_URL=http://10.0.2.2:8080  # Android emulator
flutter run --dart-define=BASE_URL=http://localhost:8080  # iOS simulator

7. Shopkeeper App (Flutter - Windows/Linux)​

For Windows with Printing:

cd shopkeeper_app

# Run setup script (downloads SumatraPDF if needed)
.\build_windows.bat

# Or manual:
flutter pub get
flutter run -d windows

For other platforms:

cd shopkeeper_app
flutter pub get
flutter run

Configure API URL:

flutter run -d windows --dart-define=BASE_URL=http://localhost:8080

Verification Checklist​

After starting all services, verify they're running:

ServiceURLExpected
Backendhttp://localhost:8080API ready message or status endpoint
Frontendhttp://localhost:3000Login/upload page
Admin Frontendhttp://localhost:3001Admin login page
Customer App(device)Login screen, map view
Shopkeeper App(Windows)Login screen, dashboard

Creating Test Users​

Option 1: Register via Frontend​

  1. Open http://localhost:3000
  2. Click "Register"
  3. Fill in details and select role (customer/shopkeeper)

Option 2: Create Admin User (CLI)​

cd backend

go run cmd/create_admin/main.go \
  -username=admin \
  -password=AdminPass123! \
  -email=admin@example.com \
  -name="Admin User"

Development Workflow​

Running All Services​

Option 1: Manual (recommended for development)

Open 5 terminals:

# Terminal 1 - Backend
cd backend && go run cmd/api/main.go

# Terminal 2 - Frontend
cd frontend && npm run dev

# Terminal 3 - Admin Frontend
cd admin_frontend && npm run dev

# Terminal 4 - Customer App (optional)
cd customer_app && flutter run

# Terminal 5 - Shopkeeper App (optional)
cd shopkeeper_app && flutter run -d windows

Option 2: Management Scripts

# Windows
manage.bat start

# Linux/Mac
./manage.sh start

# Python (cross-platform)
python manage.py start

Hot Reload​

  • Backend: Restart go run cmd/api/main.go after code changes
  • Frontend/Admin: Next.js hot reloads automatically
  • Flutter Apps: Press r (hot reload) or R (hot restart) in terminal

Database Migrations​

cd backend

# Apply migrations (if schema.go changes)
go run cmd/api/main.go
# Migrations run automatically on startup

Common Issues​

Backend: Database Connection Failed​

Error: Failed to connect to PostgreSQL

Fix:

  • Ensure PostgreSQL is running: pg_ctl status or check services
  • Verify DATABASE_URL in .env
  • Test connection: psql -U postgres -d filesharing

Backend: JWT Secret Too Short​

Error: JWT_SECRET must be at least 32 characters

Fix: Generate a secure secret:

# Linux/Mac/Git Bash
openssl rand -base64 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

Frontend: API Connection Failed​

Error: Network error or CORS issue

Fix:

  • Verify backend is running on port 8080
  • Check NEXT_PUBLIC_API_URL in .env.local
  • Ensure ALLOWED_ORIGINS includes http://localhost:3000

Flutter: Certificate Pinning Fails​

Error: HandshakeException: Connection terminated during handshake

Fix:

  • Pinning is disabled in debug mode by default
  • For custom backend, disable pinning: --dart-define=ENABLE_CERT_PINNING=false
  • Or update letsencrypt_certs.dart with your server's certificate

Shopkeeper App: Printer Not Found​

Error: No printers available or SumatraPDF.exe not found

Fix:

Flutter: Plugin Not Found​

Error: MissingPluginException

Fix:

flutter clean
flutter pub get
flutter run

Build for Production​

Backend​

cd backend

# Build binary
go build -o backend_api ./cmd/api

# Run production binary
./backend_api
# Ensure .env has production values (JWT_SECRET 32+, ALLOWED_ORIGINS, ENVIRONMENT=production)

Frontend​

cd frontend

# Build for production
npm run build

# Deploy to Vercel (recommended)
vercel --prod

Admin Frontend​

cd admin_frontend
npm run build
vercel --prod

Customer App​

Android:

cd customer_app

# Configure production API
flutter build apk --dart-define=BASE_URL=https://your-api.onrender.com

# Or AAB for Play Store
flutter build appbundle --dart-define=BASE_URL=https://your-api.onrender.com

iOS:

flutter build ios --dart-define=BASE_URL=https://your-api.onrender.com
# Then use Xcode to sign and upload to App Store

Shopkeeper App (Windows)​

cd shopkeeper_app

# Build Windows release
flutter build windows --release --dart-define=BASE_URL=https://your-api.onrender.com

# Output: build/windows/x64/runner/Release/
# Distribute: shopkeeper_app.exe + data/ folder + SumatraPDF.exe in bin/

Next Steps​

Need Help?​

Last Updated: February 2026