⌘K

Updating Synaptik CMS

What it is

SynaptikCMS can update itself with one click from your admin panel. This page explains how that works, and how to do the same thing by hand when the one-click update isn't available or doesn't finish — for example on a host that blocks outgoing connections or doesn't have PHP's ZipArchive extension.

One-click update (the normal way)

When a new version is out, a notice appears on your Dashboard. Click Apply Update and SynaptikCMS does the rest:

  1. It creates two backups in the /bckps/ folder of your site: one with your content and settings, and one with the program files it is about to replace.
  2. It downloads the new release and checks that it really is a SynaptikCMS package.
  3. It copies the new program files over the old ones.

Your content, your settings, your uploaded files and your private data are never replaced by an update.

The update notice doesn't show up

SynaptikCMS checks for updates once a day and remembers the answer, so a release can take up to 24 hours to show up on a site that checked just before it came out. To check right away, go to Settings → General → Cache, click Clear admin cache, then go back to the Dashboard.

If the notice still doesn't appear, your host may be blocking outgoing requests to GitHub (SynaptikCMS needs either curl or allow_url_fopen to look for updates). In that case, use the manual update below.

When to update manually

  • The one-click update says it failed to download the package, or that ZipArchive isn't available.
  • The update stops partway and reports failed files, usually a file permission problem.
  • Your host can't reach the internet from PHP.

Before you start

  1. Make a backup. Open Tools → Backup & Restore, click Download Full Backup (.zip) and download the file to your own computer.
  2. Note your admin folder name. The admin panel lives in a folder you chose at installation. It is admin by default, but yours may have another name. You'll need it in step 4.
  3. Note your current version. It is shown at the bottom of the admin panel.

Updating by hand

  1. Download the latest release ZIP.
  2. Unzip it on your computer. The files sit at the root of the ZIP, with no wrapping folder.
  3. Leave these out. Do not upload any of the following, they hold your own site and must not be replaced:
Leave outWhy
data/Your content: articles, pages, projects, categories, tags
files/Your uploaded media
private/Your site's private data and secrets
config.jsonYour settings
install.php and install.lockInstaller files, only used once
cache/ and bckps/Cache and backups
theme/default/The one-click update doesn't touch it either

This is exactly the list the one-click update skips, so by doing the same you get the same result.

  1. Match your admin folder name. The ZIP contains the admin panel in a folder called admin. If your admin folder has another name, upload the contents of the ZIP's admin folder into your folder, not into a new admin folder. Leave your folder's cache subfolder alone.
  2. Upload and overwrite. Upload everything that is left (admin, assets, core, lang, theme, index.php, version.json, .htaccess, and so on) to your site's root with SFTP or your host's file manager, and choose to overwrite files that already exist. Merge into the existing folders; never delete a folder first, or you could lose content that lives next to the program files.
  3. Check your .htaccess. The release replaces the .htaccess at the root of your site. If you had added your own rules (Settings → Advanced), open that page and save the rules once more so they are written back into the new file. If your site runs on nginx, compare your configuration with the nginx.conf.example file included in the release.
  4. Clear the caches. Go to Settings → General → Cache and click both Clear Cache and Clear admin cache.
  5. Check the version. The bottom of the admin panel should now show the new version number. Open your site and a few pages to make sure everything displays correctly.

If something goes wrong

  • Restore your backup. Upload the full backup you downloaded on Tools → Backup & Restore.
  • Go back to the previous program files. If you used the one-click update first, /bckps/ also holds a pre-update-core-backup ZIP with the previous version of the program files.
  • Update partially failed, check file permissions. Your host didn't let SynaptikCMS write some files. Check that the site's folders are writable (usually permission 755 for folders and 644 for files) and try again, or do the manual update.

Themes and plugins

Themes and plugins are updated separately, from the Themes and Plugins pages of the admin panel. The core release contains no plugins and only the bundled themes, so updating the CMS never changes the ones you installed.