hive/docs/getting-started.md

Getting Started

This guide will help you get Beeline running on your local machine.

Prerequisites

• Docker (v20.10+) and Docker Compose (v2.0+) - for containerized deployment
• Node.js (v20+) - for local development without Docker

Quick Start with Docker

The fastest way to get started is using Docker Compose:

# 1. Clone the repository
git clone https://github.com/adenhq/beeline.git
cd beeline

# 2. Copy and configure
cp config.yaml.example config.yaml

# 3. Run setup
npm run setup

# 4. Start services
docker compose up

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000
• Health Check: http://localhost:4000/health

Development Setup

For local development with hot reload:

# 1. Clone and configure (same as above)
git clone https://github.com/adenhq/beeline.git
cd beeline
cp config.yaml.example config.yaml

# 2. Install dependencies
npm install

# 3. Generate environment files
npm run generate:env

# 4. Start frontend (terminal 1)
cd honeycomb
npm run dev

# 5. Start backend (terminal 2)
cd hive
npm run dev

Using Docker for Development

You can also use Docker with hot reload enabled:

# Copy development overrides
cp docker-compose.override.yml.example docker-compose.override.yml

# Start with hot reload
docker compose up

Project Structure

beeline/
├── honeycomb/          # Frontend (React + TypeScript + Vite)
│   ├── src/
│   │   ├── components/ # Reusable UI components
│   │   ├── pages/      # Page components
│   │   ├── hooks/      # Custom React hooks
│   │   ├── services/   # API client and services
│   │   ├── types/      # TypeScript type definitions
│   │   └── utils/      # Utility functions
│   └── public/         # Static assets
│
├── hive/               # Backend (Node.js + TypeScript + Express)
│   └── src/
│       ├── controllers/ # Request handlers
│       ├── middleware/  # Express middleware
│       ├── models/      # Data models
│       ├── routes/      # API routes
│       ├── services/    # Business logic
│       ├── types/       # TypeScript types
│       └── utils/       # Utility functions
│
├── docs/               # Documentation
├── scripts/            # Build and utility scripts
└── config.yaml         # Application configuration

Next Steps

1. Configure the Application: See Configuration Guide
2. Understand the Architecture: See Architecture Overview
3. Start Building: Add your own components and API endpoints

Troubleshooting

Port Already in Use

If ports 3000 or 4000 are in use, update config.yaml:

server:
  frontend:
    port: 3001  # Change to available port
  backend:
    port: 4001

Then regenerate environment files:

npm run generate:env

Docker Build Fails

Clear Docker cache and rebuild:

docker compose down
docker compose build --no-cache
docker compose up

Dependencies Issues

Clear node_modules and reinstall:

npm run clean
npm install