OTC

Appearance

API Setup ​

This guide will walk you through setting up the EasyOTC API project from scratch.

Where this lives ​

  • Repo: https://github.com/Eliinova/the-one-otc-api
  • Local dev URL: http://localhost:8000
  • Staging API: https://stage-api.easyotc.com
  • Admin (staging): https://stage-api.easyotc.com/admin
  • Horizon (staging): https://stage-api.easyotc.com/horizon
  • Storefront (staging): https://stage.easyotc.com
  • Run locally: php artisan serve (from the the-one-otc-api repo root)

See /access for the full URL and credentials list across environments.

Prerequisites ​

Before you begin, ensure you have the following installed on your system:

  • PHP 8.4+
  • Composer 2.8+
  • Node.js 22+
  • Bun 1.2+
  • PostgreSQL 13+
  • Redis 8.0+
  • Meilisearch 1.15+

Quick Start ​

1. Clone the Repository ​

bash
git clone https://github.com/Eliinova/the-one-otc-api
cd the-one-otc-api

2. Install PHP Dependencies ​

bash
composer install

3. Environment Configuration ​

bash
# Copy the environment file
cp .env.example .env

# Generate application key
php artisan key:generate

4. Configure Database and Services ​

Edit the .env file with your database credentials and service configurations:

env
# Database Configuration
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=otc_api
DB_USERNAME=your_username
DB_PASSWORD=your_password

# MeiliSearch Configuration
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=your-search-key

5. Install and Start MeiliSearch ​

bash
# Download and install MeiliSearch binary
curl -L https://install.meilisearch.com | sh

# Start MeiliSearch (run this in a separate terminal)
./meilisearch

MeiliSearch will be available at http://localhost:7700

⚠️ IMPORTANT: MeiliSearch must be running before you run database seeding. If MeiliSearch is not running, the seeding process will fail.

6. Run Database Migrations ​

bash
# Create database tables
php artisan migrate

# Seed with initial data
php artisan db:seed

7. Install Frontend Dependencies (Optional) ​

If you plan to work with the frontend assets:

bash
npm install
# or
bun install

8. Start the Development Server ​

bash
php artisan serve

Your API will be available at http://localhost:8000 locally. For deployed environments, use:

EnvironmentURL
Localhttp://localhost:8000
Staging APIhttps://stage-api.easyotc.com
Admin (staging)https://stage-api.easyotc.com/admin
Horizon (staging)https://stage-api.easyotc.com/horizon
Storefront (staging)https://stage.easyotc.com

See /access for the complete URL list.

Development Setup ​

Database Seeding ​

The project comes with comprehensive seeders for development:

bash
# Seed all data
php artisan db:seed

# Seed specific data
php artisan db:seed --class=UserSeeder
php artisan db:seed --class=CarrierSeeder
php artisan db:seed --class=ProductSeeder

Default Users ​

After seeding, you'll have these default users (roles defined in app/Enums/RoleEnum.php):

  • OTC_ONE_ADMIN: admin@example.com / password
  • CARRIER_ADMIN: admin2@example.com / password
  • MEMBER: member@example.com / password

Testing ​

bash
# Run all tests
php artisan test

# Run specific test file
php artisan test tests/Feature/LoginControllerTest.php

Production Setup ​

Environment Variables ​

For production, ensure these environment variables are properly configured:

env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# Database
DB_CONNECTION=pgsql
DB_HOST=your-db-host
DB_PORT=5432
DB_DATABASE=your-database
DB_USERNAME=your-username
DB_PASSWORD=your-secure-password

# Mail configuration
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="${APP_NAME}"

# Search engine
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=your-search-key

Optimization ​

bash
# Cache configuration
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

Troubleshooting ​

Common Issues ​

Permission Denied Errors

bash
# Set proper permissions on storage and bootstrap/cache
chmod -R 775 storage bootstrap/cache

Composer Memory Issues

bash
# Increase memory limit
COMPOSER_MEMORY_LIMIT=-1 composer install

Database Connection Issues

  • Verify database credentials in .env
  • Ensure database server is running
  • Check if database exists: php artisan migrate:status

Port Already in Use

bash
# Use different port
php artisan serve --port=8001

MeiliSearch Issues

  • Ensure MeiliSearch is running: ./meilisearch
  • Check if port 7700 is available: lsof -i :7700
  • Verify MeiliSearch is accessible: curl http://localhost:7700/health
  • If seeding fails: Make sure MeiliSearch is running before running php artisan db:seed

Next Steps ​