Getting Started

Installation

Get a fresh Lunaris application running locally in a few commands — with Composer, a required .env file and your application encryption key.

Requirements

PHP 8.3+ — the codebase relies on enums, match expressions and anonymous classes.
Composer for autoloading and dependencies.
Apache with mod_rewrite, or any server that can rewrite everything to public/index.php.
Optional: Docker or Podman for the containerized environment.

Install with Composer

Clone the repository and install the dependencies:

# 1. Clone the repository
git clone <your-repo-url> lunaris
cd lunaris

# 2. Install dependencies
composer install

# 3. Create your .env file (based on the example below)
#    .env is required — the application loads it at boot

# 4. Generate the application encryption key
php lunar key:generate

# 5. Point Apache (or your web server) at the public/ directory
#    or run the Docker environment:
docker compose -f docker/docker-compose.yml up --build
# Then open http://localhost:8080

Create your `.env`

The .env file is loaded at boot with vlucas/phpdotenv (immutable mode). It is required — the application will not boot without it. Keys are read through the env() helper.

# Defuse ASCII-safe key — generate with: php lunar key:generate
APP_KEY=def0000042cec0...
APP_NAME="Lunaris"
APP_URL=http://lunaris

Never commit .env

.env holds your APP_KEY. The root .htaccess already denies direct web access to it and to *.log files — keep it out of version control too.

Generate the application key

The key:generate command creates a new Defuse ASCII-safe key and writes (or replaces) APP_KEY= in your .env:

php lunar key:generate

The key is consumed by System\Security\Crypt for AES-256-GCM encryption. A missing or empty APP_KEY throws an InvalidArgumentException the first time you encrypt something.

Web server setup

The document root must point at the public/ directory — never at the project root. public/index.php is the front controller, and public/.htaccess rewrites every request that is not a real file to it.

public/
├── index.php      # front controller (entry point)
├── .htaccess      # rewrite non-files to index.php
└── logo.png

Using Docker / Podman

The docker/ directory provides a complete environment:

PHP 8.3 + Apache container on port 8080, with the project bind-mounted into /var/www/html.
MariaDB 10.11 container (mysql) on port 3306, database lunarisdb, root password root, with a named volume for persistence.

docker compose -f docker/docker-compose.yml up --build

# Podman users:
podman-compose -f docker/podman-compose.yml up --build

Note

The podman-compose.yml currently hard-codes the bind-mount path, so adjust it for your machine. There is also no .dockerignore yet — composer install is not run during the image build, so the container only works because compose bind-mounts the project over the copied tree.

Verify the install

With the server running, open http://localhost:8080. The GET / route points at the sample HelloWorld action, which renders the welcome view:

<?php

use App\Actions\HelloWorld;
use System\Routing\Route;

Route::get("/", HelloWorld::class)->name("home");

If you see the welcome page, your installation is working.

Part of the Lunaris documentation · Source on Codeberg · MIT License