Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Create the project with the one-line installer, start it, create the database tables, and know what the installer changes outside the project.

Canonical Install

Create the project and get to a trustworthy first boot

Use the installer, review the shared env baseline, boot the runtime with the Semitexa CLI, and verify the project shape before you start authoring modules.

Step 1

Run the installer

The supported install path is the one-line installer. It needs Docker with Compose v2 and no host PHP or Composer; the last argument names the project directory.

curl -fsSL https://semitexa.com/install.sh | bash -s my-project

curl -fsSL https://semitexa.com/install.sh | bash -s my-project

Step 2

Review the env boundary

Semitexa now writes `.env.default` as the committed baseline. Edit `.env` only when this machine needs overrides such as a different port.

cd my-project

cd my-project

$EDITOR .env

$EDITOR .env

Step 3

Boot and verify

Use the operator shell to start, check, and inspect the runtime instead of guessing from container state alone. After boot, open the local app in the browser and confirm you have a real page, not just a running container.

bin/semitexa server:start

bin/semitexa server:start

bin/semitexa orm:sync

bin/semitexa orm:sync

bin/semitexa self-test

bin/semitexa self-test

bin/semitexa routes:list --json

bin/semitexa routes:list --json

Default Runtime

Semitexa uses Docker as the supported local runtime boundary.
The default app URL is http://localhost:9502 unless `SWOOLE_PORT` is overridden in `.env`.
Semitexa Demo is not part of a new project. To explore these pages locally, run `bin/semitexa demo:install`, then `bin/semitexa server:restart`, and open http://localhost:9502/demo/get-started/installation. The demo home page is its `/` route, which the starter Hello module in `src/modules/Hello` takes precedence over until you remove that module.
You do not need host PHP or Composer for the normal local flow.

install.sh orm:sync bin/semitexa .env.default .env self-test routes:list

Verified against Semitexa Ultimate 2026.10.03.1952

Installation

Installation in Semitexa should end with a running runtime and a trustworthy operator shell, not with half-finished setup notes.

Prerequisites

Docker with Compose v2, and a user that can run docker without sudo (on Linux: the docker group).
No PHP and no Composer on the host. PHP 8.4 + Swoole 6 and Composer run inside the containers.

Canonical flow

Run from the parent directory of where the project should live:

curl -fsSL https://semitexa.com/install.sh | bash -s my-project
cd my-project
bin/semitexa server:start
bin/semitexa orm:sync

The installer creates my-project/ with the Semitexa scaffold and picks the app port.
server:start builds the image and starts the stack. The first run takes about a minute because Composer installs the dependencies in the setup container. When the app is up it prints its URL.
Open that URL. The default is http://localhost:9502; if 9502 was busy at install time, the installer chose a free port in 9501–9599 and wrote it to .env as SWOOLE_PORT.
orm:sync creates the database tables. The installed stack runs MySQL, Redis and NATS next to the app.

.env.default is the committed baseline. Create or edit .env only for overrides on this machine, and do not commit it.

What the installer changes outside the project

Port registry. The app is registered in ~/.semitexa/router/registry/apps/<uuid>.env, so Semitexa projects on the same machine never claim the same port. bin/semitexa local-app:list shows the entries; local-app:remove deletes one.
Local domain (optional). A <name>.test domain is opt-in: the installer asks (default No), and a non-interactive or --start run never sets one up unless you pass --local-domain. Accepting it needs sudo, changes system DNS (systemd-resolved / /etc/resolv.conf) or /etc/hosts, and starts shared router containers that bind host port 80. See Local Domain to add one later.

Verify the install

bin/semitexa self-test
bin/semitexa routes:list --json

self-test checks that Docker and Compose are installed, that the project files exist (docker-compose.yml, Dockerfile, server.php, .env.default, composer.json, vendor/bin/semitexa), and which CPU architecture you are on (AMD64 and ARM64 are supported). It also says whether the app container is running. It does not send a request to the app.
routes:list shows the discovered routes; the starter Hello module answers /.
Load the printed URL in a browser.
bin/semitexa logs:app shows the application log when something fails.

When a new release comes out, Upgrading moves the project to it with bin/semitexa update.

Why this matters

If the first boot path is ambiguous, every later problem becomes harder to diagnose. Semitexa should feel operationally legible from the first hour.

Right After Install

Do these checks before you touch business code

A clean first boot should be operationally legible. Use the CLI to confirm health, discovery, and current bindings before you start extending the project.

Run `bin/semitexa self-test` when startup feels suspicious: it checks Docker, Compose and the project files.

Use `bin/semitexa logs:app` as the first log command when the runtime did not boot cleanly.

Inspect `bin/semitexa ai:ask project --json` and `bin/semitexa contracts:list --json` early so you know what the project discovered.

If ORM-backed modules are active, treat `bin/semitexa orm:sync --dry-run` as part of the normal first setup path.

Boot Verification

What a clean first boot should prove

After `bin/semitexa server:start`, you should be able to verify the runtime from both the browser and the operator shell without guessing what happened.

Open `http://localhost:9502` and confirm the app responds with the starter page instead of a Docker, proxy, or browser error.

If you added Semitexa Demo with `bin/semitexa demo:install`, open `http://localhost:9502/demo/get-started/installation` and confirm a demo page renders before you explore deeper pages.

Run `bin/semitexa self-test` and expect it to pass: it checks Docker, Compose and the project files.

Run `bin/semitexa routes:list --json` so route discovery is visible instead of assumed.

Use `bin/semitexa ai:ask project --json` when you need to inspect what the scaffold and installed modules actually registered.