NexMail/docs/upgrade.md

Upgrade Guide

This guide explains how to safely upgrade NexMail using the upgrade.sh script.
This guide covers setup, usage, automatic checks, backups, and what happens during the process.

---

📦 1. Overview

The upgrade.sh script automates NexMail updates by:

• Checking for the latest release from Codeberg.
• Comparing your current version with the latest one.
• Creating a full backup (files + database).
• Syncing only the safe system directories.
• Preserving your environment files and storage.
• Running database migrations automatically (if available).
• Ensuring maintenance mode is properly handled.

You should never run this script from inside the NexMail installation directory.

---

🧰 2. Preparation

Before starting:

1. Ensure you have curl, jq, unzip, rsync installed.
   The script will try to install missing tools automatically when possible.

2. Verify your .env file contains valid database credentials and ensure the MySQL/MariaDB client is available for migrations:

   DB_NAME=nexmail
   DB_USER=nexmail
   DB_PASS=your_password
   

3. Make sure you have SSH or shell access to the server.

---

📂 3. Copy the Upgrade Script

Download or copy upgrade.sh outside your NexMail directory.
For example, if NexMail is installed in /var/www/nexmail, place it in your home directory:

cp /var/www/nexmail/sh/upgrade.sh ~/upgrade.sh
chmod +x ~/upgrade.sh

⚠️ Do not run the script from inside the NexMail directory.
It must be executed from somewhere else, like /home/user or /opt.

---

🚀 4. Run the Upgrade

Run the script and specify the NexMail path:

./upgrade.sh /var/www/nexmail

The script will:

1. Fetch the latest version information from Codeberg.
2. Compare it with your installed version (VERSION file).
3. If a new version is found, prompt to enable maintenance mode.
4. Create a full backup.
5. Download and extract the latest release.
6. Sync safe directories.
7. Run database migrations.
8. Update file ownership.
9. Ask whether to disable maintenance mode when done.

---

🔍 5. Checks Performed

The script performs the following validations:

• Ensures it’s not run from inside the NexMail directory.
• Verifies that .installed and VERSION files exist.
• Confirms required tools are available (installs if missing).
• Validates .env file and database credentials.
• Prompts for maintenance mode if not already enabled.
• Checks for missing or invalid release metadata before syncing.

If any of these checks fail, the upgrade stops safely.

---

💾 6. Backup Details

Before any upgrade, a complete backup is created automatically:

../backup-YYYYMMDD_HHMMSS/

Each backup includes:

• A copy of all NexMail files (excluding .env, storage/, and config overrides).
• A MySQL/MariaDB database dump (db-backup.sql) if database credentials are valid.

This allows you to restore immediately if something goes wrong.

---

📁 7. Safe Directories Updated

Only the following directories are overwritten during upgrade:

app/
public/
config/
langs/
docs/
sh/
database/
vendor/

The following are never overwritten:

.env
storage/
.installed
config.ini

This ensures your local configuration, environment, and uploaded data remain intact.

---

🧩 8. Maintenance Mode

If maintenance mode is not enabled, the script will prompt you to turn it on.
It modifies your .env file by setting:

APP_MAINTENANCE=true

After the upgrade completes, you’ll be asked whether to disable it.

---

🧹 9. Ownership and Permissions

At the end, the script automatically detects the web server user (nginx, apache, or httpd) and adjusts ownership for all files:

chown -R www-data:www-data /var/www/nexmail

If it cannot detect the user, it will warn you to set ownership manually.

---

✅ 10. Completion

When successful, you’ll see:

Upgrade complete to version X.Y.Z!

You can then visit your site to confirm the update.

---

🧯 11. Rollback (if needed)

If something goes wrong:

1. Stop the web server or enable maintenance mode.

2. Restore files from the latest backup directory:

   rsync -a --delete /path/to/backup/app-backup/ /var/www/nexmail/
   

3. Restore your database (using secure password method):

   mysql --defaults-extra-file=<(echo -e "[client]\nuser=your_user\npassword=your_password") your_database < /path/to/backup/db-backup.sql
   

   Or use the traditional prompt method:

   mysql -u your_user -p your_database < /path/to/backup/db-backup.sql
   

Then restart your web service.

---

🔒 12. Security Improvements

The upgrade script includes enhanced security measures:

• Database password protection: Uses secure temporary config files instead of exposing passwords in process listings
• Automatic rollback: If the upgrade fails, the script automatically restores from backup
• Dry-run mode: Preview changes before executing with --dry-run flag
• Secure file permissions: Temporary files are created with strict (600) permissions

🕒 13. Summary

Task	Automated	Notes
Fetch latest release	✅	From Codeberg API
Backup files & DB	✅	Stored in parent dir
Compare versions	✅	Uses VERSION file
Maintenance mode	✅	Prompted if off
File sync	✅	Safe directories only
Run migrations	✅	Auto-applied if present
Reset permissions	✅	Web user auto-detected
Rollback support	✅	Automatic on failure
Password security	✅	Secure MariaDB connections

Found an issue with this guide? You can open an issue or submit a PR with a fix.