When something is wrong

These are failures we have actually hit, in roughly the order people hit them. Each one starts with what you see, because that is what you have.

The site loads but has no styling

The stylesheet is not being served. If you copied public/ into your document root rather than pointing the docroot at it, check that css/site.css, js/site.js and js/alpine.min.js came across. Open yourdomain.com/css/site.css in a browser: you should see the stylesheet, not an error page.

Upgrading a copy older than 2.0.0, you can delete the old build/ folder from your document root; 2.0.0 does not use it.

The admin panel is there but looks broken: invisible buttons, no field borders

Something is sending a Content-Security-Policy the admin panel cannot run under.

Almost always it is an .htaccess in a folder above AlumDeck. If you installed into a subfolder of a document root you had already hardened, Apache applies that file here too, and a policy written for a plain HTML site does not allow what an admin panel needs.

AlumDeck builds its policy from your settings and public/.htaccess puts it in place of an inherited one (it needs Apache 2.4.10 or newer). Settings > Security > Check my headers fetches your site the way a visitor's browser does and says which policy arrived and what it blocks. If you removed that block, or your server sets the header somewhere else (Nginx, LiteSpeed, or a host-wide setting - see the next section), the policy that arrives is not the one AlumDeck built for that page. AlumDeck's policy is new on every page: it names a nonce, a one-use code that each of the page's own scripts and styles carries, and nothing else may run. A fixed policy written elsewhere has no nonce, so under it the browser refuses every script on the site - in /admin nothing responds to a click and the sidebar renders shut - and every style block, so buttons lose their colour. Remove the other policy (on Nginx and LiteSpeed, use the lines in docs/server/, which pass AlumDeck's own policy through). If Check my headers says "The page's scripts do not carry the nonce of the policy that arrives", a cache in front of the site (a CDN, or the host's page cache) keeps pages apart from their headers: leave the site's pages out of that cache.

To confirm in ten seconds: open the admin panel, press F12, and read the console. A blocked policy names the exact directive that stopped it.

Web servers other than Apache

AlumDeck sends its security headers and its Content-Security-Policy itself, with every page, built from your settings (a tracking tag, Turnstile or video albums add exactly the hosts they need). On Apache, public/.htaccess also replaces any policy a parent folder sets, removes two headers that should not reach a browser (X-AlumDeck-CSP, a private copy of the policy, and X-Powered-By), and gives files Apache sends itself - stylesheets, images, uploads - a fixed base policy. Other web servers need those parts in their own words; the lines are in the docs/server/ folder of the download. Both sample files ship untested: we have not yet run them on a live Nginx or LiteSpeed server, so treat them as a starting point.

• Nginx does not read .htaccess. Add docs/server/nginx.conf to the site's server { } block (it also stops uploaded files from running as code, which public/storage/.htaccess does on Apache), then reload Nginx.
• LiteSpeed reads .htaccess but not every Apache condition. If Check my headers says the policy that arrives is the text of a server rule, or that a tag you switched on would be blocked, replace the security-header block in public/.htaccess with docs/server/litespeed.htaccess. It cannot replace a policy a parent folder sets for the whole domain: remove that one from the parent .htaccess.
• OpenLiteSpeed ignores header lines in .htaccess. Pages are still protected, because AlumDeck sends the headers itself; set the same headers for static files in the WebAdmin console (the site's context, Header Operations).

Then press Check my headers again (Settings > Security or Settings > SEO). Because the samples are untested, that check is how you know they work on your server.

Photos upload but do not display

PUBLIC_DISK_ROOT in .env points at where uploaded media physically lives. It must be a real folder inside your document root.

AlumDeck does not use a symlink for this, because a lot of shared hosts return 403 for a symlinked directory. If the setting is blank or points outside the docroot, uploads succeed and then 404.

Nobody gets any email

Until mail is configured, emails are written to a log file instead of sent. Nothing errors; they just quietly do not go.

Open Settings > Email in the admin, set how the site sends mail and press Send a test email - see Installing AlumDeck.

Event reminders and birthday greetings never arrive

The scheduler cron is missing (the dashboard says "Scheduled tasks are not running"). One line, every minute - copy the exact one from System > Backups > Scheduled tasks:

* * * * * cd /home/youraccount/alumdeck && /usr/local/bin/php -d register_argc_argv=1 artisan schedule:run >> /dev/null 2>&1

"The data.captcha field is required" when signing in

The login captcha only appears when both Turnstile keys are set. Set them on Settings > Security (the page says whether the check is on and where the keys come from). Either set both, or clear both: once either box on that page is filled, the TURNSTILE_* lines of .env are ignored, so a site key there is never matched with an old secret from .env.

Everybody was signed out after an upgrade

Expected, once: 2.0.0 encrypts sessions (SESSION_ENCRYPT=true), and sessions from before cannot be read any more. Sign in again. It does not happen a second time.

A licence warning in the admin, or "Signing in is paused"

The public site is never affected; what pauses is signing in, and only after a grace period of 21 days with a warning banner across the admin panel. The banner and the lock screen say which of these it is:

• The licence lapsed. Renew it; signing in comes back the same day.
• No answer from the licence server since installation, or for more than 60 days. Your host is blocking outbound HTTPS to alumdeck.com, or the server's clock runs far ahead (ask your host to check the time). Fix that and press Check again on the lock screen; signing in comes back as soon as an answer arrives.
• The key is in use on another site. One licence covers one site. Release the key from the other address (Moving to another server later), then press Check again.
• LICENCE_CODE is missing or mistyped. Copy the key from your purchase email into the LICENCE_CODE line of .env.
• The sodium extension is off. In your hosting control panel, open the PHP version screen (in cPanel: Select PHP Version) and tick sodium.
• The licence was withdrawn, or the key is not recognised. Contact us with your site's address.

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

"The database needs updating" on the dashboard

The files of a new version are in place but its database changes are not. Open System > Updates and press Apply database updates - see Upgrading, step 6. If the page reports an error, the site is back online already; send the text it shows to support.

I have locked myself out of two-factor authentication

Two-factor is required for staff on a fresh install, but it only starts once Settings > Email can send the setup code, so a new install is never locked out by it.

If you are locked out at the code step (lost phone, mailbox gone), run php artisan alumdeck:disable-2fa you@example.org on the server for that account, or set REQUIRE_ADMIN_2FA=false in .env, sign in, and sort it out from the admin area.

/install still loads after installation

It should not - the wizard shuts itself once an administrator exists. If it loads, your admin account was not created. Check the users table with your host's database tool (in cPanel: phpMyAdmin) for a row with is_admin set.

Something broke right after an upgrade

Old compiled configuration. Delete everything inside bootstrap/cache/ except .gitkeep. It regenerates on the next request.

The contact form on alumdeck.com - and the more of this you include, the faster the answer:

• Your version, from System > Updates (or alumdeck-build.json)
• What you did, what you expected, what happened
• The exact error text, or a screenshot
• Your PHP version and host, if it happened during installation

We would rather have one long message than three short ones.