​

Installation & Local Development

This page covers two supported installation paths:

1. Docker Compose – Easiest, fully reproducible, no host dependencies beyond Docker Desktop.
2. Source Checkout (Python + Node) – Recommended for contributors who need hot-reload on both front- and back-end code.

Regardless of path, you will end up with:

• FastAPI server on http://localhost:8001
• SvelteKit front-end on http://localhost:5173
• Live-reloading editor with full feature set

​

1 – Docker Compose

The root directory contains docker-compose.yml that orchestrates two services: backend and frontend, networked together on an internal bridge.

version: "3.9"
services:
  backend:
    build: ./backend
    ports:
      - "8001:8001"
    volumes:
      - ./data:/app/data             # Persist datasets and versions
      - ./backend:/app/backend       # Bind-mount code for live reload
  frontend:
    build: ./frontend
    ports:
      - "5173:5173"
    environment:
      - VITE_API_URL=http://backend:8001
    depends_on:
      - backend

​

Quick Start

# In project root
docker compose build      # first-time or whenever Dockerfile changes
docker compose up         # -d for detached mode

After a minute you should see logs similar to:

frontend  | http://localhost:5173
backend   | Uvicorn running on http://0.0.0.0:8001

Navigate to http://localhost:5173 and start working. Datasets will live under ./data/ on your host, making them durable across container rebuilds.

​

2 – Source Checkout

For active development you likely want in-editor auto-reload and easier debugging.

​

Prerequisites

• Python 3.11+ – Install via pyenv, Homebrew, or system package manager.
• Node 20+ – Required by SvelteKit/Vite.
• uv – Ultra-fast Python dependency installer (think pip install -r but compiled).
• Ruff – Python linter. Optional; if absent Mako Code installs it via uv.

brew install pyenv node
pyenv install 3.11.9
pyenv local 3.11.9
npm install -g pnpm             # optional but faster than npm
autopep8 --install              # optional, for editor formatting

​

2.1 – Backend Setup

cd backend
uv pip install -r requirements.txt
# OR fallback
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

--reload watches Python files under backend/ and restarts the server on change.

​

2.2 – Frontend Setup

cd frontend
npm install
npm run dev -- --open   # starts Vite dev server at :5173

The front-end uses Vite’s HMR (Hot Module Replacement). Every change to .svelte or .ts files triggers an in-browser update within ~50 ms.

​

2.3 – Environment Variables

Create .env in backend/ if you need custom paths:

DATASETS_DIR=/mnt/ssd/mako/datasets
FUNCTIONS_DIR=/mnt/ssd/mako/functions

The backend reads these using python-dotenv (see backend/main.py#init_data_directories).

​

3 – Verifying Installation

Run the smoke test below to ensure both services are operational.

curl -X POST http://localhost:8001/api/execute \
  -H 'Content-Type: application/json' \
  -d '{"code": "print(2 + 2)"}'

Expected response:

{
  "stdout": "4\n",
  "stderr": "",
  "success": true
}

If this works, the backend is executing code. Open the browser UI, create a new Python tab, and press ⌘↵ to replicate the same test. A green toaster notification should appear with Execution succeeded.

​

4 – Common Issues

1. Port Already in Use – Stop other services on 5173 or 8001, or change ports in vite.config.ts / docker-compose.yml.
2. Missing Graphics Backend on Linux servers (e.g., Bokeh wants fonts). Configure MPLBACKEND=Agg or install system fonts.
3. Unsupported CPU Instructions – Polars ships AVX2 wheels; fallback to pip install polars==0.19.7 --no-binary :all: if running on older hardware.

​

5 – Next Steps

Installation is only step 1. Continue to Architecture Overview to learn how the backend and front-end communicate, or jump straight into the API Reference for endpoint specifics.