Installation

Initial Setup

1. Clone Project

If you’re starting a new project using this starter:

# Clone the repository
git clone https://github.com/NIT-Administrative-Systems/northwestern-laravel-starter.git your-project-name
cd your-project-name

# Initialize a fresh 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:

Create Databases

Create the two databases required by the application:

your_project_name_local   # Primary application database
your_project_name_test    # PHPUnit test database

Create MinIO Bucket

Create a bucket for local object storage:
```
your-project-name
```

3. Update Configuration Files

.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
AZURE_CLIENT_ID=your-azure-entra-id-client-id
```
Ideally, these changes should be committed to your repository to serve as the base configuration for other developers.
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, the following environment variables must be set:

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

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

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.