# Quickstart

## 🚀 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

{% hint style="info" %}
**Note**: This is a development setup. For production deployment, see our AWS Production Guide or Infrastructure Guidance.
{% endhint %}

### 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

```bash
# 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

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

#### 1.2 Configure Environment

```bash
# 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

```bash
npm i
```

### Step 2: Database Setup (5 minutes)

#### 2.1 Start CockroachDB in Docker

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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: `user@gmail.com`
* Password: `ogprocks!`

**Admin Account** (Public Officer):

* Email: `admin@open.gov.sg`
* 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)

```bash
# 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

```bash
# 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:

```javascript
// 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

```bash
# 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**

```bash
# Ensure Docker is running
docker ps

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

**Build Errors**

```bash
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

```bash
# 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
```

***

{% hint style="success" %}
**🎉 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.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://international.open.gov.sg/self-hosting/askgov/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.