MelodAI Documentation — Local Development

Requirements

PHP 8.3+ (CLI and web server must use the same version)
Composer 2.x
Node.js 20 LTS and npm
MySQL 8 or MariaDB 10.6+
FFmpeg (required for lyrics video and audio pipelines)
Optional: Redis (not required; MelodAI uses database queues by default)

On Windows, XAMPP is the most common stack. Laragon and WAMP work the same way with different folder paths.

Step 1: Enable Required PHP Extensions (php.ini)

Edit the php.ini used by both Apache and CLI. Typical paths:

Windows XAMPP: C:\xampp\php\php.ini
Windows WAMP: C:\wamp64\bin\php\php8.3.x\php.ini
macOS Homebrew: /opt/homebrew/etc/php/8.3/php.ini
Linux: /etc/php/8.3/apache2/php.ini and /etc/php/8.3/cli/php.ini

Required extensions (remove leading ; if commented):

bcmath, ctype, curl, dom, fileinfo, gd, intl, mbstring, mysql, openssl, pcntl, pdo_mysql, posix, tokenizer, xml, zip

Recommended:

exif, iconv, sodium
redis only if you switch QUEUE_CONNECTION / CACHE_STORE to Redis

Also verify these php.ini values for uploads and long jobs:

upload_max_filesize = 64M

post_max_size = 64M

max_execution_time = 300

memory_limit = 512M

Windows/XAMPP SSL fix (if OpenAI, Suno, or R2 return cURL error 60):

curl.cainfo = C:\xampp\php\extras\ssl\cacert.pem

openssl.cafile = C:\xampp\php\extras\ssl\cacert.pem

Restart Apache, then verify extensions:

php -m

php --ini

Step 2: Prepare Project and .env

Place the project in your web root, for example C:\xampp\htdocs\melodai.

cd C:\xampp\htdocs\melodai

copy .env.example .env

composer install

php artisan key:generate

Minimum local .env values:

APP_ENV=local

APP_DEBUG=true

APP_URL=http://localhost/melodai/public

SKIP_INSTALL_WIZARD=false

QUEUE_CONNECTION=database

MELODAI_QUEUE_AFTER_RESPONSE=true

REDIS_CLIENT=predis

On XAMPP, use OPENAI_SSL_VERIFY=false and CLOUDFLARE_R2_SSL_VERIFY=false only if CA bundle is missing. Prefer fixing curl.cainfo instead.

Step 3: Database Setup

Create a MySQL database (phpMyAdmin or CLI), then set:

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=melodai

DB_USERNAME=root

DB_PASSWORD=

Run migrations and seeders:

php artisan migrate

php artisan db:seed

php artisan storage:link

Step 4: Build Frontend Assets

npm install

npm run build

For active development with hot reload, use npm run dev instead of build-only.

Step 5: Run the Application

Recommended — starts web server, queue worker, and Vite together:

composer run dev

Alternative manual terminals:

php artisan serve

php artisan melodai:work --tries=1

npm run dev

Website (artisan serve): http://127.0.0.1:8000
XAMPP Apache: http://localhost/melodai/public
Login (users and admins): /login — admin accounts are redirected to /admin after sign-in

Horizon requires Linux/macOS with pcntl. On Windows/XAMPP always use php artisan melodai:work or composer run dev.

Step 6: Installation Wizard

On first visit, open /install and complete all steps (database, site URL, admin account, and integrations).

After installation, configure providers in Admin → Settings (AI, Mail, Payment, YouTube, Security).

Step 7: FFmpeg (Local)

Install FFmpeg and set paths in .env:

FFMPEG_BINARIES=C:\ffmpeg\bin\ffmpeg.exe

FFPROBE_BINARIES=C:\ffmpeg\bin\ffprobe.exe

Linux/macOS example:

FFMPEG_BINARIES=/usr/bin/ffmpeg

Troubleshooting (Local)

Vite manifest error: run npm run build or npm run dev.
Queue jobs never run: keep melodai:work or composer run dev running.
cURL error 60: set CA bundle in php.ini or temporarily OPENAI_SSL_VERIFY=false.
Permission errors: ensure storage and bootstrap/cache are writable.
Installer redirect loop: confirm DB connection works and migrations completed.