Skip to content

Upgrade Guide

Instructions for upgrading WebCalendar from a previous version.

Table of Contents

Before You Upgrade

1. Back Up Your Database

# MySQL / MariaDB
mysqldump -u USERNAME -p DATABASE > webcalendar-backup-$(date +%F).sql

# PostgreSQL
pg_dump -U USERNAME DATABASE > webcalendar-backup-$(date +%F).sql

# SQLite3
cp /path/to/webcalendar.db webcalendar-backup-$(date +%F).db

2. Back Up Your Configuration

cp includes/settings.php includes/settings.php.backup

3. Back Up Custom Files

If you have custom icons or themes, back up the icons/ directory and any custom CSS files.

4. Check PHP Version

Verify your PHP version meets the requirements for the target release:

php -v

WebCalendar v1.9.16 requires PHP 8.0 or later.

Upgrade Methods

Web Wizard Upgrade

The installation wizard detects your current version and applies database schema changes automatically.

  1. Download and extract the new release into a new directory.
  2. Copy your includes/settings.php from the old installation.
  3. Copy any custom icons from your old icons/ directory.
  4. Point your web server to the new directory (or rename directories).
  5. Access WebCalendar in your browser — the wizard runs automatically when it detects a version mismatch.
  6. Follow the wizard steps. The Database Tables step shows SQL changes that will be applied. Review them before proceeding.
  7. After completion, verify the application works correctly.

The wizard can also be accessed manually at: 

https://yourserver.com/webcalendar/wizard/index.php

Headless Upgrade

For automated or scripted upgrades:

php wizard/headless.php

The headless installer reads configuration from includes/settings.php or environment variables, detects the current version, and applies schema updates non-interactively.

Docker Upgrade

  1. Update the image tag in your docker-compose file.
  2. Recreate the container:
docker-compose -f docker/docker-compose-php8.yml down
docker-compose -f docker/docker-compose-php8.yml pull
docker-compose -f docker/docker-compose-php8.yml up -d

The wizard runs automatically on first access if a schema update is needed. For fully automated upgrades with environment variable configuration, the headless installer runs during container startup.

Manual File Upgrade

If you prefer to update files in place (not recommended for major version upgrades):

  1. Back up your entire WebCalendar directory.
  2. Download the new release.
  3. Extract over your existing installation, preserving:
  4. includes/settings.php
  5. icons/ (if you have custom icons)
  6. Access the application — the wizard will prompt for schema updates.

Post-Upgrade Verification

After upgrading:

  • [ ] Application loads without errors
  • [ ] Login works for admin and regular users
  • [ ] Calendar views display correctly (month, week, day)
  • [ ] Events display with correct dates and times
  • [ ] Creating and editing events works
  • [ ] Repeating events display correctly
  • [ ] Email reminders are still configured (check cron job)
  • [ ] If using LDAP/IMAP auth, verify login still works

Rollback

If the upgrade fails:

  1. Restore your backup database:
# MySQL / MariaDB
mysql -u USERNAME -p DATABASE < webcalendar-backup-YYYY-MM-DD.sql

# PostgreSQL
psql -U USERNAME DATABASE < webcalendar-backup-YYYY-MM-DD.sql

# SQLite3
cp webcalendar-backup-YYYY-MM-DD.db /path/to/webcalendar.db
  1. Restore your old includes/settings.php.
  2. Point your web server back to the old WebCalendar directory (or restore from your file backup).