Local Setup

Prerequisites

Before you start, make sure you have installed:

Python 3.9+ — python --version
Node.js 18+ — node --version
MySQL 8.0+ — running locally on port 3306
Git — git --version
Access to the private GitHub repo (ask your team lead)

Step-by-step setup

Clone the repository

git clone https://github.com/OrchidSoftwareSolutions/orchid.git
cd orchid

Create and activate a Python virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

Install Python dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt

Create a local MySQL database

Open your MySQL client (Workbench, TablePlus, or CLI) and run:
```
CREATE DATABASE local_main CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
The database name local_main is the default — you can change it, but you’ll need to update your config file to match.

Create localflaskapp.cfg

Copy the template and fill in your values:

cp localflaskapp.cfg.example localflaskapp.cfg

At minimum, set these keys:

# Database — required
DB_HOST = 'localhost'
DB_USER = 'root'
DB_PASS = 'your_mysql_password'
DB_NAME = 'local_main'
DB_PORT = 3306

# App secrets — required (any random string works locally)
SECRET_KEY = 'dev-secret-key-change-in-prod'
FORM_KEY = 'dev-form-key-change-in-prod'

# Email — set to your own email for testing
SYSTEM_EMAIL = 'you@example.com'
ADMIN_EMAIL = 'you@example.com'
DEFAULT_EMAIL = 'you@example.com'

# External services — leave blank or use sandbox keys
# (SendGrid, Stripe, Twilio, Salesforce, HelloSign, Gurgle,
#  MSFT_APP_ID, GMAIL_CLIENT_ID_TEST are all optional for basic dev)
SENDGRID_API_KEY = ''
STRIPE_PK_TEST = ''
STRIPE_SK_TEST = ''

Run database migrations
Terminal window
```
flask db upgrade
```
This creates all tables. If this fails with a “no module named flask” error, make sure your virtual environment is activated.
Create a test agency

Run the setup script to seed an agency record:
Terminal window
```
python scripts/create_orchid_admin.py
```
Follow the prompts to create the first admin user. This seeds the agency table with a single row (remember: one agency per database).
Install frontend dependencies and build
Terminal window
```
npm install
npm run build-dev
```
Start the development server
Terminal window
```
python flaskapp.py
```
The app will be available at http://localhost:5000. Log in at http://localhost:5000/admin/login with the credentials you created in step 7.

# All tests
pytest

# Single file
pytest tests/orchid/utils/test_html_sanitizer.py

# Single test
pytest tests/orchid/utils/test_html_sanitizer.py::TestClass::test_method

# By marker
pytest -m unit
pytest -m integration

Tests use an in-memory SQLite database (configured in tests/conftest.py). You do not need a running MySQL instance to run tests.

npm test                # Run all Jest tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Test files live in tests/js/**/*.test.js. The test environment uses jsdom (a browser-like DOM for Node.js).

Rebuilding the frontend

npm run build-dev   # Fast dev build (no minification)
npm run build-prod  # Slow prod build (minified, tree-shaken)
npm run build       # Both dev + prod

Changes to .mjs or .scss files in static/js/ require a rebuild before they take effect. The dev server does not hot-reload JS/CSS.

Common local issues

Problem	Likely cause	Fix
`ModuleNotFoundError`	venv not activated	`venv\Scripts\activate` (Windows) or `source venv/bin/activate`
`flask db upgrade` fails	MySQL not running	Start MySQL service
`no agency found` error	DB not seeded	Run `create_orchid_admin.py`
Login redirects to itself	`SECRET_KEY` not set	Add `SECRET_KEY` to `localflaskapp.cfg`
Emails not sending	`SENDGRID_API_KEY` blank	Expected in local mode — check console logs instead
JS changes not reflected	Bundle not rebuilt	`npm run build-dev`

Config precedence

Orchid loads config in this order (later files override earlier ones):

flaskapp.cfg — Production defaults (committed, no secrets)
localflaskapp.cfg — Local overrides (not committed, has secrets)
Environment variables — EB environment config in production