Upgrading

This is the whole idea, so it is worth being explicit.

Everything you have typed or uploaded lives in the database and your media folder. The code is disposable - that is what makes upgrades safe.

A copy installed from a release zip is updated from System > Updates in two steps, download then install - no terminal, no uploads, no folder swapping:

1. Switch on Check for new versions on System > Updates and save. When a newer version your licence covers is out, the page says so and shows Download and install.
2. Press it and confirm with Download and check. AlumDeck asks the licence server again (only an answer the server signed counts) and checks that the new version also carries AlumDeck's release signature - made on the vendor's own workstation with a key that never touches any server, so not even a taken-over licence server could send you code. It then downloads the zip, checks it against the checksum in that signed answer (and stops the download if it grows past the signed size), checks every file in it and compares each one with your copy by SHA-256. Only the files that differ are unpacked, into storage/app/updates/staging. Nothing on your site has changed yet: the next dialog says how many files change and how many database updates come with it.
3. Press Install now. With automatic backups off, first tick "I have a recent backup from my host" (how to take one). For a minute or two visitors see a holding page while AlumDeck:
   • moves each changed file into place, after moving the file it replaces into storage/app/updates/rollback-<old version>-<date>;
   • checks every file it placed;
   • clears the compiled caches and makes PHP's opcode cache forget every file that moved (the result says whether it could);
   • then sends your browser to System > Updates again. That page is the first request on the new version, and it applies the database updates there, exactly as Apply database updates does (a backup first when automatic backups are on) - never in the request that still had the old version's code in memory.
4. The page lists every step. The same steps are in System > Audit log (event software_update).

What it never touches: .env; everything under storage/, including the licence record; your media folder (public/storage, or wherever PUBLIC_DISK_ROOT points); bootstrap/cache (cleared, not replaced); SQLite databases; your host's own files (.user.ini, php.ini, an .htaccess in the alumdeck folder itself, PHP's error_log files). A file under app/, bootstrap/, config/, database/, resources/, routes/ or vendor/ that the new version no longer ships is removed (it waits in the rollback folder); extra files in docs/, lang/ and public/ stay.

Your .htaccess rules stay. AlumDeck's own rules sit between # BEGIN AlumDeck and # END AlumDeck in public/.htaccess (and in the copy in your document root). An update replaces only those lines. Everything above and below them - your own rules, an HTTPS redirect, a password on a folder (in cPanel: Directory Privacy), IP blocks - and every block cPanel writes (# BEGIN cPanel-generated ...) is kept, even one cPanel put inside AlumDeck's block. If the # BEGIN AlumDeck block is missing, or you edited lines inside it, the update leaves that .htaccess exactly as it is and says so; compare it with the new version's public/.htaccess yourself. So put your own rules above or below the block, never inside it.

Cron waits. While files move, and until the database updates have run, artisan (and so the scheduler cron runs every minute) skips its work; it starts again on the next minute after the update. If an update was cut off and nobody visits the site, the next cron run puts the previous files back.

If you copied public/ into your document root (the layout of install guide step 2, usual on cPanel), the updater finds the document root from the request, checks that its index.php points at this copy, and updates the files there as well: index.php keeps your three edited paths, and the media folder and .user.ini stay as they are. If that index.php points somewhere else, the updater stops before downloading and says so - use the manual upgrade.

If anything fails - a file that cannot be written, a database update that stops - every file is put back from the rollback folder by itself, the holding page goes, and the page says what happened in plain words. Database updates that had already run stay; with automatic backups on, the backup taken just before them is under Backups.

If the request itself is cut off - the host stops it, PHP hits its time limit, the new version fails with a PHP error on its first page, or nobody opens that page within 15 minutes - the holding page does the work: it runs before any of AlumDeck's code (index.php and artisan load storage/framework/maintenance.php first), notices that nothing is installing any more, puts every previous file back on the next request to the site (or the next cron run), and takes itself away. System > Updates then says what happened, and the audit log has it. The update's record (storage/app/updates/plan.json) is signed with a key derived from your APP_KEY: a file dropped there by anything else is ignored.

What it needs: a copy installed from a release zip (a development copy, one with no alumdeck-build.json, says it cannot be updated this way); PHP's zip extension; outbound HTTPS to alumdeck.com; write access for your account to the alumdeck folder (and the document root); and free disk space for the download, the changed files, a copy of the files they replace and 50 MB more - all checked together before anything changes. Your hosting quota is not visible to PHP: if it runs out half-way, the write fails and everything is put back. On a host whose PHP keeps old code in its opcode cache and does not let AlumDeck clear it, the update refuses before downloading and says what to ask the host.

The replaced files stay in storage/app/updates/rollback-... until the next update deletes them. Whenever the Updates screen refuses to update, the manual upgrade below still works.

By hand: the fallback whenever the Updates screen refuses to update, and the only way for a development copy.

0. Turn off anything that writes to the install on a schedule. A cron job that rebuilds symlinks, syncs files or otherwise "repairs" the folder will fire in the middle of the swap and leave you holding half of each version. In your hosting control panel, under scheduled tasks (in cPanel: Cron Jobs): comment the line out, do the upgrade, and put it back afterwards only if you still need it.

1. Put the site in maintenance mode. Admin > Settings > Maintenance. Visitors get a holding page; you keep working.

