mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-04-23 10:50:41 +00:00
feat(core): harden runtime sourcing and simplify LXC update flow
This commit is contained in:
MickLesk
@@ -0,0 +1,202 @@
|
||||
# Core Runtime Sourcing Guide
|
||||
|
||||
This guide explains how runtime module loading works after the core hardening changes, and how to operate it safely in production.
|
||||
|
||||
## Why this exists
|
||||
|
||||
The runtime now uses a **local-first** loading strategy for core modules (`core.func`, `error_handler.func`, `tools.func`, `install.func`, `alpine-install.func`).
|
||||
|
||||
That means:
|
||||
|
||||
1. Try local files first (preferred, deterministic)
|
||||
2. Fall back to remote source only if local files are not available
|
||||
3. Allow pinning to a specific branch/tag/commit via environment variables
|
||||
|
||||
This reduces failures from transient network/CDN issues and improves deployment reproducibility.
|
||||
|
||||
---
|
||||
|
||||
## Default behavior (no config needed)
|
||||
|
||||
If you do nothing, scripts will:
|
||||
|
||||
- Use local `misc/*.func` files when available
|
||||
- Otherwise use GitHub raw URLs under `community-scripts/ProxmoxVE/main`
|
||||
|
||||
This is backward compatible with existing usage.
|
||||
|
||||
---
|
||||
|
||||
## Host vs LXC: where data is needed
|
||||
|
||||
Short answer: **for normal online operation, no full duplication is required**.
|
||||
|
||||
### If you only care about `update` inside the LXC
|
||||
|
||||
That is now the simplest path:
|
||||
|
||||
- Installer writes `/usr/local/community-scripts/runtime-source.env` inside the container
|
||||
- `/usr/bin/update` reads that file first
|
||||
- `update` therefore keeps using the container's pinned source settings by default
|
||||
|
||||
In other words, you can manage update source behavior entirely inside the LXC without requiring host-side duplication.
|
||||
|
||||
### Runtime split
|
||||
|
||||
- **Host side**
|
||||
- `misc/build.func` orchestrates creation and bootstrapping.
|
||||
- It provides bootstrap function payload for install scripts.
|
||||
|
||||
- **LXC side**
|
||||
- install scripts run inside the container.
|
||||
- They try local core modules first; if not present, they use remote fallback.
|
||||
|
||||
### Practical implications
|
||||
|
||||
1. **Online default mode**
|
||||
- Host local files + remote fallback inside LXC are enough.
|
||||
- No manual copy of all `misc/*.func` into the container is strictly required.
|
||||
|
||||
2. **Strict reproducible/offline mode**
|
||||
- You should provide the same module set on both sides:
|
||||
- host checkout (for orchestration)
|
||||
- local module files in LXC (for local-first resolution)
|
||||
- Otherwise LXC may use remote fallback and pick newer content than host-local branch state.
|
||||
|
||||
3. **Pinned mode (`COMMUNITY_SCRIPTS_REF`)**
|
||||
- Greatly reduces mismatch risk because all fallback URLs resolve to the same ref/tag/commit.
|
||||
|
||||
---
|
||||
|
||||
## Configuration knobs
|
||||
|
||||
You can control runtime source resolution with these environment variables.
|
||||
|
||||
### 1) `COMMUNITY_SCRIPTS_REF`
|
||||
|
||||
- Purpose: Select branch/tag/commit reference used for remote fallback
|
||||
- Default: `main`
|
||||
|
||||
Example values:
|
||||
|
||||
- `main`
|
||||
- `v2026.04`
|
||||
- `<commit-sha>`
|
||||
|
||||
### 2) `COMMUNITY_SCRIPTS_REMOTE_BASE`
|
||||
|
||||
- Purpose: Override remote base for `misc/*.func`
|
||||
- Default: `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/${COMMUNITY_SCRIPTS_REF}/misc`
|
||||
|
||||
### 3) `COMMUNITY_SCRIPTS_INSTALL_BASE`
|
||||
|
||||
- Purpose: Override remote base for `install/*.sh`
|
||||
- Default: `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/${COMMUNITY_SCRIPTS_REF}/install`
|
||||
|
||||
### 4) `COMMUNITY_SCRIPTS_CT_BASE`
|
||||
|
||||
- Purpose: Override remote base for `ct/*.sh` update launcher (`/usr/bin/update` inside CT)
|
||||
- Default: `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/${COMMUNITY_SCRIPTS_REF}/ct`
|
||||
|
||||
---
|
||||
|
||||
## Recommended operating modes
|
||||
|
||||
### Mode A: Standard users (recommended default)
|
||||
|
||||
- Do not set any variables
|
||||
- Local-first will automatically improve resilience
|
||||
|
||||
### Mode B: Release pinning (stable operations)
|
||||
|
||||
- Set `COMMUNITY_SCRIPTS_REF` to a known release tag
|
||||
- Keeps behavior reproducible across nodes and rebuilds
|
||||
|
||||
### Mode C: Controlled mirror / internal hosting
|
||||
|
||||
- Set `COMMUNITY_SCRIPTS_REMOTE_BASE`, `COMMUNITY_SCRIPTS_INSTALL_BASE`, `COMMUNITY_SCRIPTS_CT_BASE`
|
||||
- Useful for air-gapped or enterprise mirror setups
|
||||
|
||||
---
|
||||
|
||||
## What changed in runtime flow
|
||||
|
||||
### `misc/build.func`
|
||||
|
||||
- Core/API/tools/install payload loading now uses local-first helper resolution
|
||||
- Remote fallback is configurable via `COMMUNITY_SCRIPTS_*` variables
|
||||
- Upstream drift check warns if local code differs from latest `origin/main` (when using `COMMUNITY_SCRIPTS_REF=main`)
|
||||
|
||||
### `misc/install.func` and `misc/alpine-install.func`
|
||||
|
||||
- `core.func` and `error_handler.func` are loaded local-first
|
||||
- `tools.func` is loaded local-first with remote fallback and retries
|
||||
- `/usr/bin/update` now uses configurable `COMMUNITY_SCRIPTS_CT_BASE`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### How upstream changes are detected
|
||||
|
||||
When running from `main` (default), runtime checks for upstream drift:
|
||||
|
||||
1. **Git mode (preferred)**
|
||||
- If the script runs from a git worktree, it compares:
|
||||
- local `HEAD`
|
||||
- `origin/main` (`git ls-remote`)
|
||||
- If different, a warning is shown.
|
||||
|
||||
2. **API fallback (non-git environments)**
|
||||
- Reads latest `main` commit SHA from GitHub API
|
||||
- Compares it with a locally cached SHA (`/var/cache/community-scripts/upstream-main.sha`)
|
||||
- Warns when it changed since the previous run
|
||||
|
||||
> Note: drift check is advisory (warning only), not blocking.
|
||||
|
||||
### How to avoid stale variants
|
||||
|
||||
- **Best practice for production:**
|
||||
- Pin a known release/tag/commit via `COMMUNITY_SCRIPTS_REF`
|
||||
- **If following `main`:**
|
||||
- Update/sync local checkout regularly (fetch/rebase or merge)
|
||||
- Watch for drift warnings during installation flow
|
||||
|
||||
### Symptom: "Failed to load core.func" / "Failed to download tools.func"
|
||||
|
||||
Check:
|
||||
|
||||
1. Local files exist in one of the expected locations:
|
||||
- script directory (`$(dirname "${BASH_SOURCE[0]}")`)
|
||||
- `/opt/community-scripts/misc`
|
||||
- `/usr/local/share/community-scripts/misc`
|
||||
- `/usr/local/community-scripts/misc`
|
||||
2. Remote base URLs are reachable
|
||||
3. `COMMUNITY_SCRIPTS_REF` points to a valid branch/tag/commit
|
||||
|
||||
### Symptom: CT `update` script points to unexpected source
|
||||
|
||||
Check:
|
||||
|
||||
- `COMMUNITY_SCRIPTS_CT_BASE`
|
||||
- `COMMUNITY_SCRIPTS_REF`
|
||||
|
||||
---
|
||||
|
||||
## Security and reproducibility notes
|
||||
|
||||
- For production-grade reproducibility, prefer **pinning** (`COMMUNITY_SCRIPTS_REF` as tag/commit)
|
||||
- For highest control, use internal mirrors with explicit base URLs
|
||||
- Local-first loading reduces runtime dependence on external services
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
You now have a safer runtime model:
|
||||
|
||||
- **Resilient**: local-first
|
||||
- **Flexible**: configurable remote bases
|
||||
- **Reproducible**: ref pinning
|
||||
|
||||
Use defaults for simplicity, pin refs for stability, and override bases for enterprise/mirrored deployments.
|
||||
Reference in New Issue
Block a user