⚡Quickstart

Get AskGov running locally in 30 minutes to evaluate its capabilities

🚀 Quickstart Guide

Overview

This guide gets you from zero to a working AskGov instance in 30 minutes. Perfect for:

• Technical evaluation of AskGov capabilities

• Understanding the architecture before production deployment

• Development and customization planning

Note: This is a development setup. For production deployment, see our AWS Production Guide or Infrastructure Guidance.

Prerequisites

Ensure you have the following installed:

• Node.js v20+ (LTS version recommended)

• npm 9+

• Docker Desktop (for database and search services)

• 4GB+ available RAM (for running all services)

Quick Prerequisites Check

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Docker is running
docker --version
docker ps       # Should not error

Step 1: Clone and Setup (5 minutes)

1.1 Clone the Repository

# Clone the repository
git clone https://github.com/opengovsg/askgov.git
cd askgov

1.2 Configure Environment

# Copy the example environment file
cp .env.example .env

# Open .env in your editor and review the defaults
# For quickstart, the defaults work fine

1.3 Install Dependencies

npm i

Step 2: Database Setup (5 minutes)

2.1 Start CockroachDB in Docker

# Start the database container
npm run docker

# Wait ~30 seconds for the container to fully initialize
# You can verify it's running with:
docker ps | grep cockroach

2.2 Initialize Database Schema

# Run database migrations and seed data
npm run setup

# This creates:
# - Database schema
# - Sample agencies
# - Test user accounts
# - Sample questions and answers

2.3 Build the Application

# Run the initial build
npm run build

# This compiles TypeScript and bundles assets
# Takes about 1-2 minutes

Step 3: Start Development Server (2 minutes)

# Start the development server
npm run dev

# Server starts on http://localhost:8080
# Hot reloading is enabled for development

Step 4: Access and Explore (10 minutes)

4.1 Open AskGov

Navigate to: http://localhost:8080

You'll see the AskGov homepage with sample agencies and questions.

4.2 Test User Accounts

The setup created two test accounts:

Citizen Account (Regular User):

• Email: [email protected]

• Password: ogprocks!

Admin Account (Public Officer):

• Email: [email protected]

• Password: ogprocks!

4.3 Key Features to Explore

As a Citizen:

1. Search for answers - Try searching for common terms

2. Browse by agency - Click on any agency to see their FAQs

3. Ask a question - Submit a new question (requires login)

4. Provide feedback - Rate answers as helpful or not

As an Admin:

1. Manage questions - Answer, edit, or archive questions

2. View analytics - See popular questions and feedback

3. Manage topics - Organize questions by categories

4. Bulk operations - Export questions for reporting

Step 5: Enable Hybrid Search (Optional, 5 minutes)

AskGov's powerful hybrid search requires Weaviate setup:

5.1 Start Weaviate (Local Development)

# Add to your docker-compose.yml or run separately
docker run -d \
  -p 8001:8080 \
  --name weaviate \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  -e DEFAULT_VECTORIZER_MODULE=text2vec-transformers \
  -e ENABLE_MODULES=text2vec-transformers \
  semitechnologies/weaviate:latest

5.2 Initialize Search Index

# First, get a superadmin token (check your .env for credentials)
# Then make a POST request to initialize the search class

curl -X POST http://localhost:8080/hybrid/classes \
  -H "Authorization: Bearer YOUR_SUPERADMIN_TOKEN" \
  -F "className=Question_v1"

5.3 Verify Search

• Go to the search bar

• Try semantic searches like "how to apply for benefits"

• Notice how it finds relevant content even without exact matches

Step 6: Customization Preview (5 minutes)

6.1 Basic Branding

Edit key files to see customization in action:

// app/root.jsx - Change the site title
export const meta = () => ({
  title: "YourGov Q&A Platform",
});

// styles/themes/light.css - Adjust color scheme
:root {
  --brand-primary: #your-color;
  --brand-secondary: #your-color;
}

6.2 Add Your Agency

# Access the database
npm run prisma studio

# Or use the API to create an agency
# POST to /api/v1/superadmin/agency

Troubleshooting

Common Issues and Solutions

Database Connection Failed

# Ensure Docker is running
docker ps

# Restart the database container
docker-compose down
npm run docker

Build Errors

rm -rf node_modules
npm install
npm run build

Search Not Working

• Ensure Weaviate is running: docker ps | grep weaviate

• Check Weaviate health: curl http://localhost:8001/v1/.well-known/ready

• Verify environment variables for Weaviate are set

Next Steps

For Evaluation

Now that you have AskGov running:

1. Test core workflows - Create questions, provide answers, test search

2. Review the codebase - Understand the architecture and extension points

3. Plan customizations - Identify what needs to change for your use case

4. Estimate resources - Use the local setup to gauge performance needs

For Development

Ready to customize? Check out:

• Component Customization - Replace email, auth, search providers

• Configuration Reference - All environment variables explained

• Security Guide - Hardening for production

For Deployment

Moving to production? See:

• AWS Production Deployment - Step-by-step AWS guide

• Infrastructure Guidance - Azure, GCP, on-premise options

• Evaluation Guide - Full assessment framework

Quick Command Reference

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run all linters
npm run test         # Run unit tests
npm run test:e2e:dev # Run E2E tests with UI

# Database
npm run docker       # Start CockroachDB
npm run setup        # Run migrations and seed
npx prisma studio    # Visual database editor
npx prisma migrate dev # Create new migration

# Production
npm run start        # Start production server
npm run build && npm run start # Full production start

---

🎉 Congratulations! You now have a working AskGov instance. Explore the features, test the workflows, and when ready, proceed to our Evaluation Guide or Production Deployment guides.