Installation¶

Get Craft Easy up and running on your machine. Every package in the ecosystem can be installed independently, but most projects pull in craft-easy-api first and add the rest as needed.

Prerequisites¶

Requirement	Version	Notes
Python	3.12	3.13+ is not yet supported (Beanie/Pydantic compatibility).
MongoDB	6.0+	Use a replica set (`directConnection=true` for single-node dev) so that change streams and transactions work.
Node.js	20+	Only if you use the admin app.
`pip` / `venv`	bundled	Or any PEP 668-compatible installer (uv, pipx, poetry).

Verify your environment:

python3.12 --version      # Python 3.12.x
mongosh --eval "db.runCommand({ping:1})" --quiet
node --version            # v20.x or higher

Install craft-easy-api¶

The API framework is the foundation. Install it into a project virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
pip install craft-easy-api

During early development (pre-1.0) you can also install directly from GitHub:

pip install "craft-easy-api @ git+https://github.com/easy-software-system/craft-easy-api.git@main"

Verify the install:

python -c "import craft_easy; print(craft_easy.__version__)"

Install the standalone packages¶

These are optional — add them only if you need what they offer.

craft-easy-jobs (CLI job runner)¶

pip install craft-easy-jobs

Use this for stateless batch jobs, cron tasks in Kubernetes CronJob or GitHub Actions, or ad-hoc manual runs. See craft-easy-jobs CLI for when to prefer it over the API's built-in jobs module.

craft-easy-file-import (file & reconciliation service)¶

pip install craft-easy-file-import

This ships with bank-file parsers (BgMax, SEPA camt.054), generic parsers (CSV, JSON, FlatFile), and a poll-based runner that pushes to any Craft Easy API. It has an optional dependency on craft-easy-api — install both if you need SFTP or WatchedDirectory sources.

craft-easy-template (cookiecutter scaffolds)¶

pip install cookiecutter

The template itself is consumed via cookiecutter, not pip install. See Project Templates.

Install the admin app¶

The admin app is a React Native + Expo project that you run as a separate process. You can either install the npm package or clone the repo.

Option 1 — npm package¶

npm install @craft-easy/admin

Option 2 — clone the repo¶

git clone https://github.com/easy-software-system/craft-easy-admin.git
cd craft-easy-admin
npm install
npm run web          # Run in the browser
npm run ios          # Run on iOS simulator
npm run android      # Run on Android emulator

The admin app connects to any Craft Easy API by fetching its /admin/schema endpoint. Point it at your local API on http://localhost:5001 once the API is running.

MongoDB for development¶

The quickest way to run MongoDB locally is Docker with a single-node replica set:

docker run -d --name craft-easy-mongo -p 27017:27017 \
  mongo:7 --replSet rs0

# Initialize the replica set (one-time)
docker exec -it craft-easy-mongo mongosh --eval 'rs.initiate()'

Connection string for your app:

mongodb://localhost:27017/?directConnection=true

Verify the install¶

Start a minimal API to confirm everything is wired up:

python -c "
from craft_easy import create_base_app
print('craft-easy-api is installed')
"

If you see that line printed, the framework is ready. Move on to the Quick Start to create your first resource.

Troubleshooting¶

Symptom	Fix
`ImportError: cannot import name 'create_base_app'`	You installed an old version. Upgrade with `pip install -U craft-easy-api`.
`ServerSelectionTimeoutError` on startup	MongoDB is not running, or you forgot `?directConnection=true` against a single-node replica set.
`TypeError` from Pydantic	You are on Python 3.13+. Downgrade to 3.12.
`ModuleNotFoundError: jwt`	Reinstall with `pip install 'pyjwt[crypto]>=2.10'` — the `crypto` extra is required for ES512.