Quickstart

This tutorial walks you through setting up Sercha Core locally, connecting a GitHub repository, and running your first search query. By the end, you'll have a working search system indexing real content from your GitHub account.

Prerequisites

Before starting, ensure you have:

• Docker and Docker Compose installed (Get Docker)
• 4GB RAM available for the Vespa search engine
• A GitHub account with at least one repository to index

What We'll Build

Sercha Core consists of several components working together:

Component	Purpose
API Server	Handles authentication, source management, and search queries
Worker	Processes sync jobs and indexes content
PostgreSQL	Stores metadata, users, and source configurations
Vespa	Powers the search engine with full-text and vector search

The quickstart runs all components in a single Docker Compose stack.

API Guide

Step 1: Start the Services

First, download the Docker Compose configuration and start the services:

curl -O https://raw.githubusercontent.com/custodia-labs/sercha-core/main/examples/quickstart/docker-compose.yml
docker compose up -d

Quick Setup Script

Want to skip the manual steps? Download and run the quickstart script:

curl -O https://raw.githubusercontent.com/custodia-labs/sercha-core/main/examples/quickstart/quickstart.sh
chmod +x quickstart.sh
./quickstart.sh

The script automates all the steps below. Continue reading to understand what each step does.

Vespa requires about 60-90 seconds to initialize on first start. You can monitor the startup progress:

docker compose logs -f vespa

Once you see Container is ready, the services are running. Verify by checking the health endpoint:

curl http://localhost:8080/health

You should see a response showing all components are healthy:

{
  "status": "healthy",
  "components": {
    "postgres": { "status": "healthy" },
    "server": { "status": "healthy" },
    "vespa": { "status": "healthy" }
  }
}

Step 2: Create an Admin User

Before using the API, you need to create the first admin user. This is a one-time setup step.

POST /api/v1/setup

curl -X POST http://localhost:8080/api/v1/setup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-secure-password",
    "name": "Admin"
  }'

Response:

{
  "id": "usr_7abc123def456",
  "email": "admin@example.com",
  "name": "Admin",
  "role": "admin"
}

Step 3: Authenticate

All subsequent API calls require authentication. Login to get an access token.

POST /api/v1/auth/login

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-secure-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_7abc123def456",
    "email": "admin@example.com"
  }
}

Copy the token value. For the remaining commands, set it as an environment variable:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 4: Initialize the Search Schema

Sercha uses Vespa as its search backend. Before indexing content, you need to deploy the search schema. The dev_mode parameter deploys the full application package for local development.

POST /api/v1/admin/vespa/connect

curl -X POST http://localhost:8080/api/v1/admin/vespa/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dev_mode": true}'

Response:

{
  "status": "connected",
  "endpoint": "http://vespa:19071",
  "schema_deployed": true
}

Step 5: Create a GitHub OAuth App

To connect GitHub repositories, Sercha uses OAuth for secure access. You need to create a GitHub OAuth App:

1. Go to GitHub Developer Settings
2. Click OAuth Apps → New OAuth App
3. Fill in the details:
   • Application name: Sercha Local (or any name)
   • Homepage URL: http://localhost:8080
   • Authorization callback URL: http://localhost:8080/api/v1/oauth/callback
4. Click Register application
5. On the next page, note your Client ID
6. Click Generate a new client secret and copy it immediately

Step 6: Configure the GitHub Provider

Register your GitHub OAuth credentials with Sercha.

POST /api/v1/providers/:type/config

curl -X POST http://localhost:8080/api/v1/providers/github/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "http://localhost:8080/api/v1/oauth/callback",
    "enabled": true
  }'

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the values from step 5.

Response:

{
  "provider_type": "github",
  "enabled": true,
  "has_secrets": true
}

Step 7: Connect Your GitHub Account

Now initiate the OAuth flow to connect your GitHub account.

POST /api/v1/oauth/:provider/authorize

curl -X POST http://localhost:8080/api/v1/oauth/github/authorize \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "authorize_url": "https://github.com/login/oauth/authorize?client_id=...&state=..."
}

Open the authorize_url in your browser. GitHub will ask you to authorize the application and select which repositories to grant access to. After authorization, you'll be redirected back to Sercha, which creates an "installation" representing this connection.

Step 8: View Your Installation

After completing OAuth, verify the installation was created.

GET /api/v1/installations

curl http://localhost:8080/api/v1/installations \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "installations": [
    {
      "id": "inst_abc123def456",
      "provider_type": "github",
      "account_id": "your-github-username",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Note the id value - you'll need it in the next steps.

Step 9: Browse Available Repositories

List the repositories accessible through your installation.

GET /api/v1/installations/:id/containers

curl "http://localhost:8080/api/v1/installations/inst_abc123def456/containers" \
  -H "Authorization: Bearer $TOKEN"

Replace inst_abc123def456 with your actual installation ID.

Response:

{
  "containers": [
    {
      "id": "your-username/your-repo",
      "name": "your-repo",
      "type": "repository",
      "metadata": {
        "private": "false",
        "description": "My awesome project"
      }
    }
  ]
}

Each container represents a repository you can index. The id field uses the owner/repo format.

Step 10: Create a Source

A "source" in Sercha represents a configured data source to index. Create one for your repository.

POST /api/v1/sources

curl -X POST http://localhost:8080/api/v1/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project Docs",
    "provider_type": "github",
    "installation_id": "inst_abc123def456",
    "selected_containers": ["your-username/your-repo"]
  }'

Replace the installation_id and selected_containers with your values.

Response:

{
  "id": "src_xyz789",
  "name": "My Project Docs",
  "provider_type": "github",
  "sync_status": "pending",
  "created_at": "2024-01-15T10:35:00Z"
}

Step 11: Start Indexing

Trigger a sync to fetch and index content from your repository.

note

In production, syncs run automatically on a schedule. This manual trigger is useful for testing or forcing an immediate update.

POST /api/v1/sources/:id/sync

curl -X POST "http://localhost:8080/api/v1/sources/src_xyz789/sync" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "status": "started",
  "source_id": "src_xyz789"
}

The worker will now fetch files from your repository, extract text content, and index it in Vespa. For a small repository, this takes about 10-30 seconds. You can check the sync status:

GET /api/v1/sources/:id

curl "http://localhost:8080/api/v1/sources/src_xyz789" \
  -H "Authorization: Bearer $TOKEN"

When sync_status changes to completed, your content is indexed and searchable.

Step 12: Search Your Content

Now for the exciting part - search your indexed content.

POST /api/v1/search

curl -X POST http://localhost:8080/api/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "README"}'

Response:

{
  "results": [
    {
      "id": "doc_abc123",
      "title": "README.md",
      "snippet": "# My Project\n\nThis project demonstrates...",
      "source": "your-username/your-repo",
      "score": 0.95
    }
  ],
  "total": 1,
  "took_ms": 12
}

Try different queries to explore your indexed content. The search supports natural language queries across all text content in your repository.

Admin UI Guide

Coming Soon

The Admin UI guide is under development. For now, follow the API Guide tab.

What's Running

After completing the quickstart, you have the following services:

Service	Port	Purpose
sercha	8080	API server (combined API + Worker mode)
postgres	5432	Metadata, users, source configuration
vespa	19071	Search engine (config port)

Stopping and Cleanup

To stop the services while preserving data:

docker compose down

To stop and remove all data (start fresh):

docker compose down -v

Next Steps

Now that you have a working Sercha instance:

• Architecture Overview - Understand how the components work together
• Run Modes - Deploy API and Worker separately for production
• Examples - More deployment configurations