Hosting with 20% off when you buy through the link

Update Velk

Move a site to a newer Velk version by asking. The AI downloads the official release, checks it, replaces only the engine and keeps your theme, content and settings.

A Velk site has two parts. The engine is Velk itself (core/, bin/, config/ and a few files), the same on every site. Your site is the rest: the theme, the content in the database, the uploads and the .env file with its passwords and keys. Updating swaps the engine for a newer published version and leaves your site in place.

You don't download anything. The AI reads the version the project runs (recorded in .velk-version), finds the target in the official list at releases.velkcms.com and waits for your approval before replacing a file.

Ask the AI

Is there a newer Velk? Tell me which version this project runs, which one is the latest, and what changes in between that affects my theme or my client.

Free to ask: the answer tells you whether the update is a file swap or needs extra work.

Ask the AI

Update Velk in this project to the latest version. Before replacing anything, show me the plan: from which version to which, what gets replaced, what stays, and any change my theme needs.

The AI stops at the plan and waits for your yes.

Ask the AI

The copy on my computer is already on the new version and I've checked it. Make a backup of the live site, then update the engine on the server to the same version.

On the server it installs the published release, never your computer's files.

What the AI does

  1. Reads the upgrade notes

    For every version between yours and the target. Some need more than new files, and some of those steps must happen before the swap.

  2. Shows the plan and waits

    From and to, what's replaced and what's kept, the database changes, any extra step. Nothing changes before your yes.

  3. Downloads and checks

    It compares the file with the checksum published for that version (a fingerprint of the file). If they differ, it stops before opening it.

  4. Replaces only the engine

    It copies what the new release declares as engine and removes engine files the new version dropped.

  5. Adjusts the database

    It runs bin/velk migrate (migrations are the steps that adjust the database to the new version). Only if they all succeed does it delete migrations/.

  6. Records and reports

    It writes the new version in .velk-version, with the previous one, and tells you what changed and how to go back.

What is replaced and what is kept

PartOn update
The engine: core/, config/, bin/, migrations/, index.php, the example files and the engine's own docsReplaced by the new version
theme/: structure, templates (the files that draw the pages), lookKept
The database: content, settings, users, form submissionsKept, only adjusted by the migrations
storage/: uploads and logsKept
.env, the live .htaccess and robots.txt, your .gitignoreKept
What the AI runs
# the latest version, and the fingerprint of its file $ curl -fsSL https://releases.velkcms.com/versions.json $ shasum -a 256 velk-v3.9.1.tar.gz # once the engine files are replaced $ ./bin/velk migrate $ ./bin/velk schema:validate ✓ site.json is valid. # on the live site, after your yes $ scripts/deploy/update-cms.sh --project . ✓ Engine synced ✓ Migrations OK ✓ HTTP 200 OK
On the server, update-cms repeats the checks and ends by confirming that the home page answers.

Versions that need more than new files

Most updates are a file swap. Some need a change in the theme or in site.json, at times before the new engine arrives. The skill keeps these upgrade notes, and the AI adds what they ask for to the plan. Two recent cases:

  • v3.9.0 added a richtext function to the engine. A theme function with that name would stop every page, so the AI renames it first.
  • v3.8.4 moved the security policy settings (the CSP) from .env to site.json. On a site that had set them, the AI moves them into site.json and publishes the theme before updating the server.

The version number doesn't show the size of the job: v3.7.1, which by its number looks like a small fix, required every theme to write its own form and login messages. Updating by asking is what makes these steps happen.

From your computer to the live site

With a full copy of the site on your computer, the AI updates that copy first. You check it in the browser, then ask for the server: update-cms installs the same published release with the same checks and confirms the home page answers. Without a local copy, the AI updates the server directly, naming the version.

It refuses a server without Velk (that needs a first deploy) and refuses an older version over a newer one, because the database already has a structure the older code doesn't know.

Hosting without SSH

Some hosting has no SSH (the secure connection the AI uses to run commands on a server), only FTP (the file transfer most hosting panels offer). There the engine files go up by FTP: ask the AI to download and check the release and tell you exactly what to upload, and never upload the .env from your computer, which points to your local database. On the first visit after the upload, Velk applies the migrations on its own (AUTO_MIGRATE, on by default).

The maintenance page

In any update, a visitor who arrives while migrations run sees a plain page that says “Atualizando…” (Portuguese for “Updating…”) and reloads itself in a few seconds. If a migration fails, it says “Atualização falhou” (“Update failed”) and stays until it's fixed.

The reason is in storage/cache/migration-error.json and storage/logs/migration.log, readable by FTP too. Once the cause is fixed, bin/velk migrate (over SSH, or as a scheduled task in the hosting panel) applies the rest and brings the site back. More in Troubleshooting.

After the update

  • bin/velk schema:validate passes. Since v3.9.0 it also lists, under “Warnings:”, templates the theme lacks; those addresses give a 404.
  • The home and an inner page open, and the admin lets you in.
  • A test form shows its message. An empty box means the theme doesn't word a code the new version uses.
  • On a multilingual site, open a few translated pages: v3.9.0 and v3.9.1 changed what they show when a translation is blank.

The migrations/ folder now looks empty. That's normal: the files are deleted once applied, and the database keeps the record of what ran. bin/velk migrate:status says so instead of claiming everything is applied.