Installation

Initial Setup

1. Create Project

composer create-project northwestern-sysdev/northwestern-laravel-starter your-project-name
cd your-project-name

Then initialize a fresh Git repository:

git init -b develop # or `main` depending on your branching strategy
git add .
git commit -m "chore: initial commit from Northwestern Laravel Starter"

2. Provision Required Services

The application expects specific services to exist before you can begin local development:

1. Create Databases

   Create the two databases required by the application:

   your_project_name_local   # Primary application database
   your_project_name_test    # PHPUnit test database

2. Create MinIO Bucket

   Create a bucket for local object storage:

   your-project-name

3. Update Configuration Files

1. .env.example

   Update the file by referencing the services you created in the previous step and setting other project-specific defaults:

   .env.example

   APP_NAME="Your Project Name"
   APP_URL=https://your-project-name.test
   DB_DATABASE=your_project_name_local
   DB_PHPUNIT_DATABASE=your_project_name_test
   AWS_BUCKET=your-project-name

   Ideally, these changes should be committed to your repository to serve as the base configuration for other developers.

2. herd.yml

   If you’re using Laravel Herd, update the name field to match your folder/repository name:

   herd.yml

    name: northwestern-laravel-starter
    name: your-project-name

4. Install Dependencies

herd init    # If using Laravel Herd
herd secure  # If using Laravel Herd

composer install
cp .env.example .env
php artisan key:generate

nvm install
nvm use v25
npm install -g pnpm@latest-10 # If pnpm is not already installed

pnpm install
pnpm build

5. Environment Configuration

In your LOCAL .env file, configure credentials depending on your authentication strategy. See the WebSSO / Entra ID documentation for full details on each provider.

Entra ID

If your application uses Microsoft Entra ID (the default):

.env

AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
DIRECTORY_SEARCH_API_KEY=your-value-here
EVENT_HUB_API_KEY=your-value-here # Only if the EventHub integration is needed

Tip

AZURE_CLIENT_ID can also be set in .env.example as a shared default for your team.

Online Passport (WebSSO)

If your application uses Online Passport (agentless WebSSO):

.env

WEBSSO_URL_BASE=https://prd-nusso.it.northwestern.edu
WEBSSO_API_URL_BASE=https://northwestern-prod.apigee.net/agentless-websso
WEBSSO_API_KEY=your-api-key
DIRECTORY_SEARCH_API_KEY=your-value-here
EVENT_HUB_API_KEY=your-value-here # Only if the EventHub integration is needed

Tip

Setting WEBSSO_API_KEY automatically switches the starter from Entra ID to Online Passport. See the WebSSO / Entra ID docs for additional configuration options like WEBSSO_STRATEGY and DUO_ENABLED.

6. Validate Configuration

To ensure your environment is correctly configured, run:

php artisan config:validate

If any issues are detected, the command will output error messages to help you resolve them.

7. Database Scaffolding

php artisan db:rebuild

This will:

• Create all database tables
• Seed system permissions
• Seed default roles
• Seed role types
• Seed example users

Caution

This command is only intended for local and testing environments. Use this as needed as the schema or seeders change during development.

Verification

Test the Application

Start the development server:

# If using Laravel Herd, your site should already be available at:
http://your-project-name.test

# Otherwise, use the built-in PHP server:
php artisan serve

Visit the application in your browser. You should see the homepage.