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
anddocker-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 runip 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.
What's Running?
After starting GoPie, you'll have these services running:
Service | URL | Description |
---|---|---|
Web UI | http://localhost:3000 | Main GoPie interface |
API Server | http://localhost:8000 | Go backend API |
Chat Server | http://localhost:8001 | AI query processing |
PostgreSQL | localhost:5432 | Metadata storage |
Qdrant | http://localhost:6333 | Vector search engine |
MinIO | http://localhost:9000 | File 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.
- Click "New Project" in the GoPie interface
- Enter a project name (e.g., "Premier League Analytics")
- Add an optional description
- 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
- Navigate to your project
- Click "Upload Dataset"
- Select the downloaded
player_possession_stats.csv
file - 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
- Large Datasets: For files over 100MB, ensure Docker has sufficient memory
- Multiple Datasets: Upload related datasets to enable cross-dataset queries
- 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?
- Ensure all services are running:
docker-compose ps
- Check the web service logs:
docker-compose logs gopie-web
- Try accessing directly:
curl http://localhost:3000
- Clear your browser cache and cookies
Upload failing?
- Check file format - ensure it's CSV, Excel, or Parquet
- Verify file size is under 500MB for initial upload
- Check MinIO service:
docker-compose logs gopie-minio
- 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
- GoPie vs ChatGPT - See how GoPie compares to ChatGPT for data analysis
- GoPie vs Julius AI - Compare GoPie with Julius AI