Web Analytics Made Easy - Statcounter
Skip to content

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)

To view documentation within the Duckling UI, build the MkDocs site:

cd ..  # Return to project root
pip install -r requirements-docs.txt
mkdocs build

Auto-Build

If MkDocs is installed, the backend will automatically build the documentation when you first open the docs panel in the UI.

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

Production Security

In production, always set a strong SECRET_KEY and set DEBUG=False.

Verifying Installation

Check Backend

cd backend
source venv/bin/activate
python app.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