Skip to main content
tinymash
  • Screen mode

Installing tinymash

Requirements

tinymash requires:

  • PHP 8.4.1+
  • Nginx, Apache, or another web server that can pass requests to PHP
  • PHP-FPM or another supported PHP SAPI
  • local filesystem write access for runtime data

Required PHP extensions:

  • mbstring
  • json
  • dom
  • session
  • openssl
  • fileinfo

Recommended extensions for full feature coverage:

  • curl
  • gd or imagick
  • simplexml
  • exif
  • intl
  • zip

Prepare the runtime

Use a prepared release package when possible. To build a clean runtime from a source installation, run:

php8.4 bin/tinymash.php deploy /tmp/tinymash-deploy

Copy the prepared tree to its permanent location. Do not copy a new release over an existing application tree; upgrades use a clean sibling directory and upgrade:prepare.

Sites on 0.98.2 or earlier need that manual sibling procedure to reach 0.99.2. The immutable 0.99.0 archive also predates the guarded updater. The manual procedure is recommended for 0.99.1 too: an in-app update started there still uses its original recovery worker and its interruption-recovery limitations. Once the site runs 0.99.2, later compatible signed releases use the corrected recovery behavior from System > Updates.

Configure the web server

Set the document root to the runtime tree's public/ directory:

/path/to/tinymash/public

Do not expose the repository or runtime root. Configuration, users, content storage, drafts, backups, and temporary files must remain outside the web document root.

The release includes sample Nginx, Apache, PHP-FPM, OPcache, HTTP Basic authentication, cron, and log-rotation files under samples/.

Give each installation a distinct, stable PHP session.name. Use a short cookie-safe value that starts with a letter:

php_value[session.name] = TINYMASHEXAMPLE

Use php_value so browser setup can temporarily select its isolated session. If the pool locks session.name, session.save_path, or a non-file session handler with php_admin_value, use CLI setup or allow those settings to change during browser setup.

This prevents session-cookie collisions when several installations share a hostname. Keep the value unchanged during upgrades. PHP's session.gc_maxlifetime controls how long an inactive server-side session remains available.

Give each PHP-FPM pool a site-specific writable temporary directory. The included pool sample sets sys_temp_dir and the fallback environment variables. See Filesystem and permissions for the selection order and CLI behavior.

Set permissions

The PHP user must be able to write to:

  • data/
  • users/
  • tmp/

Setup also needs write access to app/config/ to publish the configuration. Browser setup removes its two host files from the installation root on completion; if PHP cannot remove them, remove the named files on the host after setup. Application source and the public asset tree do not need routine write access for publishing.

Browser setup

For a fresh installation at the domain root, open /install after preparing two files beside app/, data/, and public/:

cd /path/to/tinymash
umask 077
php8.4 -r 'echo bin2hex(random_bytes(16)), PHP_EOL;' > .tinymash-install-token
printf '%s\n' 'https://example.com' > .tinymash-install-origin

Use the site's exact HTTPS origin, including a non-default port when applicable, without a URL path. Uploading equivalent PHP-readable files is also supported. Keep both files outside public/. The token accepts 1–64 visible characters; use at least 32 random characters, and never put it in a URL or reuse an account password.

Browser setup requires PHP cURL, working HTTPS self-requests, and enough PHP workers to answer the hosting check. Plain HTTP is accepted only for loopback development. Whole-host HTTP Basic authentication or an unprovable proxy/TLS mapping requires CLI setup. The checks do not change the web server, permissions, dependencies, or TLS configuration.

Enter the token, wait for hosting checks, then enter the site details and first administrator credentials. Public visibility is the default; select Private if sign-in should be required. Essential steps work without JavaScript. Setup publishes the administrator and configuration, removes its exact host files, expires its installer session, and sends you to ordinary sign-in without automatically signing in.

If cleanup fails after creation, follow the named host cleanup steps; do not repeat setup. Existing configuration disables /install, even if a token remains.

CLI setup

From the runtime root, run:

php8.4 bin/tinymash.php setup

Setup creates the site configuration and first superadmin account using the same validation and defaults as the browser. It does not require a database or a browser token.

If setup is interrupted after writing an account but before publishing configuration, the browser stays closed. Inspect the host state. A lone valid active superadmin with otherwise empty stores can be completed through setup --update, using the existing username and re-entered site details; omit password input to retain its password. Mixed state, malformed configuration, or abandoned staging requires host inspection. Preserve accounts and staged files rather than deleting them to reopen setup.

After setup:

  1. open the admin URL and sign in
  2. review the site URL, timezone, language, theme, mail, and publishing settings
  3. install the scheduled publishing and housekeeping cron entries from samples/cron/tinymash.cron
  4. create a verified backup before importing or making a major structural change

Protect the admin URL

tinymash provides its own sign-in. An additional HTTP Basic authentication layer can be limited to /admin; the release includes examples for Nginx and Apache, for both top-level and sub-URL installations.

Do not protect the whole virtual host when guests must use tinymash secret links. The web server would challenge the request before tinymash can validate the link. A private development site can protect the whole host when no guest access is required.