ProxMenux/web/messages/en/docs/monitor/dashboard/vms-lxcs-updates.json

{
  "meta": {
    "title": "Updates — updating an LXC's system and apps | ProxMenux",
    "description": "Which mechanisms ProxMenux can use to update the operating system and the applications registered in an LXC container."
  },
  "header": {
    "title": "Updates — updating an LXC's system and apps",
    "description": "Where ProxMenux decides how to upgrade a container: OS packages, Community Scripts helper, or a custom command."
  },
  "intro": {
    "p1": "The <strong>Updates</strong> tab gathers the mechanisms ProxMenux can run to upgrade the operating system and the applications registered inside an LXC container.",
    "p2": "The <link>App tab</link> declares which applications exist and, optionally, compares their versions. <strong>Updates</strong> is about the action: it decides which mechanism is available, presents the matching button and runs the upgrade inside the container.",
    "callout": "<strong>Core idea:</strong> detecting a new version and knowing how to install it are two different jobs. An app can show <strong>Update available</strong> on the App tab and still not have a working update button until a valid method is defined."
  },
  "mechanisms": {
    "heading": "Available update mechanisms",
    "intro": "Depending on how the app was installed and where its updates come from, ProxMenux picks from three mechanisms.",
    "osHeading": "Operating system packages",
    "osP1": "On Debian or Ubuntu containers, ProxMenux queries and updates packages through APT. On Alpine, it uses APK.",
    "osP2": "Registered apps whose install method is <code>dpkg</code> or <code>apk</code> are part of this pass. They don't need a second command in the app section — they update as part of <strong>Apply OS update</strong>.",
    "osP3": "The section shows the number of pending packages, how many are security updates, the OS family and the time of the last check.",
    "helperHeading": "Proxmox VE Helper-Scripts updater",
    "helperP1": "When the LXC was created with a helper from the <linkHelperHome>Proxmox VE Helper-Scripts</linkHelperHome> project, ProxMenux recognises its updater. The matching app must be registered on the App tab so the Monitor can associate the helper with the service shown to the user.",
    "helperP2": "<strong>The update logic itself is maintained by the Proxmox VE Helper-Scripts project</strong>, not by ProxMenux. Each helper ships its own <code>update_script</code> function; ProxMenux fetches it and runs it inside the container in silent mode (<code>PHS_SILENT=1</code>), without prompts. There is no need to copy the helper or write a custom command on the ProxMenux side.",
    "helperP3": "Full documentation for the update mechanism lives on the project site — <linkHelperDocs>community-scripts.org / update-apps</linkHelperDocs>. Each helper also has its own entry on the <linkHelperHome>project site</linkHelperHome> with a description of what the script does, its default configuration and the source of the update logic — use that page as the reference for what the updater will change inside the LXC.",
    "helperP4": "Not every helper supports in-place updates. If the catalog marks an application as non-upgradable, the tab will surface that state and won't present this method as available.",
    "customHeading": "Custom command",
    "customP1": "A registered app can store its own update command. ProxMenux runs it inside the LXC when the user presses <strong>Apply update</strong> or when a scheduled task includes that app.",
    "customP2": "This method is designed for apps whose installer provides no recognised helper and that don't update as part of APT or APK."
  },
  "decision": {
    "heading": "How ProxMenux picks the action to show",
    "table": {
      "colSituation": "Situation",
      "colAction": "Action",
      "rows": [
        { "situation": "APT or APK packages pending", "action": "Apply OS update" },
        { "situation": "The app uses a dpkg or apk package", "action": "Apply OS update — no separate app command needed" },
        { "situation": "A compatible helper exists and the app is registered", "action": "Apply update via Community Scripts" },
        { "situation": "The registered app has a custom command", "action": "Apply update using that command" },
        { "situation": "A new version exists but no helper or command is configured", "action": "Shows No updater configured; offers to add a command" },
        { "situation": "System and app updates are both available", "action": "Combined Apply OS + Apps updates action may appear" }
      ]
    },
    "trailing": "An app registered only as a link is never shown as upgradable — ProxMenux doesn't have enough information to wire an update method to it."
  },
  "figures": {
    "f01": {
      "alt": "OS packages card showing pending updates count, security-updates count and the Apply OS update button",
      "caption": "Pending OS packages: total count, security-updates count, and the Apply OS update button"
    },
    "f02": {
      "alt": "Same OS packages card after applying updates — no packages pending, OS up to date badge",
      "caption": "After applying: 'No OS updates pending' and the OS up to date badge"
    },
    "f03": {
      "alt": "Registered app card showing 'No update method available' and an Add custom update command button",
      "caption": "'No update method available' — ProxMenux tracks the app but has nothing wired to upgrade it yet"
    },
    "f04": {
      "alt": "Custom update command editor with the example placeholder visible inside the textarea",
      "caption": "The custom command editor with its placeholder example, Cancel and Save buttons"
    },
    "f05": {
      "alt": "Terminal panel labelled 'Apply updates — CT 103' showing live apt output as packages are unpacked",
      "caption": "Terminal panel streaming the update output live while apt unpacks packages inside the CT"
    },
    "f06": {
      "alt": "Options card with snapshot before applying enabled, backup storage set to pbs, and restart after applying enabled",
      "caption": "Options card with vzdump snapshot, backup storage and restart-after-applying enabled together"
    },
    "f07": {
      "alt": "Scheduled updates section enabled — Frequency set to Daily at 3:00, cron expression 0 3 * * *, and What to update set to OS + application",
      "caption": "Scheduled updates enabled — frequency preset, matching cron expression and target scope selected"
    }
  },
  "custom": {
    "heading": "Adding a custom update command",
    "p1": "When an app has version tracking but no update method, the tab shows <strong>No updater configured</strong>. Press <strong>Add custom update command</strong> to open the editor.",
    "p2": "The command must represent the real, complete procedure that upgrades that app. Don't just paste the command that reads its version."
  },
  "figureOut": {
    "heading": "How to figure out the correct command",
    "intro": "There is no universal update command. Before saving one, identify how the software was installed and what the project's recommended upgrade path is.",
    "step1Heading": "1. Check whether the system already handles it",
    "step1P1": "If the app was installed from Debian, Ubuntu or Alpine repositories it usually upgrades with system packages. In that case don't add a custom command — use <strong>Apply OS update</strong>.",
    "step1P2": "You can check the package origin from the LXC console with the distro's tooling. For example:",
    "step1Cmd1": "dpkg -l | grep -i name",
    "step1P3": "or:",
    "step1Cmd2": "apk info | grep -i name",
    "step1P4": "Replace <code>name</code> with the package you are investigating. A match doesn't automatically confirm it's the main package — cross-check the name against the app's documentation.",
    "step2Heading": "2. Consult the official documentation",
    "step2P1": "Look in the official docs or repository for sections like <strong>Upgrade</strong>, <strong>Update</strong>, <strong>Maintenance</strong> or <strong>Manual installation</strong>. The procedure must match the method used to install the app in that LXC.",
    "step2P2": "Don't use instructions targeting a different distribution, a different install type or a different version.",
    "step3Heading": "3. Inspect the existing installation",
    "step3Lead": "If you don't remember how the app was installed, look at:",
    "step3Items": [
      "The history or notes of the original installer.",
      "The path where its files live.",
      "The service definition that starts it.",
      "Any maintenance scripts shipped by the app.",
      "The documentation stored inside its install directory."
    ],
    "step3P1": "For a systemd service, this can help locate the binary and its working directory:",
    "step3Cmd": "systemctl show service-name -p ExecStart -p WorkingDirectory",
    "step3P2": "This helps identify the installation, but it does not automatically translate the <code>ExecStart</code> line into an update command.",
    "step4Heading": "4. Test the procedure in the LXC console",
    "step4Lead": "Open a console into the container and run the procedure manually before saving it in ProxMenux. Verify that it:",
    "step4Items": [
      "Finishes without prompts or interactive menus.",
      "Returns a correct exit code.",
      "Restarts or reloads only the services that need it.",
      "Leaves the app reachable afterwards.",
      "Changes the installed version as expected."
    ],
    "step4Note": "When feasible, take a container backup before testing.",
    "step5Heading": "5. Save only the in-container command",
    "step5P1": "Enter only what would be executed inside the LXC. Don't include:",
    "step5Cmd1": "pct exec <vmid> --",
    "step5P2": "ProxMenux already handles entering the container. The command runs as <code>root</code> via <code>sh -c</code>, so it accepts chained operations and directory changes.",
    "step5P3": "If the updater must run from a specific path, include it explicitly:",
    "step5Cmd2": "cd /opt/my-app && ./update.sh",
    "step5P4": "If the project ships an updater at a different path, use the path and arguments named by the official documentation."
  },
  "requirements": {
    "heading": "Requirements for a reliable command",
    "lead": "Before running it from the Monitor, confirm the command:",
    "items": [
      "Runs without user interaction.",
      "Uses absolute paths or changes into the correct directory first.",
      "Stops, migrates and restarts services as required by the official instructions.",
      "Exits with an error when the update fails.",
      "Does not contain visible passwords, tokens or other secrets.",
      "Does not download or execute scripts from untrusted sources."
    ],
    "trailing": "The content is stored in the LXC's configuration and executed with administrator privileges. Treat it with the same care as any command run as <code>root</code>."
  },
  "difference": {
    "heading": "Difference between the detection command and the update command",
    "lead": "Both fields have different goals:",
    "table": {
      "colField": "Field",
      "colLocation": "Location",
      "colRole": "Role",
      "rows": [
        {
          "field": "Command for the installed version",
          "location": "App → advanced tracking",
          "role": "Reads and returns the current version; executed as an argument list without a shell."
        },
        {
          "field": "Custom update command",
          "location": "Updates",
          "role": "Runs the upgrade procedure; interpreted via sh -c."
        }
      ]
    },
    "trailing": "Don't blindly copy the value of one into the other. A command like <code>myapp --version</code> may correctly detect the version but won't install a new one."
  },
  "apply": {
    "heading": "Applying an update",
    "lead": "Before pressing an apply button:",
    "steps": [
      "Confirm what will be updated: system, one app or both.",
      "Check the backup and restart options.",
      "Press the matching button.",
      "Follow the process output in the terminal panel.",
      "Verify the final result and that the service responds again."
    ],
    "trailing1": "If the LXC is stopped, ProxMenux starts it to run the process. If the update finishes correctly and the restart option is enabled, the container is restarted at the end.",
    "systemLead": "On a system update:",
    "systemItems": [
      "Debian and Ubuntu run the upgrade via APT.",
      "Alpine runs it via APK."
    ],
    "appLead": "On an app update:",
    "appItems": [
      "The compatible helper is used, when it exists.",
      "The custom command stored for the app is executed, when configured.",
      "If several apps are selected, their methods run in sequence."
    ],
    "trailing2": "The terminal panel shows progress and ends with a successful result or the process's error code."
  },
  "backup": {
    "heading": "Backup before updating",
    "p1": "Enable <strong>Snapshot the container before applying</strong> to create a <code>vzdump</code> backup before touching the LXC. You can also choose the target storage.",
    "p2": "If the backup is requested and it fails, ProxMenux won't continue with the update. This prevents changes from starting without the requested recovery point.",
    "p3": "This option applies to both manual runs and scheduled runs."
  },
  "restart": {
    "heading": "Restart after updating",
    "p1": "<strong>Restart the container after applying</strong> is a preference, not a signal that the restart is mandatory. Enable it when the app's procedure or the installed packages require it.",
    "p2": "The restart only happens after a successful run. If the update fails, the container stays up so the error can be inspected.",
    "p3": "The backup and restart options are saved for that LXC and also apply to its scheduled tasks."
  },
  "scheduled": {
    "heading": "Scheduled updates",
    "p1": "The <strong>Scheduled updates</strong> section runs automatically the same flow the manual buttons use.",
    "createLead": "To create a schedule:",
    "createSteps": [
      "Open <strong>Options</strong> and press <strong>Edit</strong>.",
      "Enable <strong>Scheduled updates</strong>.",
      "Choose a preset frequency or enter a cron expression.",
      "Select what will be updated: system packages only, applications only, or system and applications.",
      "Review the backup and restart options.",
      "Save the configuration."
    ],
    "p2": "The card shows whether the schedule is active, what it covers and the outcome of the last run. A disabled schedule can be kept for later re-activation, or removed entirely.",
    "p3": "If ProxMenux detects an external schedule created by Community Scripts on the host, it surfaces it so the user knows another automation is already in place.",
    "callout": "Before scheduling app updates, test every helper or command manually. A scheduled task can't answer prompts or fix an incomplete procedure."
  },
  "verify": {
    "heading": "Checking the result",
    "p1": "After applying system packages, ProxMenux forces a fresh check to update the pending-package counter without waiting for the next periodic cycle.",
    "p2": "For an app, go back to the <link>App tab</link> and press <strong>Check</strong> if the version number doesn't refresh immediately. This runs the configured installed-version method again and queries the upstream source.",
    "p3": "Confirm additionally that the app's web links respond correctly. A command finishing without errors is not a substitute for functional verification of the service."
  },
  "troubleshoot": {
    "heading": "Common problems",
    "noButtonHeading": "Update available appears, but there's no Apply update button",
    "noButtonBody": "Version detection works, but no method to install the update was found. Check whether the app updates via system packages, a compatible helper or a custom command.",
    "aptHeading": "The app updates through APT or APK",
    "aptBody": "Use <strong>Apply OS update</strong>. Don't add a second command for the same operation — the app is already part of the system update.",
    "noUpdaterHeading": "No updater configured is shown",
    "noUpdaterBody": "ProxMenux tracks the app but doesn't know how to update it. Check its official documentation, test the procedure in the console and, if appropriate, save it via <strong>Add custom update command</strong>.",
    "helperDetectedHeading": "The helper is detected but can't be used",
    "helperDetectedBody": "The helper may be marked as non-upgradable or fall outside the recognised methods. Follow the app's official instructions and don't assume every LXC built with Community Scripts supports automatic updates.",
    "customFailsHeading": "The custom command fails",
    "customFailsBody": "Re-run it in the LXC console. Check the working path, permissions, dependencies, non-interactive arguments and exit code. Don't swap the command for a different variant until you've verified the recommended procedure with the project."
  }
}