2. Upload and extract the new zip into your home directory, next to the existing install. It extracts to alumdeck, so extract it somewhere else first - say alumdeck-new - so you do not overwrite anything yet.

3. Copy your .env across.

alumdeck/.env   ->   alumdeck-new/.env

Do this before anything else. It is the one file that is yours and lives in the code folder.

4. Copy your uploaded media across. If PUBLIC_DISK_ROOT points inside your document root, your media is already outside the code folder and nothing needs moving. Check the value in .env before assuming.

5. Swap the folders.

alumdeck        ->  alumdeck-old
alumdeck-new    ->  alumdeck

If you set your document root to alumdeck/public, it now serves the new code with no further change. If you copied public/ into your docroot instead, copy the new one over it now - then edit the three lines of the new index.php again, exactly as in the install guide, because the copy brings back the original __DIR__.'/../'. Upgrading a copy older than 2.0.0? The old build/ folder in your document root is no longer used and can be deleted.

On Nginx or LiteSpeed, compare the files in the new docs/server/ folder with the lines you added to your server; then press Check my headers on Settings > Security after the upgrade.

5a. Add any new settings to your .env. Open the new .env.example next to your own .env and copy across any key that appears in the example but not in yours, leaving the value blank unless its comment says otherwise. Missing one rarely looks like a missing setting: leave out APP_INSTALLED=true and the installer reappears on your live site.

Upgrading a copy older than 2.0.0, also change these, which have better defaults from 2.0.0 on:

LOG_STACK=daily          # was single: one log file per day instead of one that never stops growing
LOG_DAILY_DAYS=14
LOG_LEVEL=warning        # was error: failed emails are logged as warnings
REQUIRE_ADMIN_2FA=true   # staff two-factor; waits until Settings > Email works
SESSION_SECURE_COOKIE=true   # only if your site address starts with https://
SESSION_ENCRYPT=true     # encrypted sessions

Switching on encrypted sessions signs everybody out once - staff and members simply sign in again. If your .env has no SESSION_ENCRYPT line at all, 2.0.0 turns encryption on by itself, with the same one sign-out.

The Cloudflare Turnstile keys (TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY) can now live on Settings > Security instead, where the secret is stored encrypted. Once either box there is filled, the two .env lines are no longer read.

TRUSTED_HOSTS is new and optional: the site answers on the address in APP_URL and on its www twin (example.org and www.example.org). If it also answers on another name - a second domain, or another subdomain such as alumni.example.org - list that name there (comma separated). Any other host name is refused. Emails link to the address in APP_URL (or its www twin when that is the name the request came in on), never to another name.

6. Update the database. Sign in to the admin and open System > Updates. It lists the database updates the new version brings; press Apply database updates.

• With automatic backups on (Settings > Automatic backups), a backup is taken first. If it fails, nothing is changed and the page says why.
• With automatic backups off, you are asked to confirm that you have a recent backup from your host - the one you took in "Before you touch anything".

While the updates run (usually seconds) the public site shows the maintenance page; the admin keeps working. Afterwards the caches are cleared and the page says exactly which updates were applied. Until the database is updated the dashboard shows "The database needs updating" in its Needs attention list, with a link to this page.

You can still do it from a terminal if you prefer: php artisan migrate --force in the alumdeck folder.

7. Take it out of maintenance mode and check, rather than hope. Click the homepage, one event, one post, the member directory and the admin dashboard - then check these four, because they are the ones that fail quietly:

• yourdomain.com/install returns "not found". If it shows the installer, APP_INSTALLED is missing from your .env.
• Your logo and a photo uploaded through the admin both load. If they are broken, see "Images stop loading after an upgrade" below.
• yourdomain.com/robots.txt shows your site's own rules and a Sitemap: line.
• The newest log in storage/logs/ (one file a day) has nothing new in it.

8. Keep alumdeck-old for a week. Then delete it.

Swap the folders back, restore the database export, done. That is why step 8 exists.

alumdeck      ->  alumdeck-broken
alumdeck-old  ->  alumdeck

Then restore the .sql file with the same database tool (in cPanel: phpMyAdmin).

Your public site keeps working. Every public page still serves and still ranks: news, events, history, notable alumni, the archive, the sitemap. Your database is untouched.

What stops is signing in, for admins and members alike, along with new versions and support. Renewing restores all of it the same day, including years later.

The rules the licence check is built around, because they are the whole risk of a check like this:

• Nothing stops the moment the date passes. There is a grace period of 21 days past the renewal date, with a warning banner across the admin panel for the whole of it, before anything changes.
• Only a signed answer counts. The site believes an answer only when our server signed it for this site's key and address. An unreachable server is not a lapse, but it is not an answer either: a site that has never had an answer pauses signing in 21 days after it was installed, and a site with no answer for 60 days shows the banner and pauses signing in 21 days after that. Keep outbound HTTPS to alumdeck.com open.
• One site per licence. If the key is in use on another site, the banner says so and signing in pauses 21 days later unless the key is released there - see Moving to another server later.

If Cerevonix ever stops trading, we will publish a final release of AlumDeck that runs without the licence check.

An upgrade changes none of this. The answers your site has had are kept in the database as well as in storage/, so swapping the folders does not reset anything.