Quick Start

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

Prerequisites: You'll need Docker and Docker Compose installed on your system. If you don't have them, check our system requirements.

5-Minute 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 example environment file and configure it:

cp .env.example .env

For a quick start, the default values will work. The essential configurations are already set!

Want to skip authentication? Use our no-auth configuration for local development:

cp config-noauth.env .env

Start GoPie

Launch all services with a single command:

docker-compose -f docker-compose-noauth.yaml up -d

Perfect for local development and testing!

docker-compose up -d

This starts all services including authentication via Zitadel.

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:

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

What's Next?

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