Skip to content

running-the-dev-env-locally.md

Latest commit

 

History

History
433 lines (318 loc) · 9.07 KB

running-the-dev-env-locally.md

File metadata and controls

433 lines (318 loc) · 9.07 KB

Running the Dev Environment Locally (Without Docker)

This guide covers running Baserow's backend and frontend natively on your machine, using Docker only for infrastructure services (PostgreSQL, Redis). This approach offers faster iteration, easier debugging, and better IDE integration compared to full Docker development.

Prerequisites

Required Tools

  1. Docker - For running PostgreSQL, Redis, and other services

  2. just - Command runner

    # macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

  3. Python 3.14 - For the backend

    # macOS
brew install python@3.14

# Linux (Ubuntu/Debian)
sudo apt install python3.14 python3.14-dev

  4. uv - Fast Python package manager

    # macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

  5. Node.js 24 - For the frontend

    # Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24
nvm use 24

# macOS with Homebrew
brew install node@24

  6. Yarn - Frontend package manager

    npm install -g yarn

  7. Git - Install from https://git-scm.com/downloads

See supported.md for minimum version requirements.

Verify Installation

docker -v
just --version
python3 --version
uv --version
node -v
yarn -v
git --version

Quick Start

# Clone the repository
git clone --branch develop https://github.com/baserow/baserow.git
cd baserow

# Initialize backend and frontend (creates venv, installs deps, creates .env.local)
just init

# Start everything (Ctrl+C to stop)
just dev up

Once started, access:

To run in background:

just dev up -d   # Start in background
just dev logs    # View logs
just dev ps      # Check what's running
just dev stop    # Stop all services
just dev tmux    # Alternative: start tmux session with all services (you need to install tmux first)

How It Works

The just dev up command orchestrates:

  1. Docker services: PostgreSQL, Redis, Mailhog, OpenTelemetry collector
  2. Database migrations: Applied automatically
  3. Backend server: Django development server on port 8000
  4. Celery workers: Background task processing (main, export, beat scheduler)
  5. Frontend server: Nuxt development server on port 3000
just dev up
├── Docker: db, redis, mailhog, otel-collector
├── Backend: Django dev server (port 8000)
├── Celery: main worker + export worker + beat scheduler
└── Frontend: Nuxt dev server (port 3000)

All processes log to /tmp/:

  • /tmp/baserow-backend.log
  • /tmp/baserow-celery.log
  • /tmp/baserow-web-frontend.log

Environment Configuration

The .env.local File

The just init command creates .env.local in the project root with sensible defaults, taken from .env.local-dev.example:

# Key settings in .env.local
DATABASE_HOST=localhost
DATABASE_PORT=5432
REDIS_HOST=localhost
REDIS_PORT=6379
SECRET_KEY=<auto-generated>
DJANGO_SETTINGS_MODULE=baserow.config.settings.dev
SYNC_TEMPLATES_ON_STARTUP=false

All backend commands automatically load this file.

Customizing Settings

Look at Configuration to customize your environment.

Common Commands

Shortcuts: b = backend, f = frontend

Backend Commands

All backend commands can be run from the project root with just backend (or just b) or from backend/:

# From project root (just b is shorthand for just backend)
just b test              # Run tests
just b lint              # Run linters
just b fix               # Auto-fix code style
just b shell_plus        # Django shell_plus with SQL logging
just b m makemigrations  # Create migrations
just b m migrate         # Apply migrations

# From backend/
cd backend
just test
just lint
just shell_plus

Frontend Commands

# From project root (just f is shorthand for just frontend)
just f lint              # Run ESLint + Stylelint
just f test              # Run Jest tests
just f fix               # Auto-fix code style

# From web-frontend/
cd web-frontend
just lint
just test

Viewing Logs

Works like docker compose logs - services and options can be in any order:

