Upgrade Guide

This document provides detailed instructions for upgrading Securaine to newer versions safely and efficiently in production environments.

Important: Always back up your existing project before performing an upgrade.

🚀 Upgrade Workflow

✅ 1. Backup Existing Installation

Before any upgrade:

Backup all files from your current installation directory.
Backup the following critical files:
- .env
- app/config.php
- Any custom Blade views you modified (especially under views/)
- Uploaded files (storage/secure-files/)
- Secure attachment metadata (storage/secure-meta/) if attachment link delivery is enabled
- Logs (storage/logs/) if needed for audits

Note: If you are using AWS S3 storage, ensure your bucket configuration and credentials are backed up securely. Do not include secrets in public backups.

📦 2. Download the New Version

Download the latest licensed version of Securaine from the official distribution channel.
Unzip the new version locally.

🧪 3. Test in a Staging Environment (Recommended)

Before upgrading production:

Set up a staging site using a copy of your .env and configuration files.
Verify:
- Form loads and submits successfully
- CAPTCHA and CSRF validations work
- Emails are sent correctly
- File uploads work correctly
- Attachment delivery mode behaves as expected
- Any customizations still function as expected

🔁 4. Merge or Replace Files

Carefully replace or merge files. Recommended steps:

Replace / Merge	Description
`/app/Controllers/`	Replace unless you've customized logic.
`/app/Services/`	Replace unless you've extended them. Review attachment, storage, and mail services carefully.
`/app/bootstrap.php`	Replace (contains bootstrap updates).
`/views/form.blade.php`	Manually merge if you made customizations.
`/views/layouts/`	Replace or merge UI layout updates.
`/views/email/`	Review email templates if attachment handling or email formatting changed.
`/lang/`	Add or update language files as needed.
`/public/assets/`	Replace for updated CSS/JS and UI improvements.
`/routes/`	Replace if routes were updated.
`/storage/`	Preserve your logs, cache, secure metadata, and generated files. Do not replace.
`.env`	Do not overwrite. Copy any new variables from `.env.example`.
`.htaccess`	Replace only if instructed.

⚙️ 5. Update Configuration

After replacing files:

Open your existing .env file.
Compare it with the new .env.example file.
Add any new environment variables introduced in the update.

Example:

+ CAPTCHA_PROVIDER=turnstile
+ TURNSTILE_SITEKEY=your-new-site-key
+ TURNSTILE_SECRET=your-new-secret
+ ATTACHMENT_DELIVERY_MODE=attachment

📎 Attachment Delivery Configuration

Newer versions include configurable attachment delivery handling.

Review:

app/config.php

Verify the attachment_delivery section:

'attachment_delivery' => [
    'enabled' => true,
    ...
],

Attachment Delivery Modes

Mode	Behavior
`attachment`	Files are uploaded and attached directly to outgoing emails. No download metadata is generated.
`link`	Files are stored privately and delivered through protected download links with optional expiration, password protection, and download limits.

🔐 Attachment Link Migration Notes

If upgrading from a version before secure attachment links:

Verify:

storage/
├── secure-meta/
├── logs/
└── cache/

The following folder must exist and be writable:

storage/secure-meta/

This directory stores:

Secure download tokens
File metadata
Expiration information
Download counters
Password protection settings

Do not manually edit generated metadata files unless troubleshooting.

☁️ Storage Configuration Review

If using local storage:

Verify:

storage/secure-files/

permissions and uploaded files.

If using AWS S3:

Verify:

Bucket credentials
Region configuration
Bucket permissions
Private object access

Files used for secure download links should remain private. Public bucket access is not required.

🧹 6. Clear Cache

If your previous installation or server cached compiled views, language files, or configs, clear them manually.

# Navigate to your installation folder
cd /path-to-your-site/storage/cache

# Delete all contents inside the /cache folder
rm -rf *

✅ Ensure the storage/cache/ folder remains intact but empty after this.

✅ 7. Test the Upgrade

Once everything is uploaded and configured:

Visit your site in a private/incognito browser window.
Test the contact form submission flow.

Check:

Form validation
File uploads
CAPTCHA functionality (Google reCAPTCHA or Cloudflare Turnstile)
Email delivery
AI message generation
Language switching
Dark/light mode

Attachment Testing

Test both delivery modes.

Direct Attachment Mode

Environment:

ATTACHMENT_DELIVERY_MODE=attachment

Verify:

File is attached to the outgoing email.
No secure download metadata file is created.
No download password is generated.

Secure Link Mode

Environment:

ATTACHMENT_DELIVERY_MODE=link

Verify:

Secure download URL is generated.
Metadata is created under:

storage/secure-meta/

Password protection works if enabled.
Expiration date is enforced.
Download limits are enforced.

📋 8. Changelog Access

The changelog is not bundled inside the software package. To see what’s new:

🔗 Visit the official Securaine Changelog Page.

💬 9. Support for Paid Licensed Users

If you need help upgrading or encounter issues:

🛠️ Create a ticket via our Helpdesk.

Provide your:

License key or registered email
Description of the issue
Current version you are upgrading from
Server environment details
Relevant error logs if available

🧾 Final Checklist

Task	Status
🔽 Downloaded latest `.zip`	✅
📁 Extracted & uploaded files	✅
📝 `.env` and `.htaccess` renamed & updated	✅
🔧 Reviewed `config.php`	✅
📎 Reviewed attachment delivery configuration	✅
☁️ Verified storage configuration	✅
🗂️ Checked `storage/secure-meta/` permissions	✅
🧹 Cleared `storage/cache/`	✅
📬 Tested form functionality	✅
📎 Tested attachment delivery mode	✅
📞 Support ready (if needed)	✅

📌 Notes

Email templates are located in:

views/email/

Form layout can be edited in:

views/form.blade.php

Layout templates:

views/layouts/

Attachment delivery configuration:

app/config.php

Secure attachment metadata:

storage/secure-meta/

📝 Manual Customizations

If you've made manual changes to any of the following:

views/ templates
app/config.php
JS or CSS in public/assets/
Attachment or storage related services

…you must carefully merge updates instead of simply replacing files.

Use a tool like Beyond Compare, Meld, or Git diff tools to assist with merging.