Installation & Setup

Getting started with Rhapsody is designed to be a quick and straightforward process. Follow these steps to get your local development environment up and running.

1. Server Requirements

Rhapsody is built with modern PHP. Please ensure your environment meets the following requirements:

• PHP 8.4.1 or higher
• Composer installed
• A local server environment like MAMP, WAMP, or Laravel Herd
• mod_rewrite must be enabled on Apache servers
• PHP's GD extension should be enabled if you plan on using the image resizing/caching helper
• A MySQL-compatible database

2. Installation via Composer

Rhapsody is available as a Composer package. To create a new project, run:

composer create-project arout/rhapsody-app your-site-name

This command downloads the framework, installs all PHP dependencies, and sets up the basic structure.

Navigate into your new project directory:

cd your-site-name

It's a good practice to run a Composer update to ensure all dependencies are up‑to‑date and all new features are included:

composer update

2.1. Optional React Integration

If you plan to use React for SPA's or React Islands (or want the debug toolbar’s Performance and Memory Usage panels to work), you need to set up the React bridge:

php rhapsody react:install

This command installs the necessary npm dependencies and creates the basic React entry point.

After running it, install the JavaScript dependencies and start the Vite development server:

npm install
npm run dev

Note: Even if you don’t use React anywhere else, the debug toolbar’s performance tabs rely on React islands. We recommend running this step to get the full debugging experience.

3. Environment Configuration

Rhapsody uses a .env file to manage environment‑specific variables. This file is required for the application to run. It is located in your root install directory and should be created automatically during the Composer install process. If for some reason it does not exist, simply run the command below.

Copy the example file:

cp .env.example .env

Example configuration:

APP_URL="https://your-website.com"
APP_BASE_URL="/{subirectory name}" # Leave blank unless installed in a subdirectory

DB_HOST="127.0.0.1"
DB_PORT="3306"
DB_NAME="database_name"
DB_USER="username"
DB_PASS="password"
DB_DRIVER="mysql" # Supported databases: mysql, pgsql, sqlite, or sqlsrv

Without these values, the application will not be able to connect to the database or generate correct URLs.

4. Database Setup

Create a database with the name you specified in DB_NAME. If you want to receive email notifications about updates, set MAIL_ADMIN_EMAIL in the .env as well.

5. Web Server Configuration

Your web server must be configured to direct all requests to the front controller (index.php). The repository includes a .htaccess file for Apache; for other servers (Nginx, etc.) please consult your server’s documentation.

Once everything is set up, visit your site in the browser – you should see the Rhapsody welcome page.

6. Useful commands

After installation is complete, you may find it beneficial to run a few commands using the Rhapsody runner (see Rhapsody Console and console commands for a complete command list and using the CLI runner).

Some of the commands you may wish to run immediately after installation:

php rhapsody auth:install	Install authentication tables (users, password_resets, etc.). Run this if you plan on using the built-in authentication system. See authentication for more details.
php rhapsody build:proxies	Pre-generates lazy proxy classes for all container services. See lazy loading for more details.
php rhapsody app:cache-warm	Warm up the Twig template cache by compiling all templates. Recommended for live site only; keep cache disabled in dev environment.
php rhapsody route:cache	Compile all application routes into a cached file for performance. Recommended for live site only; keep cache disabled in dev environment.