Back to Documentation

Getting Started Guide

Get JOEY up and running in 5 minutes. From installation to your first analytics workflow, this guide covers everything you need to start building production-ready data pipelines.

Prerequisites

Node.js 18+

JavaScript runtime for frontend and core modules

Python 3.8+

Backend API server and analytics processing

2GB free disk space

For application data and temporary files

5-Minute Quick Start

The fastest way to get JOEY running. This script handles everything: dependencies, configuration, and startup.

One-Command Setup

Terminal
# Clone the repository
git clone https://github.com/practicai/joey-standalone.git
cd joey-standalone
# Quick start (handles everything)
./quick-start.sh
# ✨ JOEY will be ready at http://localhost:6100
Installs all dependencies automatically
Sets up development environment
Starts all services with hot reload
Opens JOEY in your browser

What Happens Next

1

Frontend Setup

React app builds and starts on port 6100

2

Backend API

Flask server starts on port 5093

3

Core Modules

TypeScript modules compile and link

4

Storage Init

Creates ~/.joey-data/ directory structure

5

Ready!

Analytics Gateway opens in your browser

Pro Tip

The quick-start script is idempotent - safe to run multiple times if something goes wrong.

Manual Installation

For developers who prefer step-by-step control or need to customize the installation process.

1

Frontend Setup

cd frontend
npm install
npm start
# → http://localhost:6100

React 18 application with TypeScript and Tailwind CSS

2

Backend Setup

cd backend
pip install -r requirements.txt
python app.py
# → http://localhost:5093

Flask API server with analytics processing capabilities

3

Core Modules

cd joey-core
npm install
npm run build
# TypeScript modules ready

AWS SDK v3 integration and core platform utilities

Development Commands

Essential commands for JOEY development and operation.

Core Commands

./dev.sh

Start all components with hot reload

./start-frontend.sh

Frontend only (port 6100)

./start-backend.sh

Backend only (port 5093)

cd joey-core && npm test

Run TypeScript module tests

Project Structure

joey-standalone/
├── frontend/ # React application
├── backend/ # Flask API server
├── joey-core/ # TypeScript modules
├── docs/ # Documentation
├── templates/ # Jinja2 templates
├── examples/ # Demo projects
└── ~/.joey-data/ # Runtime data

Your First Analytics Workflow

Create a production-ready MetaFlow analytics workflow in under 2 minutes.

Step-by-Step Guide

1

Open JOEY

Navigate to http://localhost:6100

2

Analytics Gateway

Click the 'Analytics Gateway' tab

3

Create New Flow

Click 'Create New Flow' button

4

Select Platform

Choose 'MetaFlow' (recommended)

5

Choose Template

Select 'Data Quality Check'

6

Configure

Set quality threshold and parameters

7

Generate

Click 'Generate & Execute'

8

View Results

See comprehensive quality report

Expected Output

🔍 Starting Enterprise Data Quality Assessment
📊 Dataset: 1,000 rows × 15 columns
🎯 Quality threshold: 95.0%
✅ Completeness: 94.2%
✅ Uniqueness: 98.7%
✅ Validity: 96.1%
✅ Consistency: 99.2%
🎯 Overall Score: 97.1% (EXCELLENT)
📁 Results: ~/.joey-data/flows/results/
Production-ready MetaFlow code generated
Comprehensive quality assessment
Executive summary and detailed reports
Interactive MetaFlow artifacts

Next Steps

Explore multi-context analytics, try different platforms, or dive into the SmartCity demo!

Common Issues

Quick solutions to common setup and installation problems.

Port Already in Use

Error: Port 6100 or 5093 already in use

Kill existing processes: pkill -f node pkill -f python Then restart JOEY

Permission Denied

Permission denied when creating ~/.joey-data/

Ensure proper directory permissions: chmod 755 ~/ mkdir -p ~/.joey-data chmod -R 755 ~/.joey-data/

Python Dependencies

ModuleNotFoundError for required packages

Reinstall Python dependencies: cd backend pip install --upgrade pip pip install -r requirements.txt

Node.js Version

Unsupported Node.js version errors

Update to Node.js 18+: nvm install 18 nvm use 18 npm install -g npm@latest

What's Next?

Now that JOEY is running, explore the powerful features that make it the ultimate analytics gateway.

Analytics Gateway

Master workflow generation

Platform Integrations

Connect to MetaFlow, Databricks

SmartCity Demo

See real-world example