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
-
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.
-
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.
-
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.
-
Replaces only the engine
It copies what the new release declares as engine and removes engine files the new version dropped.
-
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 deletemigrations/. -
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
| Part | On update |
|---|---|
The engine: core/, config/, bin/, migrations/, index.php, the example files and the engine's own docs | Replaced by the new version |
theme/: structure, templates (the files that draw the pages), look | Kept |
| The database: content, settings, users, form submissions | Kept, only adjusted by the migrations |
storage/: uploads and logs | Kept |
.env, the live .htaccess and robots.txt, your .gitignore | Kept |
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
richtextfunction 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
.envtosite.json. On a site that had set them, the AI moves them intosite.jsonand 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:validatepasses. 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.