GoPie Logo

Local Development Setup

Set up GoPie development environment to contribute code, test features, or customize the platform

This guide helps you set up a complete GoPie development environment for contributing code, testing features, or building custom extensions.

For Contributors: This setup is ideal for developers who want to contribute to GoPie or customize it for their needs.

Prerequisites

Required Software

  • Git for version control
  • Node.js 20.x LTS (Download)
  • Bun 1.0+ for frontend (Install Bun)
  • Go 1.21+ for backend (Download)
  • Python 3.11+ for AI service (Download)
  • Docker & Docker Compose for databases
  • Make (optional but recommended)
  • VS Code with extensions:
    • Go
    • Python
    • ESLint
    • Prettier
    • Tailwind CSS IntelliSense
  • GoLand or IntelliJ IDEA (alternative IDEs)
  • Postman or Insomnia for API testing
  • TablePlus or DBeaver for database access

Verify installations:

node --version    # Should be 20.x
bun --version     # Should be 1.0+
go version        # Should be 1.21+
python --version  # Should be 3.11+
docker --version  # Should be 20.10+

Project Structure

package.json
next.config.mjs
go.mod
main.go
pyproject.toml
docker-compose.yml
docker-compose-noauth.yaml
.env.example

Quick Setup

Clone and Initialize

# Clone the repository
git clone https://github.com/factly/gopie.git
cd gopie

# Copy environment configuration
cp .env.example .env
cp config-noauth.env .env  # For development without auth

# Install Git hooks (optional)
make install-hooks

Start Infrastructure Services

Start only the database and storage services:

# Start infrastructure services
docker-compose -f docker-compose-noauth.yaml up -d \
  gopie-postgres gopie-qdrant gopie-minio

# Verify services are running
docker-compose -f docker-compose-noauth.yaml ps

Setup Each Service

We'll run each service locally for development with hot-reload:

cd web

# Install dependencies
bun install

# Prepare WASM files
bun run prepare:wasm

# Start development server
bun run dev

The frontend will be available at http://localhost:3000

cd server

# Download dependencies
go mod download

# Install development tools
go install github.com/cosmtrek/air@latest
go install github.com/swaggo/swag/cmd/swag@latest

# Generate Swagger docs
swag init

# Run database migrations
goose -dir ./infrastructure/postgres/migrations postgres \
  "postgres://gopie:gopie@localhost:5432/gopie?sslmode=disable" up

# Start with hot-reload
air serve

# Or run directly
go run main.go serve

The API will be available at http://localhost:8000

cd chat-server

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# Or use the Makefile
make run

The chat service will be available at http://localhost:8001

Verify Everything Works

Open your browser and:

  1. Navigate to http://localhost:3000
  2. Try uploading a sample CSV file
  3. Ask a natural language question
  4. Check the auto-generated API at http://localhost:8000/swagger

Detailed Service Setup

Frontend Development (Next.js)

Environment Configuration

Create web/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_CHAT_URL=http://localhost:8001
NEXT_PUBLIC_MINIO_URL=http://localhost:9000
NEXT_PUBLIC_AUTH_ENABLED=false

Development Commands

# Install new packages
bun add package-name

# Type checking
bun run type-check

# Linting
bun run lint

# Format code
bun run format

# Build for production
bun run build

# Run tests
bun test

Key Directories

  • app/ - Next.js app router pages
  • components/ - React components
  • lib/ - Utility functions and hooks
  • public/ - Static assets

Backend Development (Go)

Environment Variables

Key variables for server/.env:

# Server
PORT=8000
ENV=development

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=gopie
POSTGRES_USER=gopie
POSTGRES_PASSWORD=gopie

# Storage
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_USE_SSL=false

# Qdrant
QDRANT_URL=http://localhost:6333

# Auth (disabled for dev)
AUTH_ENABLED=false

Database Migrations

# Create new migration
goose -dir ./infrastructure/postgres/migrations create migration_name sql

# Apply migrations
goose -dir ./infrastructure/postgres/migrations postgres \
  "postgres://gopie:gopie@localhost:5432/gopie?sslmode=disable" up

# Rollback
goose -dir ./infrastructure/postgres/migrations postgres \
  "postgres://gopie:gopie@localhost:5432/gopie?sslmode=disable" down

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./domain/...

# Run with race detection
go test -race ./...

Code Generation

# Generate Swagger documentation
swag init

# Generate SQLC queries (if modified)
sqlc generate

# Format code
go fmt ./...

# Run linter
golangci-lint run

AI Service Development (Python)

Environment Configuration

Create chat-server/.env:

# API Keys (choose one)
OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here

# Service URLs
DATABASE_URL=postgresql://gopie:gopie@localhost:5432/gopie
QDRANT_URL=http://localhost:6333
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# Development
DEBUG=true
LOG_LEVEL=debug

Development Tools

# Run tests
pytest

# Run specific test file
pytest tests/test_workflow.py

# Run with coverage
pytest --cov=app

# Format code
black .

# Sort imports
isort .

# Type checking
mypy app

Adding New Tools

Create a new tool in app/tool_utils/:

from langchain.tools import tool

@tool
def custom_analysis_tool(query: str) -> str:
    """
    Perform custom analysis on the data.
    
    Args:
        query: The analysis query
        
    Returns:
        Analysis results
    """
    # Implementation here
    return "Analysis results"

