Installation

Requirements

Requirement	Why
PHP 8.4	Locally and on the server's command line
Laravel 13	A fresh app from laravel new
Node 24	For the site's asset build, locally and in GitHub Actions
A database supported by Laravel	SQLite locally is fine; MySQL is common on shared hosting
The intl PHP extension	For the names of the languages
The GD or Imagick PHP extension, with WebP	For the image sizes of the media library

Install

Start from a fresh Laravel app:

laravel new client-site && cd client-site
composer require melasistema/mela-cms
php artisan mela:install

The command asks for the site languages and for the super-admin's email, name and password. Then open /admin and log in with that account.

MelaCMS is on Packagist, so neither your machine nor the site's workflows need a token or a Composer repository entry.

A site made while the package was private

Those sites still work as they are. To clean them up, accept the new workflow and Dependabot templates when mela:update asks about them, remove the repository entry with composer config --unset repositories.mela-cms, and only then delete the COMPOSER_AUTH and COMPOSER_TOKEN secrets on the site's GitHub repository: the old Dependabot template still reads COMPOSER_TOKEN.

"Invalid URI: Host is malformed"

Some versions of the Laravel installer write the port twice into APP_URL in .env (http://localhost:8000:8000). Fix it by hand and run the command again.

Pin the server's PHP version

Before the first push, tell Composer which PHP version the server runs:

composer config platform.php 8.4.24   # the version `php -v` prints on the server
composer update --lock

Composer then resolves every update for that version, on any machine. Dependabot needs this: without the pin it resolves for PHP 8.4.0, which some packages no longer accept, and its update fails with dependency_file_not_resolvable.

What mela:install does

1. Publishes config/mela-cms.php and writes the site languages into it.
2. Publishes the roles and permissions migration and runs the migrations.
3. Adds implements FilamentUser and the HasCmsAccess trait to app/Models/User.php. Without them nobody can log in to the admin.
4. Creates the roles and the super-admin account.
5. Publishes Filament's assets and adds @php artisan filament:upgrade to the post-autoload-dump scripts in composer.json, so the assets follow every Composer install.
6. Links public/storage to storage/app/public, where the media library keeps its files.
7. Removes Laravel's welcome route for / from routes/web.php, so / shows the home page chosen in the panel. A / route you wrote yourself is kept, and the command says so.
8. Copies the workflow templates into .github/ and records their version in mela-cms.json.
9. Adds the MelaCMS section to AGENTS.md and CLAUDE.md.

The command is safe to run again. Each step skips what is already in place, and a workflow file you changed is kept unless you confirm replacing it.

Without interaction

In a script or in CI, pass the values as options. --email and --password are then required:

php artisan mela:install --no-interaction \
    --email=admin@example.com --password=change-me-now --locales=en,it

All the options are listed under Commands. If the email belongs to an existing user, that user keeps their password and gains the super-admin role.

Next steps

• Create the pages of the site and choose the home page on the Settings page. See Pages.
• Put @seo and @hreflang in the <head> of your layout. See SEO.
• Create the GitHub repository and set up the deploy. See Releasing and deploying.
• Open the project with your coding agent. See Working with coding agents.