just dev logs                      # All services (backend, celery, frontend)
just dev logs -f                   # Follow all logs in real-time
just dev logs backend              # Backend only
just dev logs backend celery       # Backend and celery
just dev logs -f backend           # Follow backend only
just dev logs backend -n 100       # Last 100 lines of backend
just dev logs -n 50 backend celery # Last 50 lines of backend and celery

Managing Docker Services

# Start only database and redis
just dc-dev up -d db redis

# Stop Docker services
just dc-dev stop db redis

# View Docker service logs
just dc-dev logs db

Manual Setup (Alternative)

If you prefer more control over each component:

1. Start Infrastructure Services

just dc-dev up -d db redis mailhog

2. Initialize Backend

cd backend
just init          # Creates venv, installs deps
just migrate       # Apply migrations

3. Run Backend Server

cd backend
just run-dev-server

4. Run Celery Workers (separate terminal)

cd backend
just run-dev-celery

5. Initialize and Run Frontend (separate terminal)

cd web-frontend
just install           # Install node_modules
just run-dev-server    # Start Nuxt dev server

Running Tests

Backend Tests

# Run all tests
just b test

# Run tests in parallel (faster)
just b test -n=auto

# Run specific test file
just b test tests/baserow/core/test_core_models.py

# Run with coverage
just b test-coverage

Fast Tests with Ramdisk Database

For 2-5x faster tests, use a PostgreSQL container with tmpfs:

# Start ramdisk database (port 5433)
just test-db start

# Run tests against it
DATABASE_URL=postgres://baserow:baserow@localhost:5433/baserow just b test -n=auto

# Stop when done
just test-db stop

Frontend Tests

just f test              # Run Jest tests
just f test --watch      # Watch mode

Database Operations

Running Migrations

just b migrate
# or
just b m migrate

Creating Migrations

just b m makemigrations
just b m makemigrations core  # Specific app

Creating a Superuser

just b m createsuperuser

Syncing Templates

Templates (example databases, forms, etc.) are not synced by default for faster startup:

just b m sync_templates

Accessing the Database

# Django database shell
just b m dbshell

# Direct PostgreSQL (via Docker)
just dc-dev exec db psql -U baserow

Resetting the Database

# Stop Docker, remove volumes, restart
just dc-dev down -v
just dc-dev up -d db redis
just b migrate

Debugging

Backend Debugging

The Django dev server supports standard Python debugging:

# Add breakpoint in your code
breakpoint()  # or: import pdb; pdb.set_trace()

For VS Code, add to .vscode/launch.json:

{
  "name": "Django Backend",
  "type": "python",
  "request": "launch",
  "program": "${workspaceFolder}/backend/src/baserow/manage.py",
  "args": ["runserver", "0.0.0.0:8000"],
  "django": true,
  "env": {
    "DJANGO_SETTINGS_MODULE": "baserow.config.settings.dev"
  },
  "envFile": "${workspaceFolder}/.env.local"
}

Celery Debugging

# Run with debug logging
CELERY_LOG_LEVEL=DEBUG just b run-dev-celery

Troubleshooting

"Module not found" Errors

just b uv sync
just f yarn

Database Connection Errors

# Ensure Docker services are running
just dc-dev ps

# Check if PostgreSQL is ready
just dc-dev exec db pg_isready -U baserow

# Verify .env.local settings
grep DATABASE .env.local

Port Already in Use

# Find what's using the port
lsof -i :8000
lsof -i :3000

# Kill the process or change the port
kill -9 $(lsof -i :8000 | awk 'NR==2 {print $2}')
kill -9 $(lsof -i :3000 | awk 'NR==2 {print $2}')

Celery Crashes on macOS

The justfile defaults to solo pool on macOS to avoid fork() issues:

# Force a different pool if needed
CELERY_POOL=threads just b run-dev-celery

Frontend Build Errors

# Clear node_modules and reinstall
rm -rf web-frontend/node_modules
just f install

# Clear Nuxt cache
rm -rf web-frontend/.nuxt

Further Reading