This project is under very early, active development and may contain bugs or security issues. It is likely not ready for production websites.

You are responsible for reviewing, testing, and securing any deployment. Ava CMS is provided as free, open-source software without warranty (GNU General Public License), see LICENSE.

Updating

Keeping Ava CMS up to date is easy. We release updates regularly with new features and bug fixes.

Always ensure you have a good backup before updating. Ava CMS is in early, active development. The updater is designed to be safe and reliable, but its behaviour may change between releases and edge cases may exist. See Backup Strategies below.

How to Update

The easiest way is using the CLI:

# 1. Check for updates
./ava update:check

# 2. Apply the update
./ava update:apply

# 3. Detect stale files left from older releases
./ava update:stale

By default, the CLI will ask you to confirm you have a backup before proceeding.

Under the hood, Ava CMS downloads an update ZIP from GitHub, extracts it into storage/tmp/, then copies a curated set of files into your install.

Requirements: Updates require the PHP ZipArchive extension. If it is missing, update:apply will fail.

CLI Commands

Command Description
./ava update:check Check for available updates (cached 1 hour, use --force to refresh)
./ava update:check --dev Shortcut for update:apply --dev
./ava update:apply Download and apply the latest release
./ava update:apply --dev Update from latest commit on main branch (bypasses version check)
./ava update:apply --yes Skip confirmation prompt
./ava update:stale Scan for stale files left from older versions
./ava update:stale --dev Compare against latest main commit instead of latest release
./ava update:stale --clean Remove detected stale files (prompts for confirmation)
./ava update:stale --clean --yes Remove stale files without confirmation

Shortcut: ./ava update is an alias for update:check.

What Gets Updated

Path Type Notes
core/ Directory Fully deleted and replaced (clean sync)
public/index.php File Application entry point (front controller)
public/.htaccess File Apache rewrite rules for public/
ava File CLI executable
bootstrap.php File Autoloader and boot sequence
composer.json File PHP dependencies
composer.lock File Locked dependency versions
index.php File Root misconfiguration detector
.htaccess File Root protection rules
nginx.conf.example File Nginx configuration reference
app/plugins/sitemap/ Directory Bundled plugin (clean sync)
app/plugins/feed/ Directory Bundled plugin (clean sync)
app/plugins/redirects/ Directory Bundled plugin (clean sync)

Directories use clean sync — the existing directory is fully deleted before copying the new version. This ensures stale files from previous versions are removed.

What Is Never Touched

Path Description
content/ All content files
app/config/ Site configuration
app/themes/ Theme files
app/snippets/ PHP snippets
storage/ Cache, logs, temp files
vendor/ Composer dependencies (updated separately via composer install)
public/robots.txt Search engine rules
public/media/ Uploaded media
.git/ Git repository data
.env Environment variables
Custom plugins Any plugin not in the bundled list

Update Flow

  1. Path safety check — If themes, plugins, or snippets paths differ from defaults, auto-update is blocked entirely. Users are shown manual update instructions instead.
  2. Version check — Fetches latest release from GitHub API (avacms/ava). Cached for 1 hour. Dev mode skips this and pulls the main branch.
  3. Confirmation — Shows exactly what will and won't be replaced. Asks for backup confirmation. Skippable with --yes/-y.
  4. Download & extract — Downloads the GitHub zipball to storage/tmp/, extracts it. Includes ZIP slip protection.
  5. Apply updates — Syncs files and directories per the tables above.
  6. New plugin detection — If the release includes new bundled plugins not in your install, they're copied and you're told to add them to ava.php.
  7. Post-update steps (automatic):
    • Finalize — removes known stale directories from older versions (e.g., core/Admin, core/Fields)
    • Composer install — runs composer install --no-dev to install updated dependencies
    • Rebuild — rebuilds the content index and clears the webpage cache
  8. Cleanup — Temp files removed, update cache cleared.

The post-update steps spawn separate PHP processes to ensure the newly updated code is loaded. If composer install fails, a warning is shown telling you to run it manually.

Manual Updates

If you prefer not to use the built-in updater:

  1. Download the latest release from GitHub
  2. Extract and copy the files listed in "What Gets Updated" into your install
  3. Run composer install --no-dev to install dependencies
  4. Run ./ava rebuild to rebuild the content index

Stale File Detection

./ava update:stale downloads the target release/commit and compares its file list against the local installation for all updatable paths. Any local files that don't exist in the release are reported as stale. --clean removes them (with confirmation unless --yes is passed).

