Installation¶
ZubZet projects are set up with an install script. It builds the project and bundles a Docker development stack: Apache + PHP, MariaDB, phpMyAdmin, and a mail catcher.
Requirement¶
Docker is required. Nothing else needs to be installed on your host.
Database server¶
ZubZet requires MariaDB 11.7 or newer and does not support MySQL: the bundled migrations use MariaDB-only syntax (ADD COLUMN IF NOT EXISTS, ADD INDEX IF NOT EXISTS, DROP COLUMN IF EXISTS) and the native UUID column type. The Docker stack of a new project runs mariadb:11.8, and the framework's e2e suite runs MariaDB 11.8 as a three-node Galera cluster.
No other SQL dialect is wired up: the runtime connection is mysqli, the migration tooling is hard-coded to the DBAL mysqli driver with MySQL80Platform, and the query builder uses the Cake\Database\Driver\Mysql driver.
PHP extensions¶
The Docker image provides every extension the framework needs. On your own PHP build, composer.json only requires ext-openssl, but you also need:
ext-mysqlibuilt againstmysqlnd: every query callsmysqli_stmt::get_result(), which thelibmysqlclientbuild of mysqli does not offer.ext-mbstring: the framework callsmb_*functions (e.g. inHelpers).ext-ctype,ext-filterandext-hash: required by PHPMailer, which sends the mails ofResponse::sendEmail().- Argon2id support: new password hashes use
password_hash()withPASSWORD_ARGON2ID, so PHP must be compiled with Argon2 (--with-password-argon2, or thePASSWORD_ARGON2IDconstant is undefined).
Install script¶
One command creates a project in a new folder (replace my-project):
bash <(curl -fsSL https://zubzet.com/install.sh) my-project
Without the folder argument the script asks for it. https://zubzet.com/install.sh redirects to the script inside this documentation for the latest stable release, https://zubzet.com/docs/latest/setup/install.sh. The script is versioned with the framework, so for another version fetch it from that version's docs, https://zubzet.com/docs/<version>/setup/install.sh. It is printed in full below so you can read what it does before running it, or save it as install.sh and run it with bash install.sh my-project.
The script asks which framework version to install; pass it as second argument to skip the question: latest for the newest stable release, a Composer constraint such as ^1.3, or a branch such as dev-develop. It writes the project's composer.json, runs composer require zubzet/framework in the project folder and then bin/install from the new vendor, which copies the project template (Docker stack, app/ skeleton, zubzet console entry point and the project script) around it and never overwrites an existing file. All of it runs inside the PHP image the project uses; the container exits when it is done. The script then runs ./project start in the new project, see below.
#!/usr/bin/env bash
# ----------------
# Check Bash
# ----------------
# Before anything else and in plain POSIX syntax, since `sh install.sh` would choke on the Bash-only parts below
if [ -z "${BASH_VERSION:-}" ]; then
echo "Error: This installer needs Bash, but it was started with another shell." >&2
echo "Run it with: bash install.sh" >&2
exit 1
fi
# ----------------
# Output
# ----------------
bold=""; dim=""; red=""; green=""; reset=""
# Colors only on a terminal and not when NO_COLOR is set (https://no-color.org)
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
bold=$'\033[1m';
dim=$'\033[2m';
red=$'\033[31m';
green=$'\033[32m';
reset=$'\033[0m'
fi
# Start on a clean screen so the banner is at the top
if [ -t 1 ]; then
printf '\033[H\033[2J'
fi
printf '%s' "$green"
cat <<'EOF'
_____ _ _____ _
|__ / _| |__|__ /___| |_
/ / | | | '_ \ / // _ \ __|
/ /| |_| | |_) / /| __/ |_
/____\__,_|_.__/____\___|\__|
EOF
printf '%s\n' "$reset"
echo "${green}ℹ ${bold}Welcome to ZubZet!${reset}"
echo
# ----------------
# Spinner
# ----------------
# The installation output is hidden in a log. The spinner shows its last line below itself and
# the whole log only if something fails.
# Only on a terminal, in logs and pipes the installer prints a plain line instead.
log="$(mktemp)"
spinner_pid=""
tty_state=""
# Seconds as MM:SS
clock() {
printf '%02d:%02d' "$(($1 / 60))" "$(($1 % 60))"
}
spinner_start() {
if [ ! -t 1 ]; then
echo "Installing dependencies..."
return 0
fi
cols="$(tput cols 2>/dev/null || echo 80)"
# Hide the cursor and reserve the line below the spinner for the log
printf '\033[?25l\n\033[1A'
# Keys pressed meanwhile (e.g. Enter) must not be echoed, they would move the spinner down
if [ -t 0 ]; then
tty_state="$(stty -g)"
stty -echo
fi
(
frames=('⠋' '⠙' '⠹' '⠸' '⠼' '⠴' '⠦' '⠧' '⠇' '⠏')
start=$SECONDS
i=0
while true; do
# Last line of the log, progress bars rewrite their line with \r
last="$(tail -n 1 "$log" 2>/dev/null)"
last="${last##*$'\r'}"
last="${last//[^[:print:]]/}"
last="${last#"${last%%[![:space:]]*}"}"
printf '\r\033[K%s%s%s Installing dependencies... %s[%s]%s\n\033[K %s%s%s\033[1A' \
"$green" "${frames[i]}" "$reset" "$green" "$(clock "$((SECONDS - start))")" "$reset" \
"$dim" "${last:0:$((cols - 4))}" "$reset"
i=$(( (i + 1) % ${#frames[@]} ))
sleep 0.08
done
) &
spinner_pid=$!
}
spinner_stop() {
if [ -z "$spinner_pid" ]; then
return 0
fi
kill "$spinner_pid" 2>/dev/null
wait "$spinner_pid" 2>/dev/null
spinner_pid=""
# Drop what was typed meanwhile and restore the terminal
if [ -n "$tty_state" ]; then
while read -r -t 0.01 _; do :; done
stty "$tty_state"
tty_state=""
fi
# Clear both lines and show the cursor again
printf '\r\033[K\n\033[K\033[1A\r\033[?25h'
}
# Also clean up when aborted with Ctrl+C or when a step fails
cleanup() {
spinner_stop
rm -f "$log"
}
trap cleanup EXIT
trap 'exit 130' INT TERM
# ----------------
# Check Environment
# ----------------
if ! command -v docker >/dev/null; then
echo "${red}${bold}Error:${reset} Docker is required but was not found in your PATH." >&2
echo "Install Docker: https://docs.docker.com/get-started/get-docker/" >&2
echo "Then run this installer again." >&2
exit 1
fi
# ----------------
# Project Directory
# ----------------
# Given as first argument (./install.sh my-project), otherwise asked for
if [ $# -ge 1 ]; then
directory="$1"
else
question="${bold}Where would you like to create your project?${reset}"
echo "${green}?${reset} $question ${dim}(leave empty for current directory)${reset}"
read -r -p "> " directory
# Replace the question with its answer once it is given
if [ -t 0 ] && [ -t 1 ]; then
printf '\033[2A\r\033[J'
echo "${green}✔${reset} $question"
echo "${directory:-.}"
fi
fi
directory="${directory:-.}"
# ----------------
# Framework Version
# ----------------
# Given as second argument (./install.sh my-project 1.3.0), otherwise asked for. A release number,
# any Composer constraint or branch (dev-develop), or "latest" for the newest stable release.
# The docs deploy replaces the default with the version these docs belong to, so the script of a
# release installs that release.
default_version="latest"
if [ $# -ge 2 ]; then
version="$2"
else
question="${bold}Which version would you like to install?${reset}"
echo "${green}?${reset} $question ${dim}(leave empty for $default_version, or enter a constraint like ^1.3 or dev-develop)${reset}"
read -r -p "> " version
if [ -t 0 ] && [ -t 1 ]; then
printf '\033[2A\r\033[J'
echo "${green}✔${reset} $question"
echo "${version:-$default_version}"
fi
fi
version="${version:-$default_version}"
mkdir -p "$directory"
directory="$(cd "$directory" && pwd)"
echo "${green}ℹ${reset} Creating a new project in ${green}$directory${reset} with zubzet/framework ${green}$version${reset}."
# The project belongs to the user running the installer.
# Apache refuses to run as root, so for root the project goes to uid 1000 instead, the uid of the application container.
owner="$(id -u):$(id -g)"
if [ "$(id -u)" = 0 ]; then
owner="1000:1000"
chown "$owner" "$directory"
fi
# ----------------
# Install
# ----------------
# Everything runs inside the PHP image the project uses, so the host needs nothing but Docker.
# The project's composer.json comes first, then one `composer require` builds the vendor in place
# (latest: without a constraint, so Composer picks the newest stable release and writes the ^
# constraint itself), then bin/install from that vendor adds the rest of the project template.
constraint="$version"
if [ "$version" = latest ]; then
constraint=""
fi
install_start=$SECONDS
spinner_start
if [ ! -f "$directory/composer.json" ]; then
cat > "$directory/composer.json" <<'JSON'
{
"type": "project",
"autoload": {
"psr-4": {
"App\\": "app/"
}
}
}
JSON
fi
# Written by root -> the container (uid 1000) must be able to update it
if [ "$(id -u)" = 0 ]; then
chown "$owner" "$directory/composer.json"
fi
if ! docker run --rm -u "$owner" -e HOME=/tmp -e "ZUBZET_CONSTRAINT=$constraint" -v "$directory":/app -w /app --entrypoint sh ghcr.io/zubzet/php:8.5-apache -c '
composer require --no-ansi "zubzet/framework${ZUBZET_CONSTRAINT:+:$ZUBZET_CONSTRAINT}" &&
php vendor/zubzet/framework/bin/install /app
' > "$log" 2>&1; then
spinner_stop
echo "${red}${bold}Error:${reset} The installation failed:" >&2
cat "$log" >&2
exit 1
fi
spinner_stop
echo "${green}✔${reset} Done! ZubZet installed in ${bold}$directory.${reset} ${green}[$(clock "$((SECONDS - install_start))")]${reset}"
# ----------------
# Start
# ----------------
# The installer container is gone by now, the project starts on the host through its own script
echo
echo "${green}ℹ${reset} Starting the project..."
if ! (cd "$directory" && ./project start); then
echo "${red}${bold}Error:${reset} The project was installed but could not be started. Run ${bold}./project start${reset} in ${bold}$directory${reset} again." >&2
exit 1
fi
# ----------------
# Next Steps
# ----------------
# Laid out like the output of `info:startup` in the framework
rule=" ${dim}─────────────────────────────────────────────${reset}"
# Label in the muted color, value in bold
info_row() {
printf ' %s%-8s%s %s\n' "$dim" "$1" "$reset" "$2"
}
echo
echo "$rule"
# Only when the project is not in the current directory
if [ "$directory" != "$PWD" ]; then
info_row "Enter" "${bold}cd $(printf '%q' "$directory")${reset}"
fi
info_row "Stop" "${bold}./project stop${reset}"
echo
info_row "Docs" "${green}https://zubzet.com/docs${reset}"
info_row "Issues" "${green}https://github.com/zubzet/framework/issues${reset}"
echo "$rule"
echo
Install with an agent¶
If an AI coding agent (Claude Code, Cursor, Codex, ...) does the setup or the work on an existing project, give it this one line first:
Fetch https://zubzet.com/agent.md and follow it before working on this ZubZet project. If you cannot fetch it, do nothing and tell me.
The page is a short signpost for agents. It tells them to run the install script above for a new project, where the documentation and the agent skill live inside vendor/zubzet/framework/ (docs/ and skills/zubzet/), how the project script drives the Docker stack, and that a project's own AGENTS.md wins over the skill. Two things to know before you paste it:
- Docker must be installed and the agent must be allowed to run it. The install script, the application and the tests all run in containers; an agent in a sandbox without Docker can read the sources but cannot install, start or test the project.
- The agent reads the skill. The skill is a directory in the framework package,
vendor/zubzet/framework/skills/zubzet, that holds the architecture, design and style rules for ZubZet projects. Every agent can read it right there. A tool that loads project skills from a folder of its own gets a link to that directory, which the agent offers to create; the framework itself creates no tool specific folder in a project.
The same prompt works on an existing project at any time; it is the fastest way to give a new agent session the full context.
Start the project¶
The install script starts the project itself. Later, or after a ./project stop, run inside your project folder:
./project start
Every start resets the database on purpose
./project start drops and recreates the database, so all local data is lost each time.
This single command:
- Builds the application image and starts the Docker stack (detached),
- Runs
composer installinside the application container, - Seeds the database with
db:seed, which drops and recreates the database, runs all migrations and loads the seed data (local data is lost on every start), - Prints the startup info with
info:startup.
To stop and remove the stack (and its volumes), run ./project stop. ./project shell opens a shell inside the application container. See console commands for all project commands.
Access your application¶
| Service | URL |
|---|---|
| Application | http://localhost:8080 |
| Database UI (phpMyAdmin) | http://localhost:8081 |
| Mail catcher (smtp4dev) | http://localhost:3300 |
The seed creates no user accounts. app/Database/seed/accounts/0_permissions.sql adds the roles Admin (permission *.*) and User (permission dashboard); create a user and assign it a role, see Z-Admin permissions. Adjust or remove the seed before going to production.
Project layout¶
tests/e2e/ in the framework repository is a complete reference project. The framework resolves every default path relative to the process working directory, so an entry script has to chdir() to the project root before booting (the stub index.php does chdir(realpath(__DIR__)), webroot/index.php changes to its parent folder). This matters for cron jobs and other CLI calls started from elsewhere.
index.php: entry script in the project root that boots the framework, for HTTP requests (viawebroot/index.php, which requires the first existing ofindex.php,zubzet.phpandzubzet) and for CLI use (php index.php <command>). It callschdir(realpath(__DIR__)), requiresautoload.phpfrom$COMPOSER_VENDOR_DIR(default./vendor), then runsnew z_framework()(an alias ofZubZet) and->execute(). Web and CLI share this script: forphp index.php <command>,execute()hands over to the console when no route matches.app/Controllers/: defaultz_controllersdirectory with the<Name>Controller.phpfiles. A controller in a sub-folder is found by its plain name, see controllers.app/Models/: defaultz_modelsdirectory with the<Name>Model.phpfiles. A sub-folder is addressed in lower case through dot notation,getModel("reports.GuestbookStats")loadsreports/GuestbookStatsModel.php.app/Views/: defaultz_viewsdirectory with views, mail templates and thelayout/folder. Further sub-folders are allowed and addressed in the view name (employee/index).app/Routes/: defaultroutesdirectory. Every top-level*.phpfile in it isrequire_onced when the route dispatcher is built on the first request, sub-folders are not read.app/Database/migrations/: migration files read bydb:migrateanddb:sync. A missing folder is created with mode0755.app/Database/seed/: seed files read bydb:seed. Sub-folders can be used as selectors for-iand-e. A missing folder is created with mode0755.z_config/z_settings.ini: settings file at the defaultconfig_filepath. It is read without an existence check, so a project without it does not boot.
Web root¶
Apache serves only webroot/ (DocumentRoot /var/www/html/webroot, see packaging/docker/site-000-default.conf). Everything above it is outside the web root and cannot be requested, so /app/Controllers/AdminController.php, /composer.json, /vendor/autoload.php and /z_config/z_settings.ini answer 404 and never expose source code or settings. The .htaccess in webroot/ (RewriteCond %{REQUEST_FILENAME} !-f with RewriteRule . index.php [L,QSA]) sends every request that is not an existing file to webroot/index.php and keeps the query string, so such a request reaches the framework router, which has no route for it, and the response is the framework's 404 page. Existing files in webroot/ (assets, uploads/) are served by Apache directly, and PHP files there are executed directly, bypassing the framework. Keep secrets and application code out of webroot/.
The rewrite rule is an Apache .htaccess, so it needs mod_rewrite and AllowOverride All for the document root (set in packaging/docker/site-000-default.conf of the Docker stack). Any other web server needs an equivalent rule that sends requests for non-existing files to webroot/index.php.
Configuration¶
Settings live in z_config/z_settings.ini. When allow_env_config = true, any setting can be overridden by a CONFIG_* environment variable. The Docker stack uses this to inject the database and mailer credentials (see packaging/docker/docker-compose-base.yml). Keep secrets out of the committed INI file and provide them via the environment, but declare a placeholder such as dbpassword = env in the INI for each of them: a variable is ignored unless its key already exists (see environment variable overrides).
Three keys must exist in the INI, otherwise the framework does not boot: host (the base URL, e.g. http://localhost:8080), rootDirectory (the sub-path the app is served from; the key must be present, but its value may be empty; write it without leading or trailing slash, although surrounding slashes and backslashes are trimmed before use) and showErrors (0, 1 or 2, see error handling). A missing key throws an InvalidArgumentException ("The attribute '...' does not exist in the attribute store (yet)") during startup. CONFIG_* environment variables and constructor parameters only override keys that already exist, so they cannot supply a missing one. The project stub in stubs/project/z_config/z_settings.ini already defines all three.
Next steps¶
- Migrations — schema management and the migration CLI.
- Configuration — every available setting.
- MVC and Routing — build your first pages.