Development Setup

Version: 1.0.0

This guide explains how to set up the notifito development environment locally.

Prerequisites

Required Software

Verify Installation

# Check Docker
docker --version
# Docker version 29.x.x

# Check Docker Compose
docker compose version
# Docker Compose version v5.x.x

# Check Node.js
node --version
# v22.x.x

# Check Git
git --version
# git version 2.x.x

Quick Start

Clone Repository

# Clone the repository
git clone https://github.com/turkerince/notifito.git
cd notifito

Start Services

# Build and start all services
docker compose up -d

# Verify all services are running
docker compose ps

Expected output:

NAME                    IMAGE                COMMAND                  SERVICE             STATUS
notifito-caddy-1        caddy:2-alpine       "caddy run --config …"   caddy               running
notifito-core-1         notifito-tools       "php artisan serve …"    core                running
notifito-dashboard-1    notifito-tools       "php artisan serve …"    dashboard           running
notifito-dispatch-1     notifito-tools       "php artisan serve …"    dispatch            running
notifito-edge-1         notifito-tools       "php artisan serve …"    edge                running
notifito-postgres-1     postgres:18-alpine   "docker-entrypoint.s…"   postgres            running
notifito-redis-1        redis:8-alpine       "docker-entrypoint.s…"   redis               running

Run Migrations

# Run core migrations
./bin/artisan core migrate

# Run dispatch migrations
./bin/artisan dispatch migrate

Seed Test Data

# Seed demo tenants
./bin/artisan core db:seed --class=SeedTenantsSeeder

This creates three demo tenants: - Sneaker Store — Sneakers with size attribute - Grand Hotel — Hotel rooms with date range and guests - City Clinic — Appointments with date and practitioner

Verify Installation

# Run doctor check
./bin/doctor

Expected output:

php >= 8.4              OK
ext-pdo_pgsql           OK
ext-redis               OK
ext-intl                OK
ext-bcmath              OK
composer                OK
node 22                 OK
db notifito_core        OK
db core_test            OK
db dispatch             OK
db dispatch_test        OK
redis                   OK

Development Scripts

bin/dev

Run any command inside the tools container:

# Run composer install
./bin/dev composer install --working-dir=apps/core

# Run artisan commands
./bin/dev php apps/core/artisan migrate

# Run any PHP command
./bin/dev php -v

bin/test

Run Pest tests for a package or app:

# Test contracts package
./bin/test packages/contracts

# Test core app
./bin/test apps/core

# Test specific file
./bin/test apps/core tests/Feature/Tenancy/ApiKeyTest.php

# Test with coverage
./bin/test apps/core --coverage

bin/artisan

Run artisan commands for a specific app:

# Run migrations
./bin/artisan core migrate

# Run tinker
./bin/artisan core tinker

# Clear cache
./bin/artisan core cache:clear

# Generate key
./bin/artisan core key:generate

bin/doctor

Verify the development environment:

./bin/doctor

Service URLs

Access Points

Edge API:

# Health check
curl http://127.0.0.1:8002/health

# Widget schema
curl "http://127.0.0.1:8002/v1/widget/schema?key=pk_live_ADbaCjvo5TT1x8104zHXKSHr&item_type=sneaker"

Dashboard: - URL: http://app.localhost - Email: owner@sneaker-store.test - Password: password

PostgreSQL:

# Connect to core database
psql -h localhost -p 55432 -U notifito -d notifito_core

# Password: notifito

Redis:

# Connect to Redis
redis-cli -h localhost -p 56379

# Test connection
redis-cli -h localhost -p 56379 ping

Demo Credentials

Sneaker Store

Grand Hotel

City Clinic

Common Tasks

Running Migrations

# Run all migrations
./bin/artisan core migrate
./bin/artisan dispatch migrate

# Rollback migrations
./bin/artisan core migrate:rollback

# Fresh migration (drop all tables)
./bin/artisan core migrate:fresh

# Fresh migration with seeding
./bin/artisan core migrate:fresh --seed

