laravel

Complete deployment guide for laravel on NStrim

Overview

Laravel is a PHP web application framework with expressive, elegant syntax. This guide will walk you through deploying a Laravel application on the NStrim platform from start to finish.

Before You Start
Make sure you have your dashboard open - you'll need the credentials displayed there (username, password, and database connection details).

Quick Start

1

Create Repository from Template

On your dashboard, go to the Tools & Deployment tab. Click the "New Repository" button, select the Laravel template from the dropdown, enter a repository name and subdomain, then click "Create Repository".

2

Clone Your Repository

git clone https://<git-server>/<username>/<repo-name>.git
cd <repo-name>
3

Install Dependencies

composer install
4

Configure Environment

Copy the example environment file and configure your database (see detailed instructions below):

cp .env.example .env
php artisan key:generate
5

Run Migrations & Push

php artisan migrate
git add .
git commit -m "Initial setup"
git push origin main
Every push to Git automatically deploys your application. Check your Module Work URL on the dashboard to see your live site.

Local Development with Docker

If you don't have PHP installed locally, you can use Docker to run Laravel commands. The project includes a Dockerfile that sets up everything you need.

What is Docker?
Docker creates isolated "containers" with all the software you need (PHP, Composer, Node.js) without installing them on your computer. Think of it like a lightweight virtual machine.

Prerequisites

Install Docker Desktop for your operating system (Windows, Mac, or Linux).

Running Commands with Docker

Instead of running php artisan migrate directly, you run it inside a Docker container: 

# Build the Docker image (only needed once)
docker build -t laravel-app .

# Run any artisan command
docker run --rm laravel-app php artisan migrate

# Run composer install
docker run --rm -v $(pwd):/var/www/html laravel-app composer install

# Interactive shell inside container
docker run --rm -it -v $(pwd):/var/www/html laravel-app bash
Note
Docker is optional for local development. The NStrim platform handles deployment automatically - you only need Docker if you want to run commands locally without PHP installed.

Database Configuration

The NStrim platform provides you with a MySQL/MariaDB database. You need to configure your .env file with the correct database credentials to connect.

Why Configure the Database?

Laravel uses a .env file to store environment-specific configuration. By default, the template uses SQLite (a file-based database), but NStrim provides MySQL for better performance and compatibility with real-world scenarios.

Step-by-Step Configuration

1

Open Your .env File

Open the .env file in your project root with your code editor.

2

Find the Database Section

Look for these lines (usually around line 23):

DB_CONNECTION=sqlite
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=laravel
# DB_USERNAME=root
# DB_PASSWORD=
3

Update with Your Credentials

Replace with the credentials from your dashboard:

DB_CONNECTION=mysql
DB_HOST=db.<session-domain>
DB_PORT=3306
DB_DATABASE=<your-username>
DB_USERNAME=<your-username>
DB_PASSWORD=<your-password>
Important
Your database name and username are typically the same as your dashboard username (e.g., student01). Check your dashboard credentials section for exact values.

Example Configuration

If your username is student01 and session domain is demo.nstrim.app:

DB_CONNECTION=mysql
DB_HOST=db.demo.nstrim.app
DB_PORT=3306
DB_DATABASE=student01
DB_USERNAME=student01
DB_PASSWORD=your-password-from-dashboard

Running Migrations

Migrations are Laravel's way of creating database tables. After configuring your database, run migrations to set up the required tables: 

php artisan migrate

If you need to reset and re-run all migrations (this will delete all data): 

php artisan migrate:fresh

To run migrations with seed data (if your project has seeders): 

php artisan migrate:fresh --seed

Project Structure

Understanding where files are located:

├── app/                  # Application code
│   ├── Http/
│   │   └── Controllers/  # Your controllers go here
│   └── Models/           # Eloquent Models
├── config/               # Configuration files
├── database/
│   ├── migrations/       # Database migrations
│   └── seeders/          # Database seeders
├── public/               # Public assets (CSS, JS, images)
├── resources/
│   └── views/            # Blade templates
├── routes/
│   └── web.php           # Web routes (URL → Controller)
├── .env                  # Environment configuration (DB, etc.)
└── composer.json         # PHP dependencies

Common Tasks

Creating a New Controller

php artisan make:controller ProductController

Creating a New Model with Migration

php artisan make:model Product -m

Adding a Route

Edit routes/web.php:

Route::get('/products', [ProductController::class, 'index']);

Clearing Cache

php artisan cache:clear
php artisan config:clear
php artisan view:clear

Useful Commands

php artisan serve Start local development server
php artisan migrate Run database migrations
php artisan migrate:status Check migration status
php artisan make:controller Create a new controller
php artisan make:model -m Create model with migration
php artisan route:list List all registered routes
php artisan tinker Interactive PHP shell for testing

Troubleshooting

SQLSTATE[HY000] [2002] Connection refused

Cause: Database host is incorrect or database server is not accessible.

Solution: Check that DB_HOST in your .env file matches the database host from your dashboard (usually db.<session-domain>).

SQLSTATE[HY000] [1045] Access denied for user

Cause: Wrong username or password.

Solution: Double-check DB_USERNAME and DB_PASSWORD match exactly what's shown in your dashboard. Passwords are case-sensitive!

SQLSTATE[HY000] [1049] Unknown database

Cause: Database name doesn't exist.

Solution: Verify DB_DATABASE is set to your username (e.g., student01). Your database is pre-created with the same name as your username.

No application encryption key has been specified

Cause: The APP_KEY is missing in .env.

Solution: Run php artisan key:generate to generate a new key.

Class 'App\Http\Controllers\...' not found

Cause: Autoloader doesn't know about your new class.

Solution: Run composer dump-autoload to regenerate the autoloader.

Page shows old content after changes

Cause: Laravel is caching views or configuration.

Solution: Clear all caches:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

500 Server Error after deployment

Cause: Usually a configuration issue or missing dependencies.

Solution: Check that:

  • .env file exists and has correct values
  • APP_KEY is set (run php artisan key:generate)
  • All dependencies are installed (composer install)
  • Database credentials are correct

Checking Your Database

You can access phpMyAdmin to visually manage your database. Click the MySQL button on your dashboard to open phpMyAdmin. Log in with the same credentials shown on your dashboard.

From phpMyAdmin you can:

  • View all tables created by migrations
  • Browse and edit data directly
  • Run custom SQL queries
  • Export/import database data

Deployment Workflow

Every time you push code to Git, your application is automatically deployed:

Code Change git push Auto Deploy Live!

Your deployed application URL follows this format: 

https://<your-subdomain>-<repo-name>.<session-domain>

Example: https://student01-module-a.demo.nstrim.app

For more information, visit the official Laravel Documentation.