First-run setup · Documentation

The first time you open LaraMonster, a short setup gets your computer ready. It takes about a minute, and you can run it again any time from SettingsRun setup again.

Setup has seven steps. Two of them can't be skipped, because no site would work without them: the web server needs its ports, and your browser needs to trust LaraMonster's HTTPS certificate. Everything else can wait or be changed later.

Step	What it does	Required
Welcome	What setup will do	—
Ports	Checks that nothing else uses the web server's ports	Yes
Projects	Picks the folder your projects live in	Yes
PHP	Installs a PHP version	No, can be skipped
HTTPS	Trusts LaraMonster's local certificate authority	Yes
Your system	Terminal commands and start at login	No
Done	Go to the dashboard or create a project	—

1. Ports

LaraMonster's web server listens on two ports: 8080 for http:// and 8443 for https://. They're above 1024 so LaraMonster never needs administrator rights, and they don't clash with nginx, Apache or Docker on 80 and 443.

If both ports are free you'll see a green check and the address your sites will use, like http://blog.localhost:8080. Click Continue.

When a port is already in use

Sometimes another program already listens on 8080 or 8443: another web server, a Docker container, Jenkins, Tomcat, a dev server you forgot, or a second copy of LaraMonster. LaraMonster can't serve sites until it has both ports, so setup shows which port is busy and, when your system tells it, which program holds it and its process ID. You then have two ways out:

Use other ports (recommended)
Click Use 8081 and 8444 (or whichever nearby ports are free). LaraMonster moves to them right away and nothing else changes; your sites then open at, for example, http://blog.localhost:8081. You can move back later in SettingsGeneral.
Or free the port
Setup shows the commands for your system (with tabs for the others) to find the program and stop it, picked for the program it found: systemctl for an nginx or Apache service on Linux, brew services on macOS, IIS or XAMPP on Windows, docker ps for a container. Stop it, then click Check again.

The full instructions for each system, with examples, are in Troubleshooting → A port is already in use.

The same check runs every time LaraMonster starts. If a program takes a port later, LaraMonster still opens, and the dashboard shows a red banner with a Fix it button that opens this step.

2. Projects folder

Pick the folder your projects live in, for example ~/Code. LaraMonster parks it: every folder inside becomes a site at folder-name.localhost. A project in ~/Code/blog opens at http://blog.localhost:8080. The folder is created if it doesn't exist yet.

Setup suggests a folder you already use (Code, Projects, Sites, dev or src in your home folder). You can park more folders, or link single projects that live elsewhere, later; see Sites & domains.

3. PHP

If PHP is already on your computer, LaraMonster finds it and you can just continue. Otherwise click Install PHP 8.x: LaraMonster downloads a ready-made build with the extensions Laravel needs (intl, mbstring, PDO for MySQL, PostgreSQL and SQLite, GD, and more). Nothing is installed system-wide.

You can skip this step and add PHP later from the PHP page; until then, sites are served as plain files.

4. Trust local HTTPS

LaraMonster signs a certificate for every site with its own certificate authority (CA), created on your computer the first time it starts and never shared. Trusting that CA once gives every https:// site a valid padlock, so features that only work on secure pages behave like production: secure cookies, OAuth and payment callbacks, service workers, the clipboard API and webhooks.

This step is required. Click Trust the certificate; your system asks for your password once.

System	What gets trusted
macOS	Your keychain (Safari, Chrome, Edge, curl, PHP). Firefox too, if it's installed.
Windows	The Windows certificate store (Edge, Chrome, curl, PHP). Firefox reads it as well.
Linux	The system store (curl, PHP) and the browser stores Chrome, Chromium and Firefox use. These need `certutil`.

The step shows two lines, System and Browsers, and Continue unlocks once both are trusted. On Linux, if browsers show Needs certutil, click Install certutil and then Trust in browsers.

The password prompt didn't appear or failed? Open Trust it by hand instead in the same step: it shows the exact commands for your system with the certificate's path filled in, and a Check again button. The same commands are in HTTPS → Trust it by hand.

Restart your browser once afterwards so it picks up the new certificate authority.

5. Your system

Option	What it does
Terminal commands	Adds `php`, `composer` and `laramonster` to every new terminal. `php` follows each project's PHP version: in `~/Code/legacy` pinned to PHP 8.1, `php -v` says 8.1. Open a new terminal afterwards.
Start at login	Your sites and databases are up as soon as you log in. On macOS this is a launch agent, on Linux a systemd user service, on Windows a logon task.

6. Done

Drop a project into your projects folder and it's live right away, or click Create a project to let LaraMonster make a new Laravel app for you; see Your first project.

Setting up from the terminal

Everything setup does is also a command, handy on a server or in a script:

$ laramonster setup               # shims on PATH, start at login, start the engine
$ laramonster port 8081           # only if 8080 is taken (--https for 8443)
$ laramonster park ~/Code         # ~/Code/blog -> http://blog.localhost:8080
$ laramonster php:install 8.4     # optional: system PHP is used if present
$ laramonster trust               # trust the local CA (asks for your password)

laramonster setup --no-autostart skips start at login, and --no-path leaves your shell profile alone.