* Standardize exit codes and add mappings
Replace generic exit 1 usages with specific numeric exit codes and add corresponding explanations to the error lookup. This commit updates multiple misc/* scripts to return distinct codes for validation, Proxmox/LXC, networking, download and curl errors (e.g. 103-123, 64, 107-120, 206, 0 for explicit user cancels). It also updates curl error handling to propagate the original curl exit code and adds new entries in explain_exit_code and the error handler to improve diagnostics.
* Set exit code 115 for update_os errors
Change exit status from 6 to 115 in misc/alpine-install.func's update_os() error handlers when failing to download tools.func or when the expected functions are missing. This gives a distinct exit code for these specific failure cases.
* Add tools/addon exit codes and use them
Introduce exit codes 232-238 for Tools & Addon scripts in misc/api.func and misc/error_handler.func. Update addon scripts (tools/addon/adguardhome-sync.sh, tools/addon/copyparty.sh, tools/addon/cronmaster.sh) to return specific codes instead of generic exit 1: 238 for unsupported OS and 233 when the application is not installed/upgrade prerequisites are missing. This makes failures more descriptive and aligns scripts with the central error explanations.
* Standardize exit codes in exporter addons
Unify exit codes across exporter addon scripts: return 238 for unsupported OS detections and 233 when an update is requested but the exporter is not installed. Applied to nextcloud-exporter.sh, pihole-exporter.sh, prometheus-paperless-ngx-exporter.sh, and qbittorrent-exporter.sh to make failure modes distinguishable for callers/automation.
* Use specific exit codes in addon scripts
Replace generic exit 1 with distinct exit codes across multiple addon scripts to enable finer-grained error handling in automation. Exit codes introduced: 10 for Docker/Compose missing or user-declined Docker install, 233 for "nothing to update" cases, and 238 for unsupported OS cases. Affected files: tools/addon/arcane.sh, coolify.sh, dockge.sh, dokploy.sh, filebrowser-quantum.sh, filebrowser.sh, immich-public-proxy.sh, jellystat.sh, runtipi.sh.
* Use specific exit codes in addon scripts
Replace generic exit 1 with specific exit codes across multiple addon scripts to improve error signaling and handling. Files updated: tools/addon/add-netbird-lxc.sh (exit 238 on unsupported distro), tools/addon/add-tailscale-lxc.sh (treat user cancel as exit 0), tools/addon/glances.sh (exit 233 when not installed), tools/addon/komodo.sh (distinct exits for missing compose, legacy DB, backup/download failures, docker checks), tools/addon/netdata.sh (distinct exits for unsupported PVE versions, OS/codename detection, repo lookups), and tools/addon/phpmyadmin.sh (distinct exits for unsupported OS, network/download issues, package install/start failures, and invalid input). These changes make failures easier to identify and automate recovery or reporting.
* Use specific exit codes in PVE scripts
Replace generic exit 1 with distinct exit codes across tools/pve scripts to provide clearer failure signals for callers. post-pve-install.sh now returns 105 for unsupported Proxmox versions; pve-privilege-converter.sh uses 104 for non-root, 234 when no containers, and 235 for backup/conversion failures; update-apps.sh maps backup failures to 235, missing containers/selections to 234 (and UI cancellations to 0), missing backup storage to 119, and returns the actual container update exit code on failure. These changes improve diagnostics and allow external tooling to react to specific error conditions.
* Standardize exit codes and behaviors
Adjust exit codes and abort handling across multiple PVE helper scripts to provide clearer outcomes for automation and interactive flows. Changes include:
- container-restore-from-backup.sh, core-restore-from-backup.sh: return 235 when no backups found (was 1).
- fstrim.sh: treat user cancellation of non-ext4 warning as non-error (exit 0 instead of 1).
- kernel-clean.sh: treat no selection or user abort as non-error (exit 0 instead of 1).
- lxc-delete.sh: return 234 when no containers are present; treat no selection as non-error (exit 0).
- nic-offloading-fix.sh: use specific non-zero codes for root check and tool install failures (exit 104, 237) and 236 when no matching interfaces (was 1).
- pbs_microcode.sh, post-pmg-install.sh, post-pbs-install.sh: use distinct exit codes (232 and 105) for detected VM/PVE/unsupported distro conditions instead of generic 1.
These modifications make scripts return distinct codes for different failure modes and ensure user-initiated aborts or benign conditions exit with 0 where appropriate.
* Use exit 105 for unsupported PVE versions
Standardize error handling by replacing generic exit 1 with exit 105 in pve_check() across multiple VM template scripts to indicate unsupported Proxmox VE versions. Also add API exit code 226 message for "Proxmox: VM disk import or post-creation setup failed" in misc/api.func. Affected files include misc/api.func and various vm/*-vm.sh scripts.
* Use specific exit codes in VM scripts
Replace generic exit 1 with distinct exit codes across vm/*.sh to make failures more actionable for callers. Changes include: use 226 for missing imported-disk references, 237 for pv installation failures, 115 for download/extract/ISO-related failures, 214 for insufficient disk space during FreeBSD decompression, and 119 for missing storage detection. Updated scripts: archlinux-vm.sh, docker-vm.sh, haos-vm.sh, openwrt-vm.sh, opnsense-vm.sh, truenas-vm.sh, umbrel-os-vm.sh.
Delete the stderr TTY check and the static spinner printf/early return in msg_info. The function now always calls color_spinner and starts the animated spinner in the background, removing the special-case for piped/non-TTY environments and simplifying terminal handling.
Detect non-TTY stderr in msg_info() and print a static progress indicator instead of launching the background spinner (which is unreliable when output is piped). Remove the non-TTY check from is_verbose_mode() and add comments clarifying that non-TTY behavior is handled in msg_info(). Apply the same verbosity simplification to vm-core.func. This keeps spinner visuals working when passed through pipes while avoiding backgrounding issues.
* feat: add Docker-based tool addons for dockge, komodo, dokploy, npmplus
Create addon scripts following the arcane.sh pattern for Docker-based
tools that can be installed on any existing Docker LXC:
- dockge: Docker Compose stack manager (port 5001)
- komodo: Build/deployment system with MongoDB/FerretDB (port 9120)
- dokploy: PaaS via external installer with Redis (port 3000)
- npmplus: Nginx Proxy Manager Plus via Compose (port 81)
Each addon includes:
- Docker availability check
- Install with full configuration
- Update via docker compose pull
- Uninstall with container cleanup
- ASCII header files
Original ct/ and install/ scripts are preserved for now.
* refactor: convert Docker tools to addons, remove old scripts
Convert dockge, komodo, dokploy, coolify from standalone ct/install
scripts to addon pattern (like arcane.sh).
Added:
- tools/addon/dockge.sh (port 5001)
- tools/addon/komodo.sh (port 9120, MongoDB/FerretDB choice)
- tools/addon/dokploy.sh (port 3000, external installer)
- tools/addon/coolify.sh (port 8000, external installer)
- tools/headers/ for all 4
Removed:
- ct/dockge.sh, ct/komodo.sh, ct/alpine-komodo.sh, ct/dokploy.sh, ct/coolify.sh
- install/dockge-install.sh, install/komodo-install.sh, install/alpine-komodo-install.sh
- install/dokploy-install.sh, install/coolify-install.sh
- frontend/public/json/ for dockge, komodo, dokploy, coolify
- tools/addon/npmplus.sh (not an addon candidate)
These tools are Docker-only and fit the addon pattern: they require
an existing Docker LXC and manage containers via docker compose.
* feat: add addon JSON configs for dockge, komodo, dokploy, coolify
Recreate JSON configs with type=addon, script paths pointing to
tools/addon/*.sh, null resources (addon runs on existing Docker LXC),
and update instructions in notes.
* feat: add Runtipi addon + upgrade all addons with Proxmox host check, optional Docker install, Alpine support
- New: tools/addon/runtipi.sh with full Alpine support (gcompat for musl)
- New: tools/headers/runtipi ASCII header
- Updated: runtipi.json to addon type with null resources
- Removed: ct/runtipi.sh, install/runtipi-install.sh (migrated to addon)
- All addons (dockge, komodo, dokploy, coolify, runtipi) now have:
- check_proxmox_host(): warns when running on PVE host, default N
- check_or_install_docker(): optional Docker install (Debian+Alpine)
- Alpine-aware curl bootstrap and dependency installation
* readd ct, update information
* Create runtipi.sh
* refactor: remove inline header_info from addons, use core.func get_header()
- get_header() in core.func now maps APP_TYPE=addon to tools/headers/ path
- Removed 5 duplicate ASCII art header_info functions from addon scripts
- Addons now use the shared header_info() from core.func + tools/headers/ files
* chore(tools): add Github source links to dockge, komodo, dokploy, coolify, runtipi addons
* fix(runtipi): drop Alpine support; add OS compat notes to docker addon JSONs
Add apt_update_safe() function that warns instead of aborting when apt-get update fails (e.g. enterprise repo 401 Unauthorized). Shows a helpful hint about disabling the enterprise repo when no subscription is active. Replaces direct apt-get update calls in build.func and install.func.
Prevent terminal job-control signals from suspending the script during recovery by trapping TSTP, TTIN and TTOU (instead of only TSTP) and restoring them on exit. Also clear the terminal 'tostop' flag in stop_spinner() with `stty -tostop` to avoid background spinner I/O from stopping the process group.
After 'export INSTALL_LOG' in build.func, get_active_logfile() returned
the container's INSTALL_LOG path for all host-side logging, causing
msg_info/msg_ok/msg_error on the host to write to /root/.install-SESSION.log
(the host file, not the container's) instead of BUILD_LOG. This made
BUILD_LOG incomplete and get_full_log() unable to send full traces.
Fix: Add _HOST_LOGFILE (not exported, invisible to container) so the host
always logs to BUILD_LOG. Container still uses INSTALL_LOG as before.
Prevent host-side error_handler from being triggered during in-container install/recovery by delaying re-enabling set -Eeuo pipefail and the ERR trap in misc/build.func until after install/recovery completes; add explanatory comments. Update misc/error_handler.func to fall back to BUILD_LOG if container-internal log path is unavailable, show the last 20 log lines when present, refine container vs host detection (check INSTALL_LOG file and /root), copy INSTALL_LOG into /root and write a .failed flag with the exit code for host-side detection, and ensure full-log output and container removal prompt are shown appropriately in host context. Tweak misc/core.func silent() output to include a "Full log" path and adjust formatting.
Introduce post_progress_to_api() in misc/api.func — a non-blocking, fire-and-forget curl ping (gated by DIAGNOSTICS and RANDOM_UUID) that updates telemetry status to "configuring". Wire this progress ping into multiple scripts (alpine-install.func, install.func, build.func, core.func) at key milestones (container start, network ready, customization, creation, cleanup) and replace/deduplicate some earlier post_to_api calls. Also update error_handler.func to always report failures immediately via post_update_to_api to ensure failures are captured even before/after container lifecycle.
* fix(telemetry): improve error reporting with structured error strings and better categorization
- Add build_error_string() that creates structured format:
'exit_code=N | description\n---\n<last 20 log lines>'
- Fix categorize_error() to map ALL known exit codes:
- Added: shell(1,2), proxmox(200-231), service(150-154),
database(170-193), runtime(243-249), signal(139,141,143)
- Split timeout from network (28 was in both)
- Added DPKG(255) to dependency category
- Update all API functions to use build_error_string():
post_update_to_api, post_update_to_api_extended,
post_tool_to_api, post_addon_to_api
- Add ensure_log_on_host() calls to on_exit, on_interrupt,
on_terminate handlers to prevent race condition where
telemetry reports before container log is pulled to host
* fix(ui): improve error output formatting and remove redundant log paths
- error_handler: Use msg_info/msg_ok/msg_warn for container cleanup
instead of raw echo with manual ANSI codes
- error_handler: Add ❓ icon before 'Remove broken container?' prompt
- error_handler: Indent log output with TAB for visual consistency
- build.func: Use msg_custom for installation log path display
- build.func: Use msg_info → msg_ok for container removal flow
- build.func: Use msg_warn for 'kept for debugging' message
- core.func/vm-core.func: Remove redundant container-internal log
path display (📋 View full log) since combined log on host is
the canonical location shown after failure
Updated the cleanup_lxc function to directly remove cache directories for Python, Node.js, Go, Rust, Ruby, and PHP, instead of relying on package manager commands. Improved error handling to prevent cleanup failures from affecting installs, and clarified documentation to reflect safer, more targeted cache removal.
* fix(core): add IPv6 fallback support to get_current_ip functions
Fixes IP detection in IPv6-only environments by adding fallback:
- Try IPv4 first (existing behavior)
- Fall back to IPv6 via interface lookup (eth0 scope global)
- Fall back to IPv6 routing with Google/Cloudflare DNS targets
Closes #issue-ipv6-only-environment
* fix(build): use SSH_AUTHORIZED_KEY from user defaults when no SSH_KEYS_FILE exists
When using 'User Defaults' with var_ssh_authorized_key set in default.vars,
the SSH key was not being installed because install_ssh_keys_into_ct() only
checked for SSH_KEYS_FILE (which is only created in Advanced Settings).
Now the function also checks SSH_AUTHORIZED_KEY and creates a temporary
SSH_KEYS_FILE if needed.
Fixes#11062
The get_lxc_ip function now attempts to retrieve the IP address directly from eth0 before falling back to hostname -I. This improves reliability for LXC containers where eth0 is typically the primary interface.
Moved the get_lxc_ip call from automatic execution in load_functions to explicit calls in alpine-install.func and install.func, ensuring the LXC IP is retrieved only after the network is up inside the container. Updated comments to clarify usage.
* Rename import_local_ip to get_local_ip
Replaces all references to the helper function import_local_ip with get_local_ip across scripts and documentation for consistency. Updates usage examples and comments to reflect the new function name.
* Rename get_local_ip to get_lxc_ip and update usage
Replaces all references to get_local_ip with get_lxc_ip across scripts, documentation, and templates for clarity and consistency. Updates the implementation in core.func to improve IP detection for LXC containers, and adjusts helper functions in addon scripts accordingly.
Refactored various shell functions to add more robust error handling by redirecting stderr to /dev/null and using '|| true' to prevent script failures. Enhanced npm cache cleanup to remove both _cacache and _logs directories, and improved reliability of version and keyring extraction commands. These changes increase script resilience and prevent unnecessary errors from halting execution.
Replaced the if-statement for npm cache cleaning with a single command using '||' to fall back to manual cache removal if 'npm cache clean' fails. This streamlines the cleanup process.
Adds a fallback to manually remove the npm cache directory if 'npm cache clean --force' fails during cleanup. This ensures the cache is cleared even if the npm command encounters an error.
* fix(build): load app defaults before applying base_settings
App defaults were loaded after base_settings, causing saved values to be ignored.
Now loads var_* from app defaults file before calling base_settings.
* fix(cleanup): suppress composer root warning in cleanup_lxc
Composer's clear-cache command prompts for confirmation when run as root,
causing scripts to hang at 'Cleaning up' stage. Set COMPOSER_ALLOW_SUPERUSER=1
to suppress the interactive prompt.
Fixes#9952 (Heimdall Dashboard), also affects BentoPDF and other PHP apps.
* Fix COMPOSER_ALLOW_SUPERUSER export in cleanup_lxc
Exports COMPOSER_ALLOW_SUPERUSER before running composer clear-cache to ensure the environment variable is set correctly during cleanup.
* Refactor Core
Refactored misc/alpine-install.func to improve error handling, network checks, and MOTD setup. Added misc/alpine-tools.func and misc/error_handler.func for modular tool installation and error management. Enhanced misc/api.func with detailed exit code explanations and telemetry functions. Updated misc/core.func for better initialization, validation, and execution helpers. Removed misc/create_lxc.sh as part of cleanup.
* Delete config-file.func
* Update install.func
* Refactor stop_all_services function and variable names
Refactor service stopping logic and improve variable handling
* Refactor installation script and update copyright
Updated copyright information and adjusted package installation commands. Enhanced IPv6 disabling logic and improved container customization process.
* Update install.func
* Update license comment format in install.func
* Refactor IPv6 handling and enhance MOTD and SSH
Refactor IPv6 handling and update OS function. Enhance MOTD with additional details and configure SSH settings.
* big core refactor
* Enhance IPv6 configuration menu options
Updated IPv6 Address Management menu options for clarity and added a new option for fully disabling IPv6.
* Update default Node.js version to 24 LTS
* Update misc/alpine-tools.func
Co-authored-by: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com>
* indention
* remove debugf and duplicate codes
* Update whiptail backtitles and error codes
Removed '[dev]' from whiptail --backtitle strings for consistency. Refactored custom exit codes in build.func and error_handler.func: updated Proxmox error codes, shifted MySQL/MariaDB codes to 260-263, and removed unused MongoDB code. Updated error descriptions to match new codes.
* comments
* Refactor error handling and clean up debug comments
Standardized bash variable checks, removed unnecessary debug and commented code, and clarified error handling logic in container build and setup scripts. These changes improve code readability and maintainability without altering functional behavior.
* Update build.func
* feat: Improve LXC network checks and LINSTOR storage handling
Enhanced LXC container network setup to check for both IPv4 and IPv6 addresses, added connectivity (ping) tests, and provided troubleshooting tips on failure. Updated storage validation to support LINSTOR, including cluster connectivity checks and special handling for LINSTOR template storage.
---------
Co-authored-by: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com>
