Each step is a command you can copy. Check them off as you go — your progress is saved and survives a refresh.

1 · Set up your environment

From the project root, create a virtual environment and install both the runtime and dev dependencies.

python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt -r requirements-dev.txt

Windows (PowerShell): python -m venv .venv; .venv\Scripts\Activate.ps1; pip install -r requirements.txt -r requirements-dev.txt

2 · Run the doctor

The doctor is the pre-flight check. It inspects your project, works out which secrets and environment variables the code and configs need, writes a .env with the required keys, and boots the app in a sandbox to prove it starts. Run it first — the next step fills in the keys it laid out.

It runs the project's forjedoctor.py under your .venv. Use --strict to treat warnings as failures.

3 · Generate your secrets

Fill the .env the doctor created with real values. fabbro secret gen writes a FERNET_KEY (vault encryption) and a SECRET_KEY (session signing) in place — placeholders will not boot.

.env holds secrets and is already in .gitignore — never commit it. .env.local holds non-secret dev infra (DB_PATH, APP_BASE_URL).

4 · Confirm green

Run the doctor once more. With the secrets in place it should sandbox-boot the app cleanly — green means you are ready to run.

5 · Create your admin

Create the first admin account. This is the only way an admin is made — the role is CLI-only. The command prompts for an email and a hidden password.

6 · Run the app

The app is a WSGI callable (app:app) — it does not self-serve, so run it under a server. For local development, Flask's built-in server is enough; it reads DB_PATH from .env.local and creates the database schema on first boot.

Then open http://127.0.0.1:5000 — the login screen, already styled, auth working out of the box. In production the bundled docker-compose serves it with gunicorn on port 8000.

7 · Start the workers (when you need async)

Background jobs — sending email, and anything you enqueue — run in separate worker processes, not in the web app. Each reads the same database. Start them alongside the app when you need them.

The web app and every worker must point at the same local DB file — never a network filesystem. In production, compose runs these as their own services.

What you have right now, for free: working authentication (two credential flows, three roles), transactional email with a styled template, admin and client dashboards, an external-API registry, and a responsive design system with dark/light themes — before a single line of business logic. From here, load the project's skills into your AI agent and start building modules the Fabbro way.
← Back to playbooks