Installation

This guide covers setting up Duckling for local development.

Prerequisites

• Python 3.10+ (3.13 recommended)
• Node.js 18+
• npm or yarn
• Git

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/davidgs/duckling.git
cd duckling

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Frontend Setup

cd ../frontend
npm install

4. Build Documentation (Optional)

The backend install already includes MkDocs (same backend/requirements.txt). From the repository root:

cd ..  # project root (where mkdocs.yml lives)
# Use the backend venv if you created one: source backend/venv/bin/activate
mkdocs build

Documentation builds use the same backend/requirements.txt as the API (MkDocs plugins are listed at the top of that file).

Environment Configuration

Backend Environment Variables

Create a .env file in the backend directory:

# Flask Configuration
FLASK_ENV=development
SECRET_KEY=your-secret-key
DEBUG=True

# File Handling
MAX_CONTENT_LENGTH=104857600  # 100MB

Verifying Installation

Check Backend

cd backend
source venv/bin/activate
python duckling.py

You should see:

 * Running on http://127.0.0.1:5001

Check Frontend

cd frontend
npm run dev

You should see:

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3000/

Troubleshooting

Python Version Issues

If you encounter Python version issues:

# Check Python version
python --version

# Use specific Python version
python3.13 -m venv venv

Node.js Version Issues

# Check Node version
node --version

# Use nvm to switch versions
nvm install 18
nvm use 18

Dependency Installation Failures

# Backend - try upgrading pip
pip install --upgrade pip
pip install -r requirements.txt

# Frontend - clear cache
rm -rf node_modules package-lock.json
npm install

Next Steps

• Quick Start - Learn the basics
• Configuration - Customize settings