Installation
Install the lex-app package. This gives you the lex CLI tool and all framework dependencies.
pip install lex-appVerify it worked:
lex --versionMake sure you're using Python 3.12. Check with
python3.12 --version.
Run the Setup Wizard
Navigate to your project directory and run:
lex setupThis generates three things for you:
.run/— PyCharm run configurations (Init, Start, Streamlit).env— Environment configuration templatemigrations/— Django migrations folder
Configure Your Environment
The .env file is the single source of truth for runtime configuration.
Option A: Automatic (Recommended)
Run lex setup and follow the prompts. The wizard will open Excellence Cloud for you, guide you through creating a new Client, and auto-populate your .env file.
Option B: Manual
- Log in to Excellence Cloud
- Go to Clients and Click Create a new Client
- Select client type → development
- Enable confidential
- Copy the credentials into your
.env:
KEYCLOAK_URL=keycloak_url
KEYCLOAK_REALM=keycloak_realm
OIDC_RP_CLIENT_ID=your_client_id
OIDC_RP_CLIENT_SECRET=your_client_secret
OIDC_RP_CLIENT_UUID=your_client_uuidInitialize the Application
lex Init is the primary initialization command. It does three things:
- Applies migrations — creates/updates database tables from your models
- Syncs to Keycloak — registers your project models as "Resources" and permissions as "Scopes"
- Enables access management — you can now manage permissions on Excellence Cloud
Via PyCharm (easiest)
- Open the Run Configuration dropdown (top-right toolbar)
- Select "Init"
- Click the green ▶️ Run button (or press
Shift+F10)
PyCharm automatically loads your .env file.
Via Terminal
# Load environment variables first
set -a; source .env; set +a
# Then initialize
lex InitIf your Keycloak credentials are still missing, run
lex Init --bootstrapinstead. It opens the browser-based setup flow and then continues with the normal init steps.
Windows (PowerShell)
# Load environment variables Get-Content .env | ForEach-Object { if ($_ -match '^([^=]+)=(.*)$') { [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2]) } } # Initialize lex Init
When to run
lex Initagain: Whenever you add a new model, new field, or change permission methods — any change that creates a new migration file.
Start the Dev Server
Via PyCharm
Select "Start" from the Run Configuration dropdown → click ▶️.
Via Terminal
set -a; source .env; set +a
lex start --reload --loop asyncio lex_app.asgi:applicationYour application is now running at http://localhost:8000.
Troubleshooting
"Environment variable not set" errors
- PyCharm: Make sure
.envis in your project root- Terminal: Always run
set -a; source .env; set +abefore anylexcommand
"ModuleNotFoundError: lex" errors
- Make sure
lex-appis installed:pip install lex-app- Verify you're using Python 3.12
- Check that your virtual environment is activated
Keycloak connection errors
- Verify
KEYCLOAK_URLin your.env- Check that
OIDC_RP_CLIENT_IDandOIDC_RP_CLIENT_SECRETare correct- Confirm your client exists on Excellence Cloud
"
lex Initrefuses to sync this client"
- In local development,
lex Initexpects a confidential Keycloak client with alocalhostredirect URI- If you're intentionally using a different setup, rerun with
lex Init --skip-client-preflight
Got everything set up? Learn about the Project Structure or jump straight to Running Your App.
Was this helpful?
Your feedback shapes what we write next.
