Getting Started

Follow these steps to get the Web App Template running locally. This guide covers installation, environment configuration, authentication, and the first-run flow.

Installation

Use the repository as a GitHub template or clone it, then run the setup script:

git clone https://github.com/feraandrei1/template-laravel-app.git
cd template-laravel-app

composer setup installs PHP dependencies, copies .env.example to .env if missing, generates the app key, runs migrations with --force, then runs npm install and npm run build. Configure the database in .env before running it, since migrations run as part of the script.

composer dev starts four processes together with concurrently: the PHP server, a queue listener, php artisan pail, and the Vite dev server. The panel is available at http://localhost:8000/app.

Configuration

Set the database credentials (DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD) in .env. The example file uses MySQL with the database name template_laravel_app.
Configure mail (MAIL_*) and CONTACT_TO_ADDRESS.
Optionally add Stripe keys, AWS S3 credentials, a Sentry DSN, and Vonage credentials.
Fill the DEPLOY_* variables if you deploy with Envoy.
For production set APP_ENV=production and APP_DEBUG=false.

Environment Variables

Name
APP_NAME
Type
string
Description
Application name. Default: Laravel
Name
APP_ENV
Type
string
Description
Application environment. Default: local
Name
APP_KEY
Type
string
Description
Encryption key, generated by php artisan key:generate.
Name
APP_DEBUG
Type
boolean
Description
Debug mode. Disable in production. Default: true
Name
APP_URL
Type
string
Description
Base URL. Default: http://localhost. Also decides whether the demo reset is allowed.
Name
DB_CONNECTION
Type
string
Description
Database driver. Default: mysql
Name
DB_HOST / DB_PORT
Type
string
Description
Database host and port. Defaults: 127.0.0.1 and 3306
Name
DB_DATABASE
Type
string
Description
Database name. Default: template_laravel_app
Name
DB_USERNAME / DB_PASSWORD
Type
string
Description
Database credentials. Defaults: root and empty.
Name
SESSION_DRIVER / QUEUE_CONNECTION / CACHE_STORE
Type
string
Description
All default to database, so the sessions, jobs, and cache tables are created by migrations.
Name
MAIL_MAILER
Type
string
Description
Mail driver. Default: smtp on 127.0.0.1:1025.
Name
MAIL_FROM_ADDRESS / MAIL_FROM_NAME
Type
string
Description
Default sender. Defaults: hello@example.com and ${APP_NAME}.
Name
CONTACT_TO_ADDRESS
Type
string
Description
Contact recipient, read as mail.contact.address. Default: contact@example.com
Name
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
Type
string
Description
S3 credentials. Empty by default.
Name
AWS_DEFAULT_REGION / AWS_BUCKET / AWS_ROOT
Type
string
Description
S3 region, bucket, and root folder. Defaults: us-east-1, empty, app-name.
Name
STRIPE_KEY / STRIPE_SECRET / STRIPE_WEBHOOK_SECRET
Type
string
Description
Stripe credentials read by Cashier. The example file contains placeholders.
Name
SENTRY_LARAVEL_DSN
Type
string
Description
Sentry DSN for the backend. Optional.
Name
SENTRY_SEND_DEFAULT_PII / SENTRY_TRACES_SAMPLE_RATE
Type
string
Description
Sentry options. Empty by default.
Name
VITE_SENTRY_DSN_PUBLIC
Type
string
Description
Sentry DSN for the browser bundle. Optional.
Name
VONAGE_KEY / VONAGE_SECRET
Type
string
Description
Vonage SMS credentials read by config/services.php. Not listed in .env.example.
Name
DEPLOY_USER / DEPLOY_HOST / DEPLOY_REPOSITORY / DEPLOY_APP_DIR / DEPLOY_BRANCH
Type
string
Description
Envoy deployment settings. The first four are required; the branch defaults to main.
Name
DEMO_MODE
Type
boolean
Description
Turns on the live demo mode. Default: false. Present on the feature/demo-mode branch.
Name
DEMO_ALLOW_RESET
Type
boolean
Description
Allows demo:seed and demo:reset on hosts that do not start with demo-. Default: false.
Name
DEMO_PRODUCT_URL
Type
string
Description
Target of the "Get it" link in the demo banner. Falls back to the product page configured in config/demo.php.

Authentication & Roles

The Filament panel at /app provides login, registration, and a profile page. User::canAccessPanel() returns true for every authenticated user, so access to data is controlled by permissions.

The only seeded role is Super Admin. A Gate::before hook in AuthServiceProvider grants it every ability.
PermissionSeeder creates view, create, update, and delete permissions for each model in app/Models, and RoleHasPermissionSeeder gives all of them to Super Admin.
Policies extend AbstractPolicy, which maps each ability to the matching permission. Users without User.update can still edit their own record, and nobody can delete a Super Admin.
The Health Check Results and View Log pages are visible to Super Admin only.

php artisan db:seed creates a Super Admin account with email test@example.com and password password. Change or remove it before any real deployment.

Basic Usage Flow

Run php artisan db:seed and sign in at /app/login with the seeded Super Admin.
Open Users to create accounts and assign roles.
Open Roles to review permissions.
Review the Activity Log to see recorded changes.
Check Health Check Results and View Log in Settings.
After adding a new model, create its permissions with php artisan app:add-permissions-to-new-modules (edit the model list in the command first) or re-run the permission seeder.