Backups and updates

CoreInto backs up its own database every day and can update itself from the licence server. Settings > Database Backups makes, lists, downloads and deletes backups; the automation task backup makes one a day and removes old ones. Utilities > Update CoreInto asks the licence server which releases this site's licence key may have, installs a release that was signed with CoreInto's release key, and hands over to the Database Update page for the database changes that come with it. Updates can also be installed by hand by uploading files. The last section is for the owner who publishes releases, with the tools/release.php command.

Database backups

What a backup is

A backup is a copy of the whole database as an SQL file: every table, its structure (CREATE TABLE) and all its rows (INSERT statements, 200 rows per statement). It is written by PHP alone, so it works on shared hosting without mysqldump or shell access. Rows are read one at a time, so a large database does not need much memory. Binary columns are written as hexadecimal, so the file stays plain text. When PHP has the zlib extension the file is compressed with gzip and ends in .sql.gz; otherwise it ends in .sql and the page says so under "Format".

The file is named coreinto-YYYYMMDD-HHMMSS-xxxxxxxx.sql.gz (UTC time and eight random characters) and starts with a comment giving the CoreInto version and the time. It is written to storage/backups inside the CoreInto folder. The folder is made on first use with an .htaccess that denies web access and an empty index.html; the storage folder is closed to the web anyway. The file is written as .part first and renamed when complete, so a half-written backup is never listed.

A backup holds the stored secrets (server passwords, gateway keys, card tokens, the licence signing key, and so on) as they are in the database: encrypted with the key in configuration.php. Without that file a restored database works, but none of those secrets can be opened. Keep a copy of configuration.php with your backups.

What a backup does not hold: the files under storage/ (ticket attachments, client files, downloads, invoice PDFs, logs, earlier backups) and the CoreInto code. Back those up with your hosting account's file backup.

Settings > Database Backups

The page needs the permission "Database backups" (settings.backups). It shows:

Downloading sends the file as it is; the activity log records "Downloaded the database backup FILE". Deleting records "Deleted the database backup FILE". File names are checked against the fixed pattern, so the page can only reach files in storage/backups that CoreInto made.

The daily task and how long backups are kept

The task is seeded turned on. Like every task it can be turned off, turned on and run at once from Utilities > Automation Status, where it is listed under its name backup; see Automation for how tasks run.

Backups made with "Back up now" count like any other and are pruned by the same rule. To keep one for longer, download it.

Restoring a backup

A backup is restored into an empty database, then CoreInto's configuration.php is pointed at it.

1. Make an empty database in your hosting control panel, or empty the current one. The backup file begins by dropping and re-creating each table, so an existing database is overwritten table by table.
2. Import the file. In phpMyAdmin: choose the database, open Import and pick the file; .sql.gz files are accepted as they are. On a server with SSH, with the mysql client:

gunzip < coreinto-20261009-040002-1a2b3c4d.sql.gz | mysql -u USER -p DATABASE

For an uncompressed file:

mysql -u USER -p DATABASE < coreinto-20261009-040002-1a2b3c4d.sql

1. Put back the configuration.php that belongs to this installation (the one with the same encryption key), and check that it names the database you imported into.

The file sets FOREIGN_KEY_CHECKS off while it loads and on again at the end, and runs in the UTC time zone, so it can be loaded in any order of tables. If the backup is from an older version of CoreInto than the files now installed, the admin area then shows the Database Update page to bring the restored database up to date (see below).

Updating CoreInto

Where updates come from

Updates come from the licence server, https://system.coreinto.com, for this site's CoreInto licence key (see CoreInto licence). The site sends its key, the product coreinto, its domain and install folder, the channel (stable or beta) and its own version to /license/v2/releases; the licence server answers with the releases newer than that version, each with its version, release date, size, SHA-256, notes, a signature and a download link that works for 15 minutes.