Note: Most stale files within core/ are automatically cleaned up during updates (the updater fully replaces directories). This command is mainly useful for catching stale files in bundled plugins or edge cases.

Custom Paths (Blocked)

If any of these settings differ from their defaults, auto-update is blocked:

Setting Default
paths.themes app/themes
paths.plugins app/plugins
paths.snippets app/snippets

Manual update instructions are displayed instead.

Version Numbers

Ava CMS uses Calendar Versioning (CalVer): YY.M.PATCH (e.g., 26.4.1 is the first release of April 2026). Check release notes for details.

Dev Mode

--dev pulls the latest commit from the main branch instead of a tagged release. Version checks are bypassed. The version string becomes {current}-dev.{shortsha}. Intended for development and testing only — may include unstable or incomplete changes.

Never use --dev for production sites or fresh installs. The main branch may contain incomplete or untested work. For new installations, always download from GitHub Releases.

Backup Strategies

Because Ava CMS is a flat-file CMS, backing up is incredibly simple. You don't need to dump databases or export complex configurations. You just need to copy files.

What Should I Back Up?

What Should I Back Up?

The most important folders to back up are:

  • content/ — Your markdown content, taxonomies and structure
  • app/ — Your sites custom code (config, themes, plugins, snippets)
  • public/ — Any custom files you added here (like media files, robots.txt)

Most other things (like core/, vendor/, storage/cache/) can be regenerated or re-downloaded.

The 3-2-1 Rule

For important data, consider the 3-2-1 Backup Rule:

  • 3 Copies: Your live site plus at least two backups
  • 2 Different Places: Store them on different types of storage (e.g., cloud + local)
  • 1 Off-Site: Keep at least one copy somewhere other than your server

Here are some backup approaches, from simplest to most automated.

1. Download a Copy (Simple)

Just download your files and keep them safe somewhere.

How:

  • Use SFTP to download your site folder
  • Or use your host's file manager to create and download a ZIP
  • Or via command line: zip -r backup-$(date +%Y-%m-%d).zip .

Pros: Quick, works anywhere, no setup required.
Cons: Manual effort, easy to forget, stored on same server until you download it.

2. Git Repository

If you're already using Git, your remote repository (GitHub, GitLab, etc.) is a natural backup.

How: Commit your changes and push to a remote repository.

git add .
git commit -m "Backup before update"
git push origin main

Pros: Automatic history of every change, off-site storage, easy to roll back.
Cons: Requires Git knowledge, you need to remember to commit and push.

3. Cloud Sync (Set and Forget)

For production sites, consider automated sync to cloud storage.

Options:

  • Use tools like rclone or rsync to sync folders
  • Many hosts offer automated backups (check your control panel)
  • Cloud services like Dropbox, Google Drive, or S3 can sync automatically

Example with rclone:

rclone sync ./content remote:my-ava-backups/content
rclone sync ./app remote:my-ava-backups/app

Pros: Automatic, protects against server failure. Cons: Requires initial setup, may have small storage costs.

Which Should I Choose?

Approach Best For
Download a copy Occasional backups, before updates
Git repository Developers, version tracking, collaboration
Cloud sync Production sites, automated protection

Many people combine approaches—Git for development history, plus periodic manual downloads before big changes.

Troubleshooting

"Could not fetch release info from GitHub"

  • Check your internet connection
  • GitHub API may be rate-limited (60 requests/hour for unauthenticated)
  • Try again in a few minutes

Update fails mid-way

If an update fails partway through:

  1. Restore from your backup (this is why backups are essential!)
  2. Or try running the update again
  3. Or do a manual update

Your content and configuration are in separate directories from core files, so they're less likely to be affected—but with any file operations, there's always some risk.

After updating, site shows errors

  1. Run composer install to update dependencies
  2. Run ./ava rebuild to rebuild the content index
  3. Check the changelog for breaking changes

After updating, custom files are missing

  1. If you modified core files (not recommended), your changes may have been overwritten. Restore from backup.
  2. Custom themes, plugins and custom files in the public folder should be unaffected, but always double-check. Set-ups can be inconsistent across different sites and servers and the updater may not cover every edge case.
  3. Restore from backup if necessary.

Need Help?

Updates not working? Something broken? Join the GitHub Discussions—we're happy to help troubleshoot and get you back on track.

Related Documentation

Submit an issue or question about this page on GitHub