Function reference
Reference for the helper functions app scripts call from install/*.sh and ct/*.sh.
App scripts are short because the work is done by shared helpers in the core repository. This section documents those helpers one by one: what each does, its arguments, the environment variables it reads, what it returns, and a call taken from an existing script.
It is written for contributors who write or review install/<app>-install.sh and
ct/<app>.sh. If you only run scripts, you do not need it.
Pages
| Page | Covers | Source |
|---|---|---|
| Core | Messages, $STD and the other basics every script uses | core/core.func |
| Error handling | catch_errors and what happens when a command fails | core/error_handler.func |
| Releases and downloads | check_for_gh_release, fetch_and_deploy_gh_release and their GitLab, Codeberg, tag and branch variants; tokens and rate limits | lib/forge.func |
| System helpers | Downloads with retry, apt packages and repositories, services, backups, OS probes | lib/system.func |
| Runtimes | Language runtimes and application installers (setup_nodejs, setup_php, setup_uv, ...) | lib/runtime.func |
| Databases | Databases and search engines (setup_postgresql, setup_mariadb, ...) | lib/db.func |
| Hardware acceleration | GPU detection and setup_hwaccel | lib/hwaccel.func |
| Alpine helpers | The reduced helper set of Alpine install scripts | lib/alpine.func |
How helpers reach a script
Scripts never source the files in lib/ themselves. The engine does it at a fixed
point, and that point decides from where on a helper can be called.
In an install script
Every install script starts like this (from install/alpine-wakapi-install.sh,
the Debian ones are identical):
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
color
verb_ip6
catch_errors
setting_up_container
network_check
update_osFUNCTIONS_FILE_PATH holds lxc/install.func, the in-container runtime.
update_os updates the container and then sources the helper library:
lib/tools.func, or lib/alpine.func when the container's OS family is Alpine.
The helpers in this section therefore exist after update_os, not before.
If the library cannot be downloaded, or fetch_and_deploy_gh_release is not
defined after loading it, update_os stops the install with exit code 115.
In a ct script
start sources lib/tools.func as its first step, so the helpers are available
in update_script. This is the regular library on every distribution, Alpine
included; see Alpine helpers for what that means.
The loader
lib/tools.func
contains no helpers. It sources five parts, in this order:
| Part | Content |
|---|---|
lib/system.func | Packages, repositories, OS probes, services, temp files |
lib/forge.func | GitHub, GitLab and Codeberg releases, tags and branches |
lib/runtime.func | Language runtimes and application installers |
lib/db.func | Databases and search engines |
lib/hwaccel.func | GPU detection and hardware acceleration |
For each part it takes the first source that applies:
- On the host, the engine's own resolver, which honours a local checkout.
- The copy the container runtime fetched in advance, in the directory named by
COMMUNITY_SCRIPTS_CORE_DIR. - A download from
COMMUNITY_SCRIPTS_CORE_URL, which defaults tohttps://raw.githubusercontent.com/community-scripts/core/main.
The loader and every part guard against being sourced twice. Always load
lib/tools.func, never a part on its own: the parts call each other.
The inventory
lib/API.txt
lists every function lib/tools.func defines once loaded, one name per line (181
at the time of writing, internal ones included). A CI check in core compares the
file with what the loader really defines, so a function cannot be added, renamed
or dropped unnoticed. lib/alpine.func is not part of that list.
Naming conventions
The name tells you what kind of helper you are looking at.
| Pattern | Behaviour | Example |
|---|---|---|
setup_<tool> | Installs the tool, or brings an existing install to the requested version. Options are environment variables | setup_nodejs |
check_for_<forge>_<kind> | Returns 0 when upstream has something newer and sets CHECK_UPDATE_RELEASE. Used as an if condition | check_for_gh_release |
fetch_and_deploy_<forge>_<kind> | Downloads and puts in place, then records the version in ~/.<app> | fetch_and_deploy_gh_release |
get_<thing> | Prints a value on stdout, changes nothing | get_latest_github_release, get_os_info |
is_<state>, should_<action>, verify_<thing> | A test: the return status is the answer | is_package_installed |
ensure_<state> | Makes the state true, doing nothing when it already is | ensure_dependencies |
cleanup_<thing> | Removes leftovers | cleanup_old_repo_files |
_<name> | Internal. Not for scripts, can change without notice | _forge_release_json |
Forge abbreviations: gh is GitHub, gl is GitLab, codeberg is Codeberg.
Passing options
Positional arguments carry what every call needs (app name, repository, URL).
Optional behaviour is switched on with an environment variable set for that one
call, written in front of it on the same line. From ct/airtrail.sh:
CLEAN_INSTALL=1 CLEAN_INSTALL_KEEP="uploads" fetch_and_deploy_gh_release "airtrail" "johanohly/AirTrail" "tarball" "latest" "/opt/airtrail"Return codes
Helpers return 0 on success. On failure they print the reason with msg_error and
return a code that says what kind of failure it was. What happens when a script
does not check that code is described under
error handling. The codes used by the helpers on
the forge and system pages:
| Code | Meaning in these helpers |
|---|---|
| 6 | A host name does not resolve |
| 7 | Connection or download failed after all retries |
| 22 | A forge API answered with an error |
| 65 | A required argument is missing or has an unsupported value |
| 100 | apt or dpkg failed |
| 150 | A service did not start |
| 250 | Download failed, or no version could be determined |
| 251 | An archive or key could not be unpacked |
| 252 | Nothing usable in the download, or it could not be copied into place |
The full list of exit codes is on the exit codes page.