Getting Started

Quick Start

Get GoPie up and running in a few minutes with Docker Compose

Get GoPie running on your machine in just a few minutes! This guide will walk you through the fastest way to deploy GoPie locally using Docker Compose without authentication.

Need authentication? This quick start uses a no-auth setup for simplicity. Installation with authentication (using Zitadel) will be covered in upcoming documentation.

Prerequisites

Before you begin, ensure you have the following:

Required Software

  • Docker & Docker Compose: Required to run GoPie services
    • Install Docker Desktop (includes Docker Compose)
    • Verify installation: docker --version and docker-compose --version

API Keys

  • LLM API Key: Required for natural language query processing. You can use any provider with OpenAI-compatible APIs:

    Commercial Providers:

    • OpenAI: Sign up at OpenAI Platform and generate an API key
    • Google Gemini: Get your API key from Google AI Studio - natively OpenAI-compatible
    • Groq: Ultra-fast inference with Groq Cloud - supports Llama and other open models
    • Together AI: Access open models at Together AI

    Open Source Models:

    • Via Cloud APIs: Providers like Groq, Together AI, Replicate, and Hugging Face offer OpenAI-compatible endpoints for models like Llama, Mistral, and others
    • Via Proxy (for non-compatible APIs): Use LiteLLM to convert Anthropic Claude, AWS Bedrock, or other provider APIs to OpenAI format
    • Local Models: Run models locally with tools like Ollama, LM Studio, or Jan that provide OpenAI-compatible endpoints
  • E2B API Key: Required for generating data visualizations

    • E2B provides secure cloud environments for code execution
    • Get your free API key by following these steps
    • The free trial includes sufficient credits for getting started

Why E2B? GoPie uses E2B to securely execute Python code for creating visualizations. This ensures your local environment remains isolated and secure while generating charts and graphs from your data.

Network Configuration

  • MinIO Access: The chat server needs to access MinIO (S3-compatible storage) running on port 9000
    • Ensure port 9000 is not blocked by firewall
    • Docker containers need to communicate with the host machine

Important: The chat server runs inside a Docker container and needs to access MinIO on your host machine. The configuration uses special Docker hostnames that vary by operating system.

Quick Setup

Clone the Repository

First, clone the GoPie repository to your local machine:

git clone https://github.com/factly/gopie.git
cd gopie

Configure Environment

Copy the no-auth configuration example file and add your API keys:

cp config-noauth.env.example config-noauth.env

Now edit the config-noauth.env file and update your API keys and network configuration:

# Open config-noauth.env in your preferred editor and update these values:

# ==================================
# AI Gateways & Providers Configuration
# ==================================
# GoPie supports multiple gateway providers for flexibility and reliability:
# - "custom": Direct access to any OpenAI-compatible provider (recommended for simplicity)
# - "portkey": AI gateway with routing, caching, and fallbacks
# - "litellm": Unified interface for 100+ LLM providers
# - "cloudflare": Cloudflare Workers AI gateway
# - "openrouter": Access multiple AI models through one API

# For most users, use "custom" with your preferred provider:
LLM_GATEWAY_PROVIDER="custom"

# Configure your chosen provider (Examples below):

# Option 1: OpenAI (default)
CUSTOM_LLM_BASE_URL="https://api.openai.com/v1"
CUSTOM_LLM_API_KEY="your-openai-api-key-here"

# Option 2: Google Gemini (uncomment to use)
# CUSTOM_LLM_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai"
# CUSTOM_LLM_API_KEY="your-gemini-api-key-here"

# Option 3: Groq for fast open source models (uncomment to use)
# CUSTOM_LLM_BASE_URL="https://api.groq.com/openai/v1"
# CUSTOM_LLM_API_KEY="your-groq-api-key-here"

# Legacy configuration (keep these in sync with above)
GOPIE_OPENAI_APIKEY="your-api-key-here"  # Same as CUSTOM_LLM_API_KEY
GOPIE_OPENAI_BASEURL="https://api.openai.com/v1"  # Same as CUSTOM_LLM_BASE_URL
GOPIE_OPENAI_MODEL="gpt-4o-mini"
OPENAI_API_KEY="your-api-key-here"  # Same as CUSTOM_LLM_API_KEY

# Model Configuration - Adjust based on your provider
FAST_MODEL="gpt-4o-mini"  # or "gemini-2.0-flash" or "llama-3.3-70b-versatile"
BALANCED_MODEL="gpt-4o-mini"  # or "gemini-2.0-flash"
ADVANCED_MODEL="gpt-4o"  # or "gemini-2.0-flash" or "llama-3.3-70b-versatile"
DEFAULT_EMBEDDING_MODEL="text-embedding-3-large"  # or provider's embedding model

# E2B Configuration
E2B_API_KEY="your-e2b-api-key-here"

# CHAT SERVER S3 Configuration - IMPORTANT: Platform-specific setting
# Choose the correct host based on your operating system:
# macOS/Windows (Docker Desktop):
S3_HOST="http://host.docker.internal:9000"
# Linux (native Docker):
# S3_HOST="http://172.17.0.1:9000"

Platform-Specific Configuration:

  • macOS/Windows: Use host.docker.internal (Docker Desktop provides this)
  • Linux: Use 172.17.0.1 (default Docker bridge IP) or run ip addr show docker0 to find your Docker bridge IP
  • If you encounter connection issues, verify MinIO is accessible at http://localhost:9000 from your host machine first

