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:

Start the services first

PostgreSQL, Redis and RustFS must be running before you create the databases and bucket. In Laravel Herd Pro, add them under Settings → Services using the versions in herd.yml (PostgreSQL 16, Redis 7.0.0, RustFS 1.0.0). herd init in step 4 then links the site to them.

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 RustFS Bucket

   Create a bucket for local object storage in the RustFS console (http://localhost:9001 in Herd, signing in as herd / secretkey):

   your-project-name

   Then open the bucket’s settings, edit Bucket CORS, and save the default rule. Livewire uploads files directly from the browser to the bucket, and RustFS sends no CORS headers until a rule exists.

   With Serve over HTTPS enabled in Herd’s RustFS service settings, the S3 API is available at https://rustfs.herd.<tld> on macOS and https://rustfs-9000.herd.<tld> on Windows, where <tld> is your Herd TLD.

   You can also create the bucket and its CORS rule from the command line with the RustFS CLI, rc (brew install rustfs/tap/rc on macOS):

   rc alias set local https://rustfs.herd.test herd secretkey
   rc bucket create local/your-project-name
   echo '{"CORSRules":[{"AllowedOrigins":["*"],"AllowedMethods":["GET","PUT","POST","DELETE","HEAD"],"AllowedHeaders":["*"],"ExposeHeaders":["ETag"]}]}' \
       | rc bucket cors set local/your-project-name -

   Windows

   Herd’s Internal API Port (Settings → General) defaults to 9001, the same port as the RustFS console. Change it to another port, such as 9009, before starting RustFS, or the herd CLI can fail with access denied errors.

   Note

   Herd’s RustFS 1.0.0 service, which herd.yml requests, is currently only published for Apple silicon. On an Intel Mac, install the RustFS version Herd offers and change the version in your local herd.yml.

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_URL=https://rustfs.herd.test/your-project-name
   AWS_ENDPOINT=https://rustfs.herd.test
   AWS_BUCKET=your-project-name

   Replace test in AWS_URL and AWS_ENDPOINT with your Herd TLD (use rustfs-9000.herd.<tld> on Windows). AWS_URL ends with the bucket 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-12 # If pnpm is not already installed

pnpm install
pnpm build

5. Environment Configuration

A local environment needs no credentials. With the .env.example values, the sign-in page offers Sign In As for the seeded demo users, db:rebuild makes no network calls, and config:validate skips the SSO and Directory Search checks. See Signing In Locally.

Configure SSO and Directory Search locally only to test real NetID sign-in or to add Northwestern users from the directory. Deployed environments always need them. See the WebSSO / Entra ID documentation for full details on each provider.

Note

Entra ID only redirects back to the redirect URIs registered for the application in Azure, so local NetID sign-in works only at a host you have registered. Worktrees and agents on other hosts or ports use Sign In As instead.

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:

• Clear the cache, the queue and the schedule cache (Redis must be running)
• Create all database tables
• Seed system permissions, role types and default roles
• Sync changelog entries from resources/changelogs/
• Seed the demo users, which the sign-in page offers under Sign In As
• Regenerate the model IDE helper files

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 processes:

composer dev

This runs the PHP server, a queue worker, the log viewer and Vite together. The queue worker is required: jobs go to Redis (QUEUE_CONNECTION=redis), and email sign-in codes are not sent until a worker runs them.

With Laravel Herd, the site is served at https://your-project-name.test. Without Herd, use the address php artisan serve prints.

As a guest you should see the landing page. Choose Sign In, then Sign In As… and a demo user such as NUIT Administrator, and you land in the app panel at /app.