PHP-FPM: ordinary and isolated installation
This English guide follows two FPM architectures from release 0.2.4: ordinary FPM on SimbiozaEN_FPM and isolated FPM on SimbiozaEN_FPMsecured. Ordinary FPM uses the shared web account and CLI for later package operations. Isolated FPM has its own service, Unix identities and limited helper, allowing GUI management of modules, languages and upgrades. Do not mix the permissions or ports of these modes.
The Apache and temporary Nginx test servers listened on loopback only. Use HTTPS and your own domain for a public deployment. One-time installer tokens and passwords are intentionally absent from this guide. Screenshots come from the real light-theme installations, not mock-ups.
1. Common prerequisites and one release tag
Verify the PHP CLI, FPM binary, required extensions, Composer, Git and the web server. SQLite was used in the two English walkthrough installations; MySQL and PostgreSQL require their matching PDO driver, an empty database and a dedicated DB user. A successful php -v command alone does not tell you which version the FPM worker uses. On Debian, install version-matched php-fpm, php-cli, php-sqlite3, php-xml, php-mbstring, php-intl, php-zip, Composer 2 and acl. Apache also needs rewrite, proxy and proxy_fcgi; Nginx uses FastCGI directly.
php -v
php -m
/opt/homebrew/sbin/php-fpm -v
composer --version
git --version
id -un
id -GnFetch a single tagged release. Do not copy .git into the deployed app or mix files from different tags. The fresh tag has no composer.lock, so use explicit composer update for a new installation. Existing sites must later use Simbioza's updater instead of replacing it with a bare Composer update.
SIMBIOZA_TAG=0.2.4
SIMBIOZA_FETCH_DIR="$(mktemp -d)"
mkdir "$SIMBIOZA_FETCH_DIR/release"
git -C "$SIMBIOZA_FETCH_DIR/release" init -q
git -C "$SIMBIOZA_FETCH_DIR/release" remote add origin https://github.com/kmihalj/Simbioza.git
git -C "$SIMBIOZA_FETCH_DIR/release" fetch --quiet --depth 1 origin "refs/tags/$SIMBIOZA_TAG:refs/tags/$SIMBIOZA_TAG"
git -C "$SIMBIOZA_FETCH_DIR/release" -c advice.detachedHead=false checkout --quiet "$SIMBIOZA_TAG"
cat "$SIMBIOZA_FETCH_DIR/release/VERSION"2. Ordinary FPM: the English installation
The English ordinary FPM pool runs in a root-owned service as the shared web identity _www and listens only on 127.0.0.1:9078. Do not rely on an existing Homebrew pool that runs under a different account. On Linux, adapt the pool to the real versioned service and web identity, such as www-data.
2.1. English ordinary FPM: files, Composer and permissions
mkdir -p /Users/Shared/Simbioza/SimbiozaEN_FPM
rsync --archive --exclude=.git/ "$SIMBIOZA_FETCH_DIR/release/" /Users/Shared/Simbioza/SimbiozaEN_FPM/
cd /Users/Shared/Simbioza/SimbiozaEN_FPM
composer update --with-all-dependencies --optimize-autoloader
composer check-platform-reqs
mkdir -p config data/cache data/logs data/sessions data/setup-requests data/tmp resources/config/menu resources/config/theme
sudo chgrp -R _www config data resources/config/menu resources/config/theme
sudo chmod 3770 config
sudo chmod 2770 resources/config/menu resources/config/theme
sudo chmod -R g+rwX data resources/config/menu resources/config/theme
sudo chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' config
sudo find data resources/config/menu resources/config/theme -type d -exec chmod +a 'user:kmihalj allow read,write,append,execute,delete,readattr,writeattr,readextattr,writeextattr,readsecurity,file_inherit,directory_inherit' {} +
ls -lde data data/sessions data/tmpThis site has its own SQLite database, sessions and temporary files. Confirm access for both the web worker and maintainer before opening the installer.
2.2. Ordinary FPM pools and service
These are the relevant directives for the English ordinary pool and its global configuration. It has its own port, session directory and temporary files. Keep the listener on loopback.
[global]
pid = /opt/homebrew/var/run/php-fpm-install-guides.pid
error_log = /opt/homebrew/var/log/php-fpm-install-guides.log
daemonize = no
include = /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d/*.conf
[simbioza-guide-en]
user = _www
group = _www
listen = 127.0.0.1:9078
listen.allowed_clients = 127.0.0.1
pm = ondemand
pm.max_children = 4
pm.process_idle_timeout = 10s
pm.max_requests = 500
clear_env = yes
security.limit_extensions = .php
env[TMPDIR] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmp
php_admin_value[session.save_path] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/sessions
php_admin_value[upload_tmp_dir] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmp
php_admin_value[sys_temp_dir] = /Users/Shared/Simbioza/SimbiozaEN_FPM/data/tmpFile placement: save the [global] part through include as php-fpm-install-guides.conf and the English pool as php-fpm-install-guides.d/en.conf. Validate the syntax after creating them. Do not copy the other pool into this procedure.
sudo mkdir -p /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d
sudoedit /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf
sudoedit /opt/homebrew/etc/php/8.5/php-fpm-install-guides.d/en.conf
sudoedit /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plistPut the complete content below into the last file. This is a separate test service, not a replacement for any existing Homebrew FPM service:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>hr.simbioza-guide-ordinary.php-fpm</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/sbin/php-fpm</string>
<string>--nodaemonize</string>
<string>--fpm-config</string>
<string>/opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>/opt/homebrew/var/log/php-fpm-install-guides-launchd.log</string>
<key>StandardErrorPath</key><string>/opt/homebrew/var/log/php-fpm-install-guides-launchd.log</string>
</dict>
</plist>On Linux, do not copy the macOS plist or /opt/homebrew paths. Put the English pool in the directory for the PHP version actually installed, for example /etc/php/8.4/fpm/pool.d/; replace _www with the actual web identity and the paths with /srv/..., then run sudo php-fpm8.4 -t and sudo systemctl restart php8.4-fpm. Those Linux commands are an adaptation pattern; the illustrated English walkthroughs were performed on macOS, so check your distribution's service name.
On macOS, the master service must start as root so the workers may switch to _www. The tested LaunchDaemon called /opt/homebrew/sbin/php-fpm --nodaemonize --fpm-config /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf and used RunAtLoad and KeepAlive. On Linux, systemd manages the corresponding versioned FPM service. Verify systemctl status php8.4-fpm, listening ports and the worker identity, not just the existence of a configuration file.
sudo chown root:wheel /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
sudo chmod 644 /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
/opt/homebrew/sbin/php-fpm --test --fpm-config /opt/homebrew/etc/php/8.5/php-fpm-install-guides.conf
sudo launchctl bootstrap system /Library/LaunchDaemons/hr.simbioza-guide-ordinary.php-fpm.plist
sudo launchctl print system/hr.simbioza-guide-ordinary.php-fpm
lsof -nP -iTCP:9078 -sTCP:LISTENDo not call bootstrap a second time when the service is already loaded; inspect it with launchctl print and reload it in a controlled manner after a configuration change. The installed version and port numbers must match what Apache or Nginx will use.
2.3. Apache or Nginx: choose one front end
Apache routed the English ordinary FPM alias to port 9078 with mod_proxy and mod_proxy_fcgi. Apache does not start FPM. ProxyTimeout 900 permits longer requests but does not replace PHP/FPM limits. Use a TLS virtual host and serve only public/ in production.
LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
ProxyTimeout 900
Alias /SimbiozaEN_FPM "/Users/Shared/Simbioza/SimbiozaEN_FPM/public"
<Directory "/Users/Shared/Simbioza/SimbiozaEN_FPM/public">
Options -Indexes +FollowSymLinks
AllowOverride All
Require local
DirectoryIndex index.php
<FilesMatch "\.php$">
SetHandler "proxy:fcgi://127.0.0.1:9078"
</FilesMatch>
</Directory>/opt/homebrew/bin/httpd -t -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.conf
sudo /opt/homebrew/bin/httpd -k graceful -f /opt/homebrew/etc/httpd/extra/httpd-simbioza-install-guides.confThe Nginx FastCGI pattern was tested temporarily on the same local host. The example below adapts that pattern to this English site at port 9078; the EN installation itself was verified behind Apache. Use real paths and certificates for a public TLS host. The temporary Nginx installation was removed afterward.
server {
listen 443 ssl;
server_name simbioza.example.org;
root /srv/simbioza/public;
index index.php;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
try_files $uri =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9078;
fastcgi_read_timeout 900s;
}
location ~ /\. {
deny all;
}
}nginx -t
curl -I https://simbioza.example.org/auth/loginThe local Nginx experiment omitted TLS only because the server listened exclusively on loopback; its root, try_files, SCRIPT_FILENAME and fastcgi_pass directives served actual Simbioza pages. Switching front ends does not change database or FPM user permissions. Never configure Nginx to serve the release root.
2.4. Prepare packages and run the English ordinary-FPM wizard
An ordinary pool has no GUI package helper, so the maintainer prepares optional modules in the CLI before opening the English wizard. With no list, php scripts/installation_packages.php prepare prepares all modules; the updated wizard selects them all initially, and you deselect those you do not want. For a smaller set use --modules=theme,calendar,email; for none use --modules=. Check packages with php scripts/installation_packages.php status and, after success, run php scripts/installation_packages.php cleanup. The screenshots record the earlier 0.2.4 test, where only Theme was prepared and Backup was temporarily available for starter guides. Create one token with the exact EN URL prefix; never publish it.
cd /Users/Shared/Simbioza/SimbiozaEN_FPM
php scripts/installation_packages.php prepare
php scripts/installation_packages.php status
php bin/simbioza install:prepare --base-url=http://127.0.0.1:8090/SimbiozaEN_FPMSelect “Simbioza EN FPM”, English as primary language and its own first administrator. Check requirements, test SQLite, fill the form, review and install in order. Select English in the wizard header if your browser initially chooses another language.
2.5. English ordinary FPM: every screen
3. Isolated FPM: distinct identities and GUI package management
The isolated mode is more than a different TCP port. configure_fpm_setup.php creates a dedicated service, web/deploy identities and groups, restricted write paths and a limited helper for checked package operations. Each installation needs a distinct --instance and --listen. --check is read-only; run --finalize only after the web wizard succeeds.
3.1. English isolated FPM: dedicated identity, service and database
mkdir -p /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
rsync --archive --exclude=.git/ "$SIMBIOZA_FETCH_DIR/release/" /Users/Shared/Simbioza/SimbiozaEN_FPMsecured/
cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
composer update --with-all-dependencies --optimize-autoloader
composer check-platform-reqs
sudo php scripts/configure_fpm_setup.php --install --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php scripts/configure_fpm_setup.php --check --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php bin/simbioza install:prepare --base-url=http://127.0.0.1:8090/SimbiozaEN_FPMsecuredApache routes this isolated English site to port 9080. On Linux, supply the actual FPM binary and review the generated pool, service, sudoers rule and file rights before opening the one-time URL.
ProxyTimeout 900
Alias /SimbiozaEN_FPMsecured "/Users/Shared/Simbioza/SimbiozaEN_FPMsecured/public"
<Directory "/Users/Shared/Simbioza/SimbiozaEN_FPMsecured/public">
Options -Indexes +FollowSymLinks
AllowOverride All
Require local
DirectoryIndex index.php
<FilesMatch "\.php$">
SetHandler "proxy:fcgi://127.0.0.1:9080"
</FilesMatch>
</Directory>Validate Apache syntax and reload it before the wizard. With Nginx use the tested location ~ \.php$ pattern from section 2.3, changing fastcgi_pass to 127.0.0.1:9080 for this site. Keep the FPM ports private.
3.2. English isolated FPM: every screen
3.3. Finalize ownership after, not before, the web installation
The English isolated wizard completed Theme installation, migrations and first-admin creation. Only then run --finalize with the same --instance, --listen, --app-root and --php-fpm values used for --install. Accidentally omitting an instance would target a different service. The maintainer should log into a new shell after being added to deploy/runtime groups so the membership takes effect.
cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
sudo php scripts/configure_fpm_setup.php --finalize --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm
php scripts/configure_fpm_setup.php --check --instance=ensecure --listen=127.0.0.1:9080 --app-root=/Users/Shared/Simbioza/SimbiozaEN_FPMsecured --maintainer=kmihalj --php-fpm=/opt/homebrew/sbin/php-fpm4. Modules, languages, upgrades and final checks
On ordinary FPM the initial GUI wizard and enabling/disabling an installed module work, but package add/remove and upgrades belong to the CLI owner. Isolated FPM may run those operations through its restricted helper when checks pass; the web worker must not have write access to vendor/. The EN isolated wizard and post-login setup were verified on the English site.
Authorized deploy users may use these CLI commands in either FPM arrangement. Mandatory modules cannot be removed and optional dependencies are checked. Disable retains data; removal first backs up module data. Installed language packages may be updated independently of the application release.
vendor/bin/hph modules list
vendor/bin/hph modules add calendar --fresh
vendor/bin/hph modules disable calendar
vendor/bin/hph modules enable calendar
vendor/bin/hph modules backups calendar
vendor/bin/hph modules remove calendar --yes
vendor/bin/hph modules add calendar --restore
vendor/bin/hph languages available
vendor/bin/hph languages install de
vendor/bin/hph languages update
php update.php --check
php update.phpBefore a production upgrade, separately back up the SQLite/MySQL/PostgreSQL database, config/, private uploads and themes. Do not run routine upgrades as root. Do not substitute a standalone composer update for the Simbioza updater on an existing installation; the updater preserves selected optional packages, migrations and maintenance state.
Run these checks from the ordinary and isolated English site directories. Both logins returned 200, both locked installers 404, platform checks passed, and each database had 22 executed migrations with zero pending. On ordinary FPM, first remove only the temporary Backup package used for starter guides.
cd /Users/Shared/Simbioza/SimbiozaEN_FPM
php scripts/installation_packages.php cleanup
vendor/bin/hph modules migrate-status
composer check-platform-reqs
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPM/auth/login
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPM/install
cd /Users/Shared/Simbioza/SimbiozaEN_FPMsecured
vendor/bin/hph modules migrate-status
composer check-platform-reqs
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPMsecured/auth/login
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/SimbiozaEN_FPMsecured/installFinally inspect actual sign-in, the home page, navigation, theme and expected modules on each site. Service status alone does not verify a user's path. Cross-check the configuration details against the primary Apache mod_proxy_fcgi, Nginx FastCGI and PHP-FPM documentation.
Comments
0There are no comments yet.
You must sign in to add a comment.