Skip to content

getting-started.md

Latest commit

 

History

History
261 lines (178 loc) · 4.94 KB

getting-started.md

File metadata and controls

261 lines (178 loc) · 4.94 KB

Getting Started

This guide gets the Pioreactor monorepo running on a development laptop:

  • Flask web API: make web-dev
  • React frontend: make frontend-dev
  • Huey task consumer: make huey-dev
  • Local CLI: pio

The development flow is POSIX-shell based. On macOS, use Terminal. On Windows, use WSL2 with Ubuntu rather than PowerShell or native cmd.exe.

1. Install system dependencies

macOS

Install Homebrew if needed, then install the basic runtime tools:

brew install python@3.13 node@20 direnv make mosquitto

Make sure python3.13, node, npm, make, and direnv are available:

python3.13 --version
node --version
npm --version
make --version
direnv --version

Windows

Use WSL2:

wsl --install -d Ubuntu

Open Ubuntu, then install the base tools:

sudo apt update
sudo apt install -y build-essential curl git make direnv mosquitto

Install Python 3.13 and Node 20. The most reliable cross-distro option is pyenv for Python and nvm for Node:

curl https://pyenv.run | bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Restart the Ubuntu shell, then:

pyenv install 3.13.0
pyenv global 3.13.0
nvm install 20
nvm use 20

Confirm:

python3.13 --version
node --version
npm --version

Keep the repo inside the Linux filesystem, for example ~/code/pioreactor, not under /mnt/c/.... File watching and virtualenv behavior are much better there.

2. Clone the repo

git clone https://github.com/Pioreactor/pioreactor.git
cd pioreactor

If you already have the repo, start from its root directory.

3. Create local development state

The app expects a Pioreactor data root with config, storage, plugins, and export directories. For local development, keep that under the repo as .pioreactor.

mkdir -p .pioreactor/storage .pioreactor/cache .pioreactor/plugins .pioreactor/experiment_profiles .pioreactor/exportable_datasets plugins_dev
cp -n config.dev.ini .pioreactor/config.ini
touch .pioreactor/unit_config.ini

Do not commit .envrc, .pioreactor/, plugins_dev/, or generated local state.

4. Configure direnv

Create a local .envrc:

export TESTING=1
export HOSTNAME=localhost
export ACTIVE=1

export DOT_PIOREACTOR="$PWD/.pioreactor"
export GLOBAL_CONFIG="$DOT_PIOREACTOR/config.ini"
export RUN_PIOREACTOR="$DOT_PIOREACTOR"
export PLUGINS_DEV="$PWD/plugins_dev"

export PIO_EXECUTABLE="$PWD/.venv/bin/pio"
export PIOS_EXECUTABLE="$PWD/.venv/bin/pios"
PATH_add "$PWD/.venv/bin"

export HARDWARE=1.1
export FIRMWARE=1.1
export MODEL_NAME=pioreactor_40ml
export MODEL_VERSION=1.5

export BLINKA_FORCECHIP=BCM2XXX
export BLINKA_FORCEBOARD=RASPBERRY_PI_4B

Allow it:

direnv allow

Check that the required variables are loaded:

make check-env

If you do not use direnv, export the same variables manually in every shell before running make, pio, or pios. Replace the PATH_add line with export PATH="$PWD/.venv/bin:$PATH".

5. Install dependencies

Install Python dependencies and the editable pio / pios commands:

make install

Install frontend dependencies:

make frontend-install

Confirm the CLI is available:

command -v pio
pio version

If command -v pio prints nothing, reload the shell or run:

direnv reload

You can always run the CLI directly as:

.venv/bin/pio version

6. Start MQTT for local UI work

Many pages still load without MQTT, but live job state, charts, and browser MQTT subscriptions need a local broker. Use this small dev config:

mkdir -p scratch
cat > scratch/mosquitto-dev.conf <<'EOF'
listener 1883 127.0.0.1
allow_anonymous true

listener 9001 127.0.0.1
protocol websockets
allow_anonymous true
EOF

Start Mosquitto in its own terminal:

mosquitto -c scratch/mosquitto-dev.conf

Leave it running while using the web UI.

7. Start the dev services

First ask the Makefile what is already running:

make dev-status

Start only the services listed under Need to start. In separate terminals:

make huey-dev
make web-dev
make frontend-dev

The web API listens on http://127.0.0.1:4999. The React dev server listens on http://localhost:3000 and proxies API requests to http://localhost:4999.

Open:

http://localhost:3000

8. Verify the setup

Run these checks from the repo root:

make dev-status
pio version
pio workers
curl -fsS http://127.0.0.1:4999/unit_api/health

Common problems

pio is not found

The pio command is created by make install when it installs core/ in editable mode. Run:

PYTHON=python3.13 make install
direnv reload
command -v pio

Or use .venv/bin/pio directly.

Frontend starts but API calls fail

Make sure the Flask API is running:

make dev-status

If Flask web API is missing, start:

make web-dev