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

   Commit these changes to your repository 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 v26
npm install -g pnpm@latest-11 # 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.