Refactor: Koillection

Use default value for MAINT_MODE to prevent errors when the variable is unset. This ensures the maintenance mode check works reliably.

CHANGELOG.md

@@ -393,6 +393,16 @@ Exercise vigilance regarding copycat or coat-tailing sites that seek to exploit
 
 ## 2026-01-30
 
+### 💾 Core
+
+  - #### 🐞 Bug Fixes
+
+    - core: meilisearch - add data migration for version upgrades [@MickLesk](https://github.com/MickLesk) ([#11356](https://github.com/community-scripts/ProxmoxVE/pull/11356))
+
+  - #### ✨ New Features
+
+    - core: php - improve module handling and prevent installation failures [@MickLesk](https://github.com/MickLesk) ([#11358](https://github.com/community-scripts/ProxmoxVE/pull/11358))
+
 ## 2026-01-29
 
 ### 🆕 New Scripts

ct/immich.sh

@@ -250,7 +250,7 @@ EOF
     ln -s "$GEO_DIR" "$APP_DIR"
 
     chown -R immich:immich "$INSTALL_DIR"
-    if [[ "$MAINT_MODE" == 1 ]]; then
+    if [[ "${MAINT_MODE:-0}" == 1 ]]; then
       msg_info "Disabling Maintenance Mode"
       cd /opt/immich/app/bin
       $STD bash ./immich-admin disable-maintenance-mode

ct/koillection.sh

@@ -31,8 +31,8 @@ function update_script() {
     msg_info "Stopping Service"
     systemctl stop apache2
     msg_ok "Stopped Service"
-    
+
-    PHP_VERSION="8.5" PHP_APACHE="YES" PHP_MODULE="apcu,ctype,dom,fileinfo,iconv,pgsql" setup_php
+    PHP_VERSION="8.5" PHP_APACHE="YES" setup_php
     
     msg_info "Creating a backup"
     mv /opt/koillection/ /opt/koillection-backup
@@ -45,6 +45,7 @@ function update_script() {
     cp -r /opt/koillection-backup/.env.local /opt/koillection
     cp -r /opt/koillection-backup/public/uploads/. /opt/koillection/public/uploads/
     export COMPOSER_ALLOW_SUPERUSER=1
+    export APP_RUNTIME='Symfony\Component\Runtime\SymfonyRuntime'
     $STD composer install --no-dev -o --no-interaction --classmap-authoritative
     $STD php bin/console doctrine:migrations:migrate --no-interaction
     $STD php bin/console app:translations:dump

install/koillection-install.sh

@@ -13,24 +13,11 @@ setting_up_container
 network_check
 update_os
 
-NODE_VERSION="22" NODE_MODULE="yarn@latest" setup_nodejs
+NODE_VERSION="24" NODE_MODULE="yarn" setup_nodejs
 PG_VERSION="16" setup_postgresql
-PHP_VERSION="8.5" PHP_APACHE="YES" PHP_MODULE="apcu,ctype,dom,fileinfo,iconv,pgsql" setup_php
+PHP_VERSION="8.5" PHP_APACHE="YES" setup_php
 setup_composer
-
+PG_DB_NAME="koillection" PG_DB_USER="koillection" setup_postgresql_db
-msg_info "Setting up PostgreSQL"
-DB_NAME=koillection
-DB_USER=koillection
-DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | cut -c1-13)
-$STD sudo -u postgres psql -c "CREATE ROLE $DB_USER WITH LOGIN PASSWORD '$DB_PASS';"
-$STD sudo -u postgres psql -c "CREATE DATABASE $DB_NAME WITH OWNER $DB_USER TEMPLATE template0;"
-{
-  echo "Koillection Credentials"
-  echo "Koillection Database User: $DB_USER"
-  echo "Koillection Database Password: $DB_PASS"
-  echo "Koillection Database Name: $DB_NAME"
-} >>~/koillection.creds
-msg_ok "Set up PostgreSQL"
 
 fetch_and_deploy_gh_release "koillection" "benjaminjonard/koillection" "tarball"
 
@@ -41,11 +28,12 @@ APP_SECRET=$(openssl rand -base64 32)
 sed -i -e "s|^APP_ENV=.*|APP_ENV=prod|" \
   -e "s|^APP_DEBUG=.*|APP_DEBUG=0|" \
   -e "s|^APP_SECRET=.*|APP_SECRET=${APP_SECRET}|" \
-  -e "s|^DB_NAME=.*|DB_NAME=${DB_NAME}|" \
+  -e "s|^DB_NAME=.*|DB_NAME=${PG_DB_NAME}|" \
-  -e "s|^DB_USER=.*|DB_USER=${DB_USER}|" \
+  -e "s|^DB_USER=.*|DB_USER=${PG_DB_USER}|" \
-  -e "s|^DB_PASSWORD=.*|DB_PASSWORD=${DB_PASS}|" \
+  -e "s|^DB_PASSWORD=.*|DB_PASSWORD=${PG_DB_PASS}|" \
   /opt/koillection/.env.local
 export COMPOSER_ALLOW_SUPERUSER=1
+export APP_RUNTIME='Symfony\Component\Runtime\SymfonyRuntime'
 $STD composer install --no-dev -o --no-interaction --classmap-authoritative
 $STD php bin/console doctrine:migrations:migrate --no-interaction
 $STD php bin/console app:translations:dump

misc/tools.func

@@ -4460,6 +4460,8 @@ function setup_nodejs() {
 #   - Adds Sury PHP repo if needed
 #   - Installs default and user-defined modules
 #   - Patches php.ini for CLI, Apache, and FPM as needed
+#   - Handles built-in modules gracefully (e.g., opcache in PHP 8.5+)
+#   - Skips unavailable packages without failing
 #
 # Variables:
 #   PHP_VERSION                - PHP version to install (default: 8.4)
@@ -4470,6 +4472,17 @@ function setup_nodejs() {
 #   PHP_UPLOAD_MAX_FILESIZE    - (default: 128M)
 #   PHP_POST_MAX_SIZE          - (default: 128M)
 #   PHP_MAX_EXECUTION_TIME     - (default: 300)
+#
+# Notes on modules:
+#   - Base modules (always installed): bcmath, cli, curl, gd, intl, mbstring,
+#     readline, xml, zip, common
+#   - Extended modules (commonly needed): mysql, sqlite3, pgsql, redis,
+#     imagick, bz2, ldap, soap, imap, gmp, apcu
+#   - Some modules are built-in depending on PHP version:
+#     * PHP 8.5+: opcache is built-in (no separate package)
+#     * All versions: ctype, fileinfo, iconv, tokenizer, phar, posix, etc.
+#       are part of php-common
+#   - Unavailable modules are skipped with a warning, not an error
 # ------------------------------------------------------------------------------
 
 function setup_php() {
@@ -4481,23 +4494,69 @@ function setup_php() {
   DISTRO_ID=$(awk -F= '/^ID=/{print $2}' /etc/os-release | tr -d '"')
   DISTRO_CODENAME=$(awk -F= '/^VERSION_CODENAME=/{print $2}' /etc/os-release)
 
-  local DEFAULT_MODULES="bcmath,cli,curl,gd,intl,mbstring,opcache,readline,xml,zip"
+  # Parse version for compatibility checks
-  local COMBINED_MODULES
+  local PHP_MAJOR="${PHP_VERSION%%.*}"
+  local PHP_MINOR="${PHP_VERSION#*.}"
+  PHP_MINOR="${PHP_MINOR%%.*}"
+
+  # Modules that are ALWAYS part of php-common (no separate package needed)
+  # These are either built-in or virtual packages provided by php-common
+  local BUILTIN_MODULES="calendar,ctype,exif,ffi,fileinfo,ftp,gettext,iconv,pdo,phar,posix,shmop,sockets,sysvmsg,sysvsem,sysvshm,tokenizer"
+
+  # Modules that became built-in in specific PHP versions
+  # PHP 8.5+: opcache is now part of the core
+  local BUILTIN_85=""
+  if [[ "$PHP_MAJOR" -gt 8 ]] || [[ "$PHP_MAJOR" -eq 8 && "$PHP_MINOR" -ge 5 ]]; then
+    BUILTIN_85="opcache"
+  fi
+
+  # Base modules - essential for most PHP applications
+  # Note: 'common' provides many built-in extensions
+  local BASE_MODULES="cli,common,bcmath,curl,gd,intl,mbstring,readline,xml,zip"
+
+  # Add opcache only for PHP < 8.5 (it's built-in starting from 8.5)
+  if [[ "$PHP_MAJOR" -lt 8 ]] || [[ "$PHP_MAJOR" -eq 8 && "$PHP_MINOR" -lt 5 ]]; then
+    BASE_MODULES="${BASE_MODULES},opcache"
+  fi
+
+  # Extended default modules - commonly needed by web applications
+  # These cover ~90% of typical use cases without bloat
+  local EXTENDED_MODULES="mysql,sqlite3,pgsql,redis,imagick,bz2,apcu"
+
+  local COMBINED_MODULES="${BASE_MODULES},${EXTENDED_MODULES}"
 
   local PHP_MEMORY_LIMIT="${PHP_MEMORY_LIMIT:-512M}"
   local PHP_UPLOAD_MAX_FILESIZE="${PHP_UPLOAD_MAX_FILESIZE:-128M}"
   local PHP_POST_MAX_SIZE="${PHP_POST_MAX_SIZE:-128M}"
   local PHP_MAX_EXECUTION_TIME="${PHP_MAX_EXECUTION_TIME:-300}"
 
-  # Merge default + user-defined modules
+  # Merge with user-defined modules
   if [[ -n "$PHP_MODULE" ]]; then
-    COMBINED_MODULES="${DEFAULT_MODULES},${PHP_MODULE}"
+    COMBINED_MODULES="${COMBINED_MODULES},${PHP_MODULE}"
-  else
-    COMBINED_MODULES="${DEFAULT_MODULES}"
   fi
 
+  # Filter out built-in modules (they don't have separate packages)
+  local FILTERED_MODULES=""
+  IFS=',' read -ra ALL_MODULES <<<"$COMBINED_MODULES"
+  for mod in "${ALL_MODULES[@]}"; do
+    mod=$(echo "$mod" | tr -d '[:space:]')
+    [[ -z "$mod" ]] && continue
+
+    # Skip if it's a known built-in module
+    if echo ",$BUILTIN_MODULES,$BUILTIN_85," | grep -qi ",$mod,"; then
+      continue
+    fi
+
+    # Add to filtered list
+    if [[ -z "$FILTERED_MODULES" ]]; then
+      FILTERED_MODULES="$mod"
+    else
+      FILTERED_MODULES="${FILTERED_MODULES},$mod"
+    fi
+  done
+
   # Deduplicate
-  COMBINED_MODULES=$(echo "$COMBINED_MODULES" | tr ',' '\n' | awk '!seen[$0]++' | paste -sd, -)
+  COMBINED_MODULES=$(echo "$FILTERED_MODULES" | tr ',' '\n' | awk '!seen[$0]++' | paste -sd, -)
 
   # Get current PHP-CLI version
   local CURRENT_PHP=""
@@ -4555,16 +4614,41 @@ EOF
     return 1
   fi
 
-  # Build module list - without version pinning (preferences.d handles it)
+  # Build module list - verify each package exists before adding
   local MODULE_LIST="php${PHP_VERSION}"
+  local SKIPPED_MODULES=""
 
   IFS=',' read -ra MODULES <<<"$COMBINED_MODULES"
   for mod in "${MODULES[@]}"; do
-    MODULE_LIST+=" php${PHP_VERSION}-${mod}"
+    mod=$(echo "$mod" | tr -d '[:space:]')
+    [[ -z "$mod" ]] && continue
+
+    local pkg_name="php${PHP_VERSION}-${mod}"
+
+    # Check if package exists in repository
+    if apt-cache show "$pkg_name" &>/dev/null; then
+      MODULE_LIST+=" $pkg_name"
+    else
+      # Package doesn't exist - could be built-in or renamed
+      if [[ -z "$SKIPPED_MODULES" ]]; then
+        SKIPPED_MODULES="$mod"
+      else
+        SKIPPED_MODULES="${SKIPPED_MODULES}, $mod"
+      fi
+    fi
   done
 
+  # Log skipped modules (informational, not an error)
+  if [[ -n "$SKIPPED_MODULES" ]]; then
+    msg_info "Skipping unavailable/built-in modules: $SKIPPED_MODULES"
+  fi
+
   if [[ "$PHP_FPM" == "YES" ]]; then
-    MODULE_LIST+=" php${PHP_VERSION}-fpm"
+    if apt-cache show "php${PHP_VERSION}-fpm" &>/dev/null; then
+      MODULE_LIST+=" php${PHP_VERSION}-fpm"
+    else
+      msg_warn "php${PHP_VERSION}-fpm not available"
+    fi
     # Create systemd override for PHP-FPM to fix runtime directory issues in LXC containers
     mkdir -p /etc/systemd/system/php${PHP_VERSION}-fpm.service.d/
     cat <<EOF >/etc/systemd/system/php${PHP_VERSION}-fpm.service.d/override.conf
@@ -4591,38 +4675,31 @@ EOF
 
   # Install PHP packages (pinning via preferences.d ensures correct version)
   msg_info "Installing PHP ${PHP_VERSION} packages"
-  if ! install_packages_with_retry $MODULE_LIST; then
+
-    msg_warn "Failed to install PHP packages, attempting individual installation"
+  # First attempt: Install all verified packages at once
+  if ! $STD apt install -y $MODULE_LIST 2>/dev/null; then
+    msg_warn "Bulk installation failed, attempting individual installation"
 
     # Install main package first (critical)
-    install_packages_with_retry "php${PHP_VERSION}" || {
+    if ! $STD apt install -y "php${PHP_VERSION}" 2>/dev/null; then
       msg_error "Failed to install php${PHP_VERSION}"
       return 1
-    }
+    fi
 
     # Try to install Apache module individually if requested
     if [[ "$PHP_APACHE" == "YES" ]]; then
-      install_packages_with_retry "libapache2-mod-php${PHP_VERSION}" || {
+      $STD apt install -y "libapache2-mod-php${PHP_VERSION}" 2>/dev/null || {
         msg_warn "Could not install libapache2-mod-php${PHP_VERSION}"
       }
     fi
 
-    # Try to install modules individually - skip those that don't exist
+    # Try to install each package individually
-    for pkg in "${MODULES[@]}"; do
+    for pkg in $MODULE_LIST; do
-      if apt-cache search "^php${PHP_VERSION}-${pkg}\$" 2>/dev/null | grep -q "^php${PHP_VERSION}-${pkg}"; then
+      [[ "$pkg" == "php${PHP_VERSION}" ]] && continue  # Already installed
-        install_packages_with_retry "php${PHP_VERSION}-${pkg}" || {
+      $STD apt install -y "$pkg" 2>/dev/null || {
-          msg_warn "Could not install php${PHP_VERSION}-${pkg}"
+        msg_warn "Could not install $pkg - continuing without it"
-        }
+      }
-      fi
     done
-
-    if [[ "$PHP_FPM" == "YES" ]]; then
-      if apt-cache search "^php${PHP_VERSION}-fpm\$" 2>/dev/null | grep -q "^php${PHP_VERSION}-fpm"; then
-        install_packages_with_retry "php${PHP_VERSION}-fpm" || {
-          msg_warn "Could not install php${PHP_VERSION}-fpm"
-        }
-      fi
-    fi
   fi
   cache_installed_version "php" "$PHP_VERSION"
 
@@ -5182,9 +5259,169 @@ function setup_meilisearch() {
   if [[ -f /usr/bin/meilisearch ]]; then
     if check_for_gh_release "meilisearch" "meilisearch/meilisearch"; then
       msg_info "Updating MeiliSearch"
+
+      # Get current and new version for compatibility check
+      local CURRENT_VERSION NEW_VERSION
+      CURRENT_VERSION=$(/usr/bin/meilisearch --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1) || CURRENT_VERSION="0.0.0"
+      NEW_VERSION="${CHECK_UPDATE_RELEASE#v}"
+
+      # Extract major.minor for comparison (Meilisearch requires dump/restore between minor versions)
+      local CURRENT_MAJOR_MINOR NEW_MAJOR_MINOR
+      CURRENT_MAJOR_MINOR=$(echo "$CURRENT_VERSION" | cut -d. -f1,2)
+      NEW_MAJOR_MINOR=$(echo "$NEW_VERSION" | cut -d. -f1,2)
+
+      # Determine if migration is needed (different major.minor = incompatible DB format)
+      local NEEDS_MIGRATION=false
+      if [[ "$CURRENT_MAJOR_MINOR" != "$NEW_MAJOR_MINOR" ]]; then
+        NEEDS_MIGRATION=true
+        msg_info "MeiliSearch version change detected (${CURRENT_VERSION} → ${NEW_VERSION}), preparing data migration"
+      fi
+
+      # Read config values for dump/restore
+      local MEILI_HOST MEILI_PORT MEILI_MASTER_KEY MEILI_DUMP_DIR
+      MEILI_HOST="${MEILISEARCH_HOST:-127.0.0.1}"
+      MEILI_PORT="${MEILISEARCH_PORT:-7700}"
+      MEILI_DUMP_DIR="${MEILISEARCH_DUMP_DIR:-/var/lib/meilisearch/dumps}"
+      MEILI_MASTER_KEY=$(grep -E "^master_key\s*=" /etc/meilisearch.toml 2>/dev/null | sed 's/.*=\s*"\(.*\)"/\1/' | tr -d ' ')
+
+      # Create dump before update if migration is needed
+      local DUMP_UID=""
+      if [[ "$NEEDS_MIGRATION" == "true" ]] && [[ -n "$MEILI_MASTER_KEY" ]]; then
+        msg_info "Creating MeiliSearch data dump before upgrade"
+
+        # Trigger dump creation
+        local DUMP_RESPONSE
+        DUMP_RESPONSE=$(curl -s -X POST "http://${MEILI_HOST}:${MEILI_PORT}/dumps" \
+          -H "Authorization: Bearer ${MEILI_MASTER_KEY}" \
+          -H "Content-Type: application/json" 2>/dev/null) || true
+
+        # The initial response only contains taskUid, not dumpUid
+        # dumpUid is only available after the task completes
+        local TASK_UID
+        TASK_UID=$(echo "$DUMP_RESPONSE" | grep -oP '"taskUid":\s*\K[0-9]+' || true)
+
+        if [[ -n "$TASK_UID" ]]; then
+          msg_info "Waiting for dump task ${TASK_UID} to complete..."
+          local MAX_WAIT=120
+          local WAITED=0
+          local TASK_RESULT=""
+          
+          while [[ $WAITED -lt $MAX_WAIT ]]; do
+            TASK_RESULT=$(curl -s "http://${MEILI_HOST}:${MEILI_PORT}/tasks/${TASK_UID}" \
+              -H "Authorization: Bearer ${MEILI_MASTER_KEY}" 2>/dev/null) || true
+            
+            local TASK_STATUS
+            TASK_STATUS=$(echo "$TASK_RESULT" | grep -oP '"status":\s*"\K[^"]+' || true)
+            
+            if [[ "$TASK_STATUS" == "succeeded" ]]; then
+              # Extract dumpUid from the completed task details
+              DUMP_UID=$(echo "$TASK_RESULT" | grep -oP '"dumpUid":\s*"\K[^"]+' || true)
+              if [[ -n "$DUMP_UID" ]]; then
+                msg_ok "MeiliSearch dump created successfully: ${DUMP_UID}"
+              else
+                msg_warn "Dump task succeeded but could not extract dumpUid"
+              fi
+              break
+            elif [[ "$TASK_STATUS" == "failed" ]]; then
+              local ERROR_MSG
+              ERROR_MSG=$(echo "$TASK_RESULT" | grep -oP '"message":\s*"\K[^"]+' || echo "Unknown error")
+              msg_warn "MeiliSearch dump failed: ${ERROR_MSG}"
+              break
+            fi
+            sleep 2
+            WAITED=$((WAITED + 2))
+          done
+
+          if [[ $WAITED -ge $MAX_WAIT ]]; then
+            msg_warn "MeiliSearch dump timed out after ${MAX_WAIT}s"
+          fi
+        else
+          msg_warn "Could not trigger MeiliSearch dump (no taskUid in response)"
+          msg_info "Response was: ${DUMP_RESPONSE:-empty}"
+        fi
+      fi
+
+      # If migration is needed but dump failed, we have options:
+      # 1. Abort the update (safest, but annoying)
+      # 2. Backup data directory and proceed (allows manual recovery)
+      # 3. Just proceed and hope for the best (dangerous)
+      # We choose option 2: backup and proceed with warning
+      if [[ "$NEEDS_MIGRATION" == "true" ]] && [[ -z "$DUMP_UID" ]]; then
+        local MEILI_DB_PATH
+        MEILI_DB_PATH=$(grep -E "^db_path\s*=" /etc/meilisearch.toml 2>/dev/null | sed 's/.*=\s*"\(.*\)"/\1/' | tr -d ' ')
+        MEILI_DB_PATH="${MEILI_DB_PATH:-/var/lib/meilisearch/data}"
+        
+        if [[ -d "$MEILI_DB_PATH" ]] && [[ -n "$(ls -A "$MEILI_DB_PATH" 2>/dev/null)" ]]; then
+          local BACKUP_PATH="${MEILI_DB_PATH}.backup.$(date +%Y%m%d%H%M%S)"
+          msg_warn "Backing up MeiliSearch data to ${BACKUP_PATH}"
+          mv "$MEILI_DB_PATH" "$BACKUP_PATH"
+          mkdir -p "$MEILI_DB_PATH"
+          msg_info "Data backed up. After update, you may need to reindex your data."
+          msg_info "Old data is preserved at: ${BACKUP_PATH}"
+        fi
+      fi
+
+      # Stop service and update binary
       systemctl stop meilisearch
       fetch_and_deploy_gh_release "meilisearch" "meilisearch/meilisearch" "binary"
-      systemctl start meilisearch
+
+      # If migration needed and dump was created, remove old data and import dump
+      if [[ "$NEEDS_MIGRATION" == "true" ]] && [[ -n "$DUMP_UID" ]]; then
+        local MEILI_DB_PATH
+        MEILI_DB_PATH=$(grep -E "^db_path\s*=" /etc/meilisearch.toml 2>/dev/null | sed 's/.*=\s*"\(.*\)"/\1/' | tr -d ' ')
+        MEILI_DB_PATH="${MEILI_DB_PATH:-/var/lib/meilisearch/data}"
+
+        msg_info "Removing old MeiliSearch database for migration"
+        rm -rf "${MEILI_DB_PATH:?}"/*
+
+        # Import dump using CLI flag (this is the supported method)
+        local DUMP_FILE="${MEILI_DUMP_DIR}/${DUMP_UID}.dump"
+        if [[ -f "$DUMP_FILE" ]]; then
+          msg_info "Importing dump: ${DUMP_FILE}"
+          
+          # Start meilisearch with --import-dump flag
+          # This is a one-time import that happens during startup
+          /usr/bin/meilisearch --config-file-path /etc/meilisearch.toml --import-dump "$DUMP_FILE" &
+          local MEILI_PID=$!
+          
+          # Wait for meilisearch to become healthy (import happens during startup)
+          msg_info "Waiting for MeiliSearch to import and start..."
+          local MAX_WAIT=300
+          local WAITED=0
+          while [[ $WAITED -lt $MAX_WAIT ]]; do
+            if curl -sf "http://${MEILI_HOST}:${MEILI_PORT}/health" &>/dev/null; then
+              msg_ok "MeiliSearch is healthy after import"
+              break
+            fi
+            # Check if process is still running
+            if ! kill -0 $MEILI_PID 2>/dev/null; then
+              msg_warn "MeiliSearch process exited during import"
+              break
+            fi
+            sleep 3
+            WAITED=$((WAITED + 3))
+          done
+          
+          # Stop the manual process
+          kill $MEILI_PID 2>/dev/null || true
+          sleep 2
+          
+          # Start via systemd for proper management
+          systemctl start meilisearch
+          
+          if systemctl is-active --quiet meilisearch; then
+            msg_ok "MeiliSearch migrated successfully"
+          else
+            msg_warn "MeiliSearch failed to start after migration - check logs with: journalctl -u meilisearch"
+          fi
+        else
+          msg_warn "Dump file not found: ${DUMP_FILE}"
+          systemctl start meilisearch
+        fi
+      else
+        systemctl start meilisearch
+      fi
+
       msg_ok "Updated MeiliSearch"
     fi
     return 0