Database Access

PostgreSQL

Connect to the development database:

# Using psql
docker exec -it gopie-postgres psql -U gopie -d gopie

# Using connection string
psql postgres://gopie:gopie@localhost:5432/gopie

Common queries for development:

-- View all tables
\dt

-- Check datasets
SELECT * FROM datasets;

-- View schema for a table
\d datasets

-- Check recent queries
SELECT * FROM query_history ORDER BY created_at DESC LIMIT 10;

Qdrant Vector Database

Access Qdrant dashboard at http://localhost:6333/dashboard

Test vector operations:

# List collections
curl http://localhost:6333/collections

# Check collection info
curl http://localhost:6333/collections/schemas

MinIO Object Storage

Access MinIO console at http://localhost:9000

  • Username: minioadmin
  • Password: minioadmin

Development Workflow

1. Feature Development

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes

Follow the coding standards for each service:

Frontend (TypeScript/React):

  • Use functional components with hooks
  • Follow Airbnb style guide
  • Keep components small and focused

Backend (Go):

  • Follow Go code review comments
  • Use dependency injection
  • Write table-driven tests

AI Service (Python):

  • Follow PEP 8
  • Use type hints
  • Document with docstrings

Test Your Changes

# Frontend tests
cd web && bun test

# Backend tests
cd server && go test ./...

# AI service tests
cd chat-server && pytest

Commit and Push

git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

2. Hot Reload Development

All services support hot reload:

  • Frontend: Changes reflect immediately
  • Backend: Air restarts on file changes
  • AI Service: Uvicorn reloads on changes

3. Debugging

Frontend Debugging

Add to web/.vscode/launch.json:

{
  "type": "chrome",
  "request": "launch",
  "name": "Debug Next.js",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}/web"
}

Backend Debugging

Add to server/.vscode/launch.json:

{
  "type": "go",
  "request": "launch",
  "name": "Debug Server",
  "program": "${workspaceFolder}/server/main.go",
  "args": ["serve"],
  "env": {
    "ENV": "development"
  }
}

AI Service Debugging

Use VS Code Python debugger or add breakpoints:

import pdb; pdb.set_trace()

Common Development Tasks

Adding a New API Endpoint

  1. Define the handler in interfaces/http/handlers/:
func (h *DatasetHandler) NewEndpoint(c *fiber.Ctx) error {
    // Implementation
    return c.JSON(response)
}
  1. Add route in interfaces/http/routes/:
api.Post("/datasets/:id/analyze", h.NewEndpoint)
  1. Update Swagger docs:
// @Summary New endpoint summary
// @Tags datasets
// @Accept json
// @Produce json
// @Param id path string true "Dataset ID"
// @Success 200 {object} Response
// @Router /api/datasets/{id}/analyze [post]

After adding the endpoint:

cd server
swag init

View at http://localhost:8000/swagger

  1. Add API function in web/lib/api/:
export async function analyzeDataset(id: string) {
  const response = await fetch(`${API_URL}/datasets/${id}/analyze`, {
    method: 'POST',
  });
  return response.json();
}
  1. Use in component:
const result = await analyzeDataset(datasetId);

Adding a New UI Component

  1. Create component in web/components/:
export function NewComponent({ prop }: Props) {
  return <div>{/* Component JSX */}</div>;
}
  1. Add to component index:
export { NewComponent } from './NewComponent';
  1. Use in pages:
import { NewComponent } from '@/components';

Modifying the AI Workflow

  1. Edit workflow in chat-server/app/workflow/:
from langgraph.graph import StateGraph

workflow = StateGraph(State)
# Add new nodes and edges
  1. Test changes:
pytest tests/test_workflow.py -v

Troubleshooting

Port already in use

Find and kill the process:

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>
Database connection failed

Check PostgreSQL is running:

docker-compose -f docker-compose-noauth.yaml ps gopie-postgres
docker-compose -f docker-compose-noauth.yaml logs gopie-postgres
Module not found errors

Frontend:

cd web && bun install

Backend:

cd server && go mod download

AI Service:

cd chat-server && uv sync
WASM files missing

Regenerate WASM files:

cd web && bun run prepare:wasm

Development Best Practices

Code Style

  1. Use linters and formatters:

    • Frontend: ESLint + Prettier
    • Backend: golangci-lint + gofmt
    • Python: Black + isort + flake8

  2. Write tests:

    • Unit tests for business logic
    • Integration tests for APIs
    • E2E tests for critical paths

  3. Document your code:

    • JSDoc for TypeScript
    • GoDoc for Go
    • Docstrings for Python

Git Workflow

  1. Commit messages:

    feat: add new feature
fix: resolve bug
docs: update documentation
refactor: improve code structure
test: add tests
chore: update dependencies

  2. Pull request template:

    • Clear description
    • Screenshots for UI changes
    • Test instructions
    • Breaking changes noted

Performance

  1. Profile before optimizing
  2. Use appropriate data structures
  3. Implement caching where beneficial
  4. Monitor memory usage

Resources

Documentation

Tools

Community

Ready to Code! You now have a complete GoPie development environment. Check our Contributing Guide to start making improvements!