Clearing Cache

# Clear application cache
./bin/artisan core cache:clear

# Clear config cache
./bin/artisan core config:clear

# Clear route cache
./bin/artisan core route:clear

# Clear view cache
./bin/artisan core view:clear

# Clear all caches
./bin/artisan core optimize:clear

Queue Management

# Check queue status
./bin/artisan core queue:status

# Restart queue workers
./bin/artisan core queue:restart

# Clear failed jobs
./bin/artisan core queue:flush

Horizon Management

# Check Horizon status
./bin/artisan core horizon:status

# Pause Horizon
./bin/artisan core horizon:pause

# Continue Horizon
./bin/artisan core horizon:continue

# Terminate Horizon
./bin/artisan core horizon:terminate

IDE Setup

PHPStorm

1. Open project: Open the notifito directory
2. Configure PHP interpreter: Use Docker Compose
3. Settings → PHP → CLI Interpreter
4. Add → From Docker → Docker Compose
5. Service: tools
6. Configure PHPUnit:
7. Settings → PHP → PHPUnit
8. Test runner: PHPUnit
9. Default configuration file: apps/core/phpunit.xml
10. Configure Laravel plugin:
11. Install Laravel plugin
12. Enable Laravel support

VS Code

1. Install extensions:
2. PHP Intelephense
3. PHP Debug
4. Laravel Blade Snippets
5. Docker
6. Configure settings: json { "php.validate.executablePath": "/usr/local/bin/php", "php.suggestFromComposer": true }
7. Configure debugging:
8. Install Xdebug in container
9. Configure launch.json for remote debugging

Debugging

Xdebug Setup

Add to docker/php/Dockerfile:

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug

# Configure Xdebug
RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_port=9003" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Rebuild the image:

docker compose build tools
docker compose up -d

Log Files

# View core logs
docker compose logs -f core

# View edge logs
docker compose logs -f edge

# View dispatch logs
docker compose logs -f dispatch

# View dashboard logs
docker compose logs -f dashboard

# View all logs
docker compose logs -f

Database Debugging

# Connect to core database
psql -h localhost -p 55432 -U notifito -d notifito_core

# List tables
\dt

# Describe table
\d tenants

# Run query
SELECT * FROM tenants;

# Exit
\q

Widget Development

Build Widget

# Navigate to widget directory
cd widget

# Install dependencies
npm install

# Build for production
npm run build

# Watch for changes
npm run dev

Run Widget Tests

# Run unit tests
npm test

# Run browser tests
npm run test:browser

Widget Structure

widget/
├── src/
│   ├── index.js        # Main entry point
│   ├── api.js          # API client
│   ├── dom.js          # DOM manipulation
│   ├── form.js         # Form rendering
│   └── styles.js       # CSS styles
├── tests/
│   ├── browser/        # Playwright tests
│   └── form.test.mjs   # Unit tests
├── build.mjs           # Build script
└── package.json

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :8002

# Kill process
kill -9 <PID>

# Or use different port
# Edit docker-compose.yml to change port mapping

Docker Issues

# Check Docker status
docker info

# Check Docker Compose status
docker compose ps

# Restart Docker
sudo systemctl restart docker

# Clean up Docker
docker system prune -a

Database Connection Issues

# Check PostgreSQL status
docker compose exec postgres pg_isready

# Check database exists
docker compose exec postgres psql -U notifito -l

# Restart PostgreSQL
docker compose restart postgres

Redis Connection Issues

# Check Redis status
docker compose exec redis redis-cli ping

# Restart Redis
docker compose restart redis

Permission Issues

# Fix file permissions
sudo chown -R $USER:$USER .

# Fix storage permissions
chmod -R 777 apps/core/storage
chmod -R 777 apps/edge/storage
chmod -R 777 apps/dispatch/storage
chmod -R 777 apps/dashboard/storage

Related Documentation

• Testing Guide — Running and writing tests
• Contributing — Code style and workflow
• Configuration Reference — Environment variables