Skip to content

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-mysqli built against mysqlnd: every query calls mysqli_stmt::get_result(), which the libmysqlclient build of mysqli does not offer.
  • ext-mbstring: the framework calls mb_* functions (e.g. in Helpers).
  • ext-ctype, ext-filter and ext-hash: required by PHPMailer, which sends the mails of Response::sendEmail().
  • Argon2id support: new password hashes use password_hash() with PASSWORD_ARGON2ID, so PHP must be compiled with Argon2 (--with-password-argon2, or the PASSWORD_ARGON2ID constant 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:

  1. Builds the application image and starts the Docker stack (detached),
  2. Runs composer install inside the application container,
  3. 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),
  4. 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 (via webroot/index.php, which requires the first existing of index.php, zubzet.php and zubzet) and for CLI use (php index.php <command>). It calls chdir(realpath(__DIR__)), requires autoload.php from $COMPOSER_VENDOR_DIR (default ./vendor), then runs new z_framework() (an alias of ZubZet) and ->execute(). Web and CLI share this script: for php index.php <command>, execute() hands over to the console when no route matches.
  • app/Controllers/: default z_controllers directory with the <Name>Controller.php files. A controller in a sub-folder is found by its plain name, see controllers.
  • app/Models/: default z_models directory with the <Name>Model.php files. A sub-folder is addressed in lower case through dot notation, getModel("reports.GuestbookStats") loads reports/GuestbookStatsModel.php.
  • app/Views/: default z_views directory with views, mail templates and the layout/ folder. Further sub-folders are allowed and addressed in the view name (employee/index).
  • app/Routes/: default routes directory. Every top-level *.php file in it is require_onced when the route dispatcher is built on the first request, sub-folders are not read.
  • app/Database/migrations/: migration files read by db:migrate and db:sync. A missing folder is created with mode 0755.
  • app/Database/seed/: seed files read by db:seed. Sub-folders can be used as selectors for -i and -e. A missing folder is created with mode 0755.
  • z_config/z_settings.ini: settings file at the default config_file path. 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