# Upgrading

Updates are separated into two categories, panel and system.

# Panel updates

ApisCP follows semantic versioning beginning with 3.0.0. Versions are split into 3 categories delimited by a period numerically ascending.

  • Major is the leading number (3). Major versions are guaranteed to introduce significant changes that may require rework to third-party modules that use ApisCP. Major changes should be deployed with caution on any environment.
  • Minor is the second number (0). Minor versions may introduce minor API changes or new services, however will not break anything in a meaningful way. Minor changes are considered safe for most environments.
  • Patch is the final number (0). Patch versions introduce non-destructive additions or bugfixes and are considered safe to always apply.

ApisCP is configured to deploy patch and minor updates on update. This is controlled with cp.update-policy Scope. Possible values include:

  • all: always apply official updates
    Example: ✔️ 3.1.1 => 3.1.2, ✔️ 3.1.10 => 3.2.0, ✔️ 4.3.99 => 5.0.0, ❌ 3fcae012 => cefa3210
  • major: apply official updates if major version does not change
    Example: ✔️ 3.1.1 => 3.1.2, ✔️ 3.1.10 => 3.2.0, ❌ 4.3.99 => 5.0.0
  • minor: apply official updates if minor version does not change
    Example: ✔️ 3.1.1 => 3.1.2, 3.1.10 =>❌ 3.2.0
  • false: never apply updates
    Example: ❌ 3.1.1 => 3.1.2
  • edge: always apply updates, official or experimental
    Example: ✔️ 3.1.1 => 3.1.2, ✔️ 3.1.10 => 3.2.0, ✔️ 4.3.99 => 5.0.0, ✔️ 3fcae012 => cefa3210

Updates are checked automatically every night. This behavior can be changed via cp.nightly-updates Scope.

Set the update policy to "edge" to help test new features. "edge" deploys code that is published to Gitlab before a formal release tag is defined for a commit.

For example, to disable update checks, but deploy the latest code on manual update via upcp:

cpcmd scope:set cp.update-policy edge
cpcmd scope:set cp.nightly-updates false

# Switching to EDGE

An EDGE update policy ensures you are the latest commit, which may contain untested/experimental code. You may be asked to switch to EDGE to validate a fix before the next public release. Switching may be done using a Scope + upcp:

cpcmd scope:set cp.update-policy edge

ApisCP will automatically merge new changes and restart itself. To switch back, reset the update policy ("major" is default), then reset the code.

cpcmd scope:set cp.update-policy major
upcp --reset
systemctl restart apiscp


upcp --reset is useful if you make changes to the panel code while debugging a problem. --reset will always return the panel code to its original state.

# upcp update helper

upcp is an alias to build/upcp.sh distributed as part of ApisCP. upcp checks for releases off Gitlab and deploys consistent with your update policy. A variety of flags can influence how upcp operates. With the exception of --reset, they may be mixed.

Flag Purpose
-n Skip migrations that automatically run after update
-b Run Bootstrapper reporting only changes
-s Skip updating code (e.g. upcp -sb, Bootstrap without updating panel)
-a Run Bootstrapper if the latest release contains changes to playbook
--reset Reset panel code, including all changes, to match Gitlab
--flare Check for FLARE signal. Exit status 0 if received, 1 if none available

-b accepts a list of roles to run as well. For example, a common task after making changes to apnscp-vars.yml is to process the affected roles. upcp -sb mail/rspamd mail/configure-postfix runs only the rspamd + configure-postfix subroles within mail.

# FLARE Updates

FLARE is a separate update system for ApisCP that performs hourly checks for critical releases. FLARE is automatically enabled whenever nightly updates are enabled (cpcmd scope:get cp.nightly-updates). This feature is a crucial side-channel to allow emergency updates should the need arise (new OS update introduces volatile changes, zero day mitigation, etc). FLARE checks are handled via apnscp-flare-check timer and its eponymous oneshot service.

systemctl list-timers apnscp-flare-check.timer
# Outputs:
# Sun 2020-02-23 14:36:50 EST  22min left Sun 2020-02-23 14:00:18 EST  14min ago apnscp-flare-check.timer apnscp-flare-check.service
# 1 timers listed.

# System updates

System updates are delivered via Yum. It is recommended to NOT alter this default. Failing appropriate judgment, this may be changed via system.update-policy Scope,

cpcmd scope:set system.update-policy security-severity

If system updates are disabled, then they may be applied from the command-line via yum update. The default setting, default, always applies system updates when available and applies any filesystem replication as needed.

# Manual FST updates

Filesystem template ("FST") updates are managed by Yum Synchronizer, which is invoked as a yum postaction on update/install. Yum Synchronizer usage is covered in depth in Filesystem.md.