Start GoPie

Launch all services with a single command:

docker-compose --env-file config-noauth.env -f docker-compose-noauth.yaml up -d

Wait about 30-60 seconds for all services to initialize.

Access GoPie

Open your browser and navigate to:

http://localhost:3000

You should see the GoPie interface ready to use!

What's Running?

After starting GoPie, you'll have these services running:

ServiceURLDescription
Web UIhttp://localhost:3000Main GoPie interface
API Serverhttp://localhost:8000Go backend API
Chat Serverhttp://localhost:8001AI query processing
PostgreSQLlocalhost:5432Metadata storage
Qdranthttp://localhost:6333Vector search engine
MinIOhttp://localhost:9000File storage (S3-compatible)

Create Your First Project

Before uploading datasets, you'll need to create a project. Projects organize your datasets and enable powerful cross-dataset queries.

  1. Click "New Project" in the GoPie interface
  2. Enter a project name (e.g., "Premier League Analytics")
  3. Add an optional description
  4. Click "Create"

Projects & Datasets: An organization can have multiple projects, and each project can contain multiple related datasets. This structure enables complex queries across datasets within the same project.

Sample Dataset: Premier League Player Statistics

Want to try GoPie immediately? We'll use the 2025 Premier League Player Possession Statistics dataset as our example. This comprehensive dataset contains detailed possession and performance metrics for Premier League players, including:

  • Player information: Names, teams, positions, nationalities, and ages
  • Possession statistics: Touches in defensive, middle, and attacking zones
  • Performance metrics: Successful take-ons, carries, distance covered, and more
  • Match participation: Minutes played (90s) across the season

Download the Dataset

curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/player_possession_stats.csv

Upload to Your Project

  1. Navigate to your project
  2. Click "Upload Dataset"
  3. Select the downloaded player_possession_stats.csv file
  4. GoPie will automatically analyze the schema and prepare it for querying

More Datasets Available: Explore additional sample datasets at github.com/factly/gopie/main/datasets/ if you want to try different data types.

Advanced: Complete Premier League Project

For a comprehensive analytics experience, upload all Premier League datasets to your project:

# Download all Premier League datasets
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/player_possession_stats.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/player_salaries.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/player_stats.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/team_possession_stats.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/team_salary.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/team_stats.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/standings.csv
curl -O https://raw.githubusercontent.com/factly/gopie/main/datasets/2025-premier-league-stats-matches-salaries/fixtures.csv

With multiple related datasets in one project, you can perform complex cross-dataset queries like:

  • Correlating player salaries with performance metrics
  • Analyzing team possession stats against league standings
  • Comparing individual player contributions to team success

Verify Installation

Check that all services are running properly:

docker-compose ps

You should see all services with status "Up". If any service shows "Exit" or "Restarting", check the logs:

docker-compose logs [service-name]

Your First Query

Once your Premier League dataset is uploaded, try these natural language queries:

Basic Queries

  • "Show me all players from Liverpool"
  • "How many players are in the dataset?"
  • "What teams are represented in the data?"

Analytical Queries

  • "Who are the top 10 players by total touches?"
  • "Which players have the best successful take-on rate?"
  • "Show me the average age by team"
  • "What's the distribution of positions in the Premier League?"

Advanced Queries (Single Dataset)

  • "Which defenders have the most attacking touches?"
  • "Compare possession stats between Manchester City and Arsenal players"
  • "Who covers the most distance per 90 minutes played?"
  • "Find midfielders under 25 with high successful take-on rates"

Complex Queries (Multiple Datasets in Project)

Once you've uploaded additional Premier League datasets to your project:

  • "Show me the correlation between player salary and possession stats"
  • "Which teams have the best cost-per-point ratio in the standings?"
  • "Compare team possession dominance with their league position"
  • "Find undervalued players based on performance vs salary"

Quick Tips

Performance Tip

For the best experience, ensure Docker has at least 4GB of RAM allocated. You can adjust this in Docker Desktop settings.

Optimize Your Experience

  1. Large Datasets: For files over 100MB, ensure Docker has sufficient memory
  2. Multiple Datasets: Upload related datasets to enable cross-dataset queries
  3. API Access: Your datasets are instantly available at http://localhost:8000/api/datasets

Common Commands

# Stop all services
docker-compose down

# View logs for a specific service
docker-compose logs -f gopie-web

# Restart a service
docker-compose restart gopie-server

# Remove all data and start fresh
docker-compose down -v

Troubleshooting

Services not starting?

Check if ports are already in use:

# Check if ports are free
lsof -i :3000 -i :8000 -i :8001 -i :5432

If ports are occupied, either stop the conflicting services or modify the port mappings in docker-compose.yml.

Can't access the web interface?
  1. Ensure all services are running: docker-compose ps
  2. Check the web service logs: docker-compose logs gopie-web
  3. Try accessing directly: curl http://localhost:3000
  4. Clear your browser cache and cookies
Upload failing?
  1. Check file format - ensure it's CSV, Excel, or Parquet
  2. Verify file size is under 500MB for initial upload
  3. Check MinIO service: docker-compose logs gopie-minio
  4. Ensure the file has headers in the first row

Need Help?

Running into issues? Don't worry! Our community is here to help. Join our Discord server where our team and community members can assist you with installation and setup.

What's Next?

Congratulations! You now have GoPie running locally. Here's what to explore next:

Compare GoPie

Get Involved