The signature is made by the owner of CoreInto with CoreInto's release key (ECDSA P-256 with SHA-256 over the text cil-release-v1, coreinto, the version, the SHA-256 and the size, one per line). Only the public half of that key is in CoreInto (key id tQNDa-v9WzM1v8u6, built into app/src/Licence/Licence.php); the private half never leaves the owner's computer. A release whose signature does not check against that key is left out, so neither the licence server nor anyone between it and your site can make your site install anything the owner did not sign.

No update is offered or installed while the site's licence is restricted.

Utilities > Update CoreInto

The page needs the permission "Update CoreInto" (system.update). It shows:

While the licence is restricted a red line at the top says "Updates are not offered while this site's CoreInto licence is not in order." with the reason and a button to the licence page.

A warning at the top, "New files are in place and the database needs changes", with a link to the Database Update page, appears when files newer than the database are installed.

Checking says "CoreInto X.Y.Z is available." or "CoreInto X.Y.Z is the newest version.", and adds "N releases were not signed with CoreInto's release key and were left out." when the list had releases it rejected (badly formed, larger than 200 MB, or wrongly signed). Errors: no licence key entered yet; the licence server could not be reached or answered with an HTTP error; the licence server does not offer updates to this licence (with its reason, for example a suspended licence); the licence is restricted. The newest signed release newer than this copy is remembered without its download link (settings UpdateLatest and UpdateCheckedAt) and shown until it is installed or a newer one appears.

When a release is available, a card "CoreInto X.Y.Z is available" shows the release date, the size, the release notes, a sentence explaining what installing does, a confirmation box "Install it now" and the button "Install CoreInto X.Y.Z". Without the tick the page refuses with "Tick the box to confirm the update." If PHP has no zip extension the card says the update cannot be installed from this page and to upload the files instead.

What Install does

In this order; if any step fails, the page shows why and (up to the point files are written) nothing has changed:

1. Refuses while the licence is restricted, and checks that the release is well formed and that its signature checks against CoreInto's release key.
2. Asks the licence server again for a fresh download link for exactly that release (same version, size and SHA-256); if it is no longer offered: "The licence server no longer offers this release; check for updates again." The link must be on the licence server's own address ("The download link is not on the licence server; nothing was changed.").
3. Makes storage/updates (closed to the web) if it is missing.
4. Downloads the zip (up to 300 seconds; redirects are not followed). The download must be exactly the signed size and have exactly the signed SHA-256; otherwise "The downloaded file does not match the signed release (size or SHA-256); nothing was changed." After it is saved, its SHA-256 is checked once more on disk.
5. Opens the zip and reads its list. Every path must start with coreinto/ and contain no .. or backslashes, and the zip must contain coreinto/app/bootstrap.php, or it is refused as not a CoreInto release.
6. Leaves out the paths that are never written: configuration.php, everything under storage/, everything under .git/, and everything under install/ when the install folder has already been removed from your site (a removed installer stays removed).
7. Checks that the web server can write to every folder it will write into. If not: "The web server cannot write to PATH; nothing was changed. Upload the files by hand, or make the folder writable."
8. Makes a database backup, the same as "Back up now".
9. Puts a copy of every file about to be replaced into storage/updates/before-OLDVERSION-YYYYMMDD-HHMMSS.zip.
10. Writes each new file beside its place as NAME.new and moves it over the old one, making folders as needed. If a file cannot be written the update stops part way and the message names the zip in storage/updates that holds the replaced files.
11. Removes the downloaded zip, clears PHP's opcode cache when that is possible, and forgets the remembered release.

The activity log records "Installed CoreInto X.Y.Z: N files; database backup FILE; replaced files kept in storage/updates/ZIP", and the page says the same. You are then sent to the Database Update page. When the release has no database changes, that page says "The database is up to date." and offers the Dashboard.

To undo an update by hand, unpack the before-...zip from storage/updates over the CoreInto folder; database changes already applied are not undone by that, so restore the backup that was made in step 8 as well if the database was changed.

The task update-check

The task is listed under its name on Utilities > Automation Status. The result is visible there and as "Last checked" on Update CoreInto.

The Database Update page (/upgrade)

Database changes come as numbered files in app/migrations/ (for example 0011_updates.sql); each is applied once and recorded in the table schema_migrations. Whenever the files on disk hold a change the database has not had, CoreInto is "updating":

• Every page of the admin area sends signed-in staff to Database Update (the address is /upgrade; /update works too, but some hosting firewalls refuse addresses with "update" in them). Only sign-out and that page itself work.
• The client area and the public pages answer HTTP 503 "This site is being updated. Please try again in a few minutes." with a Retry-After of ten minutes.
• cron.php does nothing until the database is updated (with -v it prints "waiting: a database update is pending").

The page lists the pending changes by file name. A staff member with the permission "Update CoreInto" sees a warning to take a database backup first, and the button "Update the Database", which asks "Have you taken a database backup? Apply the update now?" before running. Everyone else sees "An administrator with the "Update CoreInto" permission must apply it."

Applying takes a database lock (so two staff members cannot run it at once), applies each pending file in order, and records it. On success the activity log gets "Updated the database to CoreInto VERSION: 0011_updates, ..." and you return to the dashboard with "The database is up to date with CoreInto VERSION." If a statement fails, the page shows "The update stopped: ... Nothing after that change was applied. Restore your backup or contact support." Changes before the failing one stay applied and are not run again; the failing file is not recorded and is offered again.

The command php cli.php migrate applies the same changes from the command line; see Command line.

Installing an update by hand

When PHP has no zip extension, the web server cannot write to the CoreInto folder, or you simply prefer it. The release zip is one package for both a fresh install and an update; updating means replacing every file except your configuration and data, so no old file is left behind:

1. Take a database backup (Settings > Database Backups, "Back up now", then download it) and download a copy of the CoreInto folder, so that you can go back.
2. In the CoreInto folder delete everything except configuration.php (database login and encryption key), storage/ (attachments, client files, downloads, backups, logs and your own languages in storage/lang) any module you bought separately in modules/ (such as modules/pknic) unless you are uploading its new version too, and your own client area templates in templates/ (every folder except classic and horizon).
3. Unpack the release zip (every path starts with coreinto/) and upload the contents of that coreinto folder into the CoreInto folder, install/ included.
4. Delete the install/ folder. With configuration.php present the installer only says that CoreInto is installed, but the admin area refuses all sign-ins while the folder exists.
5. Open the admin area. If the release has database changes you are sent to Database Update; apply it. If not, the admin area opens as usual.

Your own changes to CoreInto's files (for example the Classic or Horizon template in templates/; make your own copy of a template instead, see Client area) are replaced by the new files: keep a copy and apply them again.

Each release's notes say whether the Database Update step will appear.

For the publisher: releasing CoreInto

This is for the owner who publishes CoreInto, not for a site that uses CoreInto.

1. Set the new version in app/bootstrap.php (CI_VERSION), commit, and make the zip: git archive --format=zip --prefix=coreinto/ -o coreinto-VERSION.zip HEAD -- . ':!tests' ':!docs/HANDOFF.md' ':!docs/ROADMAP.md' ':!modules/pknic'.
2. Sign it on your own computer with CoreInto's release private key: php tools/release.php sign-product --product=coreinto --version=VERSION --file=coreinto-VERSION.zip --key=coreinto-release-PRIVATE.pem. It prints the size, the SHA-256 and the signature.
3. On the licence server: Add-ons > Licensing Releases > Add Release, product coreinto, the version, the channel, the zip and the printed signature; then publish it. The release key coreinto must be set once under Licensing Settings > Release keys (the public half, key id tQNDa-v9WzM1v8u6).

Sites find the release on their next daily update-check, or when an administrator presses "Check for updates". More on tools/release.php in Command line.