Skip to main content
This guide provides detailed instructions for installing and configuring the ServITech Backend API in various environments.

​
System Requirements

Before starting, ensure your system meets these requirements:

PHP

Version 8.2 or higher

Composer

Latest stable version

Node.js

Version 16.x or higher

Database

MySQL 5.7+ or SQLite 3

​
Installation Methods

1

Install PHP and Composer

Use the official PHP installer for your operating system:
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
Important: Restart your terminal after installation to ensure PHP and Composer are added to your PATH.
Verify the installation:
php --version
composer --version
2

Clone and setup project

Clone the repository and install dependencies:
git clone https://github.com/MOSHE9647/ServITech-Backend.git
cd ServITech-Backend
composer install
npm install
3

Configure environment

Create and configure your .env file:
cp .env.example .env
Generate required keys:
php artisan key:generate
php artisan jwt:secret
4

Setup database

Run migrations to create database tables:
php artisan migrate
5

Start development server

Launch all services:
composer run dev

​
Method 2: Manual Installation

For more control over the installation process:
1

Install PHP manually

Download and install PHP 8.2+ from php.netEnsure these extensions are enabled:
  • php-mbstring
  • php-xml
  • php-pdo
  • php-curl
  • php-zip
  • php-tokenizer
2

Install Composer

Download Composer from getcomposer.org
# Verify installation
composer --version
3

Install Node.js

Download Node.js from nodejs.org
# Verify installation
node --version
npm --version
4

Setup database

Choose your database:For SQLite (Recommended for development):
# No additional setup needed
# SQLite database will be created automatically
For MySQL:
# Install MySQL Server
# Create a database:
mysql -u root -p
CREATE DATABASE servitechdb;
5

Clone and configure

git clone https://github.com/MOSHE9647/ServITech-Backend.git
cd ServITech-Backend
cp .env.example .env
6

Install dependencies

composer install
npm install
7

Generate keys and migrate

php artisan key:generate
php artisan jwt:secret
php artisan migrate

​
Environment Configuration

​
Basic Configuration

Your .env file contains essential configuration. Here are the key sections:

​
Application Settings

APP_NAME=ServITech
APP_VERSION=1.0.0
APP_ENV=local
APP_KEY=         # Generated by php artisan key:generate
APP_DEBUG=true
APP_URL=http://localhost:8000

APP_LOCALE=es
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=es_ES
  • APP_ENV: Set to local for development, production for production
  • APP_DEBUG: Set to false in production to hide error details
  • APP_LOCALE: Default language (es=Spanish, en=English)

​
Database Configuration

DB_CONNECTION=sqlite
# No additional configuration needed
Security: Never commit your .env file to version control. It contains sensitive credentials.

​
API Documentation

# Scramble API Documentation Route
SCRAMBLE_API_ROUTE=/docs/api
The API documentation will be available at http://localhost:8000/docs/api

​
Advanced Configuration

​
Session and Cache

SESSION_DRIVER=database
SESSION_LIFETIME=120

CACHE_STORE=database

​
Queue Configuration

QUEUE_CONNECTION=database
The composer run dev command automatically starts a queue worker for background jobs.

​
Mail Configuration

MAIL_MAILER=log          # Use 'smtp' for production
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

​
Database Setup

​
Using SQLite (Development)

SQLite requires no additional setup: 
# The database file is created automatically
php artisan migrate
The SQLite database file will be created at database/database.sqlite.

​
Using MySQL (Production)

1

Create database

mysql -u root -p
CREATE DATABASE servitechdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit;
2

Update .env file

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=servitechdb
DB_USERNAME=root
DB_PASSWORD=your_password
3

Run migrations

php artisan migrate

​
Running the Application

​
Development Mode

The recommended way to run the application in development: 
composer run dev
This starts three concurrent processes:
  • PHP server on port 8000
  • Queue worker for background jobs
  • Vite dev server for frontend assets
You can customize the number of PHP workers by setting PHP_CLI_SERVER_WORKERS in your .env file (default: 4).

​
Individual Services

You can also run services individually: 
php artisan serve

​
Production Mode

For production deployment: 
# Build frontend assets
npm run build

# Optimize Laravel
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Start queue worker as daemon
php artisan queue:work --daemon
Production Checklist:
  • Set APP_ENV=production
  • Set APP_DEBUG=false
  • Use a proper web server (Nginx/Apache)
  • Configure SSL/TLS certificates
  • Set up proper queue workers with supervisord
  • Enable opcode caching (OPcache)

​
Testing the Installation

​
Run Tests

The project includes functional tests: 
# Run all tests
php artisan test

# Run specific test
php artisan test --filter TestName

​
API Verification

Test key endpoints: 
curl http://localhost:8000

​
Troubleshooting

​
Common Issues

Change the port when starting the server:
php artisan serve --port=8080
Update APP_URL in your .env:
APP_URL=http://localhost:8080
Fix file permissions:
chmod -R 775 storage
chmod -R 775 bootstrap/cache
On Linux/Mac, you may need to change ownership:
sudo chown -R $USER:www-data storage bootstrap/cache
For SQLite:
# Ensure the database directory exists
mkdir -p database
touch database/database.sqlite
php artisan migrate
For MySQL:
# Test MySQL connection
mysql -u root -p -e "SHOW DATABASES;"

# Verify credentials in .env match your MySQL setup
# Try connecting with the credentials manually first
Clear Composer cache and try again:
composer clear-cache
composer install --no-cache
If you encounter memory limit errors:
php -d memory_limit=-1 /path/to/composer install
Generate the JWT secret:
php artisan jwt:secret
This adds the secret to your .env file. If the command doesn’t exist:
composer require tymon/jwt-auth
php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"
php artisan jwt:secret
Try clearing the NPM cache:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

​
Getting Help

If you continue to experience issues:

Check Logs

View Laravel logs at storage/logs/laravel.log

GitHub Issues

Report bugs on the GitHub repository

Laravel Docs

Consult Laravel documentation

Enable Debug Mode

Set APP_DEBUG=true in .env for detailed errors

​
Next Steps

Now that you have the API installed:

API Documentation

Explore all available endpoints

Authentication

Learn about JWT authentication

Configuration

Advanced configuration options

Deployment

Deploy to production

Build docs developers (and LLMs) love

Get started for freeTalk to us