Skip to content

installation.md

Latest commit

 

History

History
287 lines (225 loc) · 9.1 KB

installation.md

File metadata and controls

287 lines (225 loc) · 9.1 KB
Raw

WebCalendar v1.9.16 Installation Guide

Table of Contents

Requirements

PHP: 8.2 minimum (CI tests against 8.2, 8.3 and 8.4). PHP 8.1 reached end of life on 31 December 2025 and is no longer supported. Note that PHP 8.2 itself loses security support on 31 December 2026.

PHP Extensions (required):

  • A database driver: mysqli, pgsql, sqlite3, oci8, ibm_db2, odbc, or interbase
  • mbstring
  • openssl
  • session
  • json

PHP Extensions (optional):

  • gd -- gradient backgrounds in calendar views

Supported Databases (via includes/dbi4php.php):

  • MySQL / MariaDB (mysqli) — recommended, most widely tested
  • PostgreSQL (postgresql) — fully supported
  • SQLite3 (sqlite3) — good for small installations, no server needed

Legacy database backends (code present but not tested on PHP 8):

  • Oracle (oracle) — uses deprecated OCI API removed in PHP 8
  • IBM DB2 (ibm_db2) — requires PECL extension, untested
  • ODBC (odbc) — untested, no dedicated table creation SQL
  • Interbase/Firebird (ibase) — extension removed from PHP 8 core

Installation Methods

Web Wizard

The web-based installer lives at wizard/index.php. When no includes/settings.php file exists, WebCalendar automatically redirects to the wizard.

The wizard is a Bootstrap 5 single-page application with 10 steps:

  1. Welcome
  2. PHP Settings check
  3. Database Settings
  4. Create Database
  5. Create/Upgrade Tables
  6. Authentication
  7. Admin User
  8. Application Settings
  9. Summary
  10. Finish

On completion the wizard writes includes/settings.php.

Headless CLI

For automated or Docker deployments, use the CLI installer:

php wizard/headless.php \
  --db-type=mysqli \
  --db-host=localhost \
  --db-login=root \
  --db-password=secret \
  --db-database=webcalendar \
  --admin-login=admin \
  --admin-password=admin123

Additional options:

Flag Description
--db-cachedir=PATH Cache directory (optional)
--user-auth=METHOD Auth method: web, http, none
--user-db=BACKEND Backend file, e.g. user-ldap.php
--single-user=LOGIN Single-user login (if auth=none)
--admin-email=EMAIL Admin email (optional)
--install-password=PASS Wizard/install password
--readonly Enable read-only mode
--dev-mode Enable development mode
--use-env Read DB settings from env vars
--from-settings Use existing settings.php
--force Overwrite existing settings

Exit codes: 0=success, 1=missing params, 2=DB connect failed, 3=DB create failed, 4=table create/upgrade failed, 5=admin user create failed, 6=settings write failed.

Docker

Run all docker compose commands from the top-level WebCalendar directory, not from the docker/ subdirectory.

Production (MariaDB, port 8080):

docker compose -f docker/docker-compose-prod.yml up -d --build

This builds the image from your checkout. On first start every page redirects to the install wizard; complete it in the browser at http://localhost:8080, or from a shell (the database values match the defaults in docker-compose-prod.yml; --force is needed because the image ships an empty settings.php):

docker compose -f docker/docker-compose-prod.yml exec webcalendar \
  php wizard/headless.php --force --db-type=mysqli --db-host=db \
  --db-login=webcalendar --db-password=Webcalendar.1 \
  --db-database=webcalendar_php8 --admin-login=admin \
  --admin-password='choose-a-password'

No default admin/admin account exists; the administrator is whichever account the wizard creates. Change the database passwords in docker-compose-prod.yml before exposing the site.

To run the published image rather than building one, use craigk5n/webcalendar from Docker Hub (for example craigk5n/webcalendar:1.9.24).

Development (MariaDB on 8080, PostgreSQL on 8081):

docker compose -f docker/docker-compose-dev.yml up

SQLite Development (port 8081):

docker compose -f docker/docker-compose-sqlite-dev.yml up

Shell access into a running container:

docker compose -f docker/docker-compose-prod.yml \
  exec webcalendar /bin/sh

Environment Variables

For containerized or automated deployments you can skip includes/settings.php entirely. Set WEBCALENDAR_USE_ENV=true and provide the following variables:

Variable Example
WEBCALENDAR_USE_ENV true
WEBCALENDAR_DB_TYPE mysqli
WEBCALENDAR_DB_HOST db-mariadb
WEBCALENDAR_DB_DATABASE webcalendar
WEBCALENDAR_DB_LOGIN webcalendar
WEBCALENDAR_DB_PASSWORD secret
WEBCALENDAR_DB_PERSISTENT true
WEBCALENDAR_INSTALL_PASSWORD MD5 hash of password
WEBCALENDAR_USER_INC user.php
WEBCALENDAR_MODE dev or prod

Generate the install password hash:

php -r "echo md5('YourPassword');"

Manual Database Setup

While the Web Wizard is the recommended way to set up your database, you can also perform the setup manually if your hosting environment requires it.

Manual setup involves three steps:

  1. Creating the database.
  2. Creating the database user with appropriate privileges.
  3. Importing the required table definitions.

SQL files for supported databases are located in the install/sql/ directory:

  • tables-mysql.sql
  • tables-postgres.sql
  • tables-sqlite.sql
  • tables-oracle.sql
  • tables-mssql.sql
  • tables-db2.sql
  • tables-ibase.sql

MySQL / MariaDB (Command Line)

  1. Create the database: 
    mysqladmin -u root -p create webcalendar
  2. Create the user and grant privileges: 
    GRANT ALL PRIVILEGES ON webcalendar.* TO 'webcal_user'@'localhost' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
  3. Import the tables: 
    mysql -u webcal_user -p webcalendar < install/sql/tables-mysql.sql

PostgreSQL (Command Line)

  1. Create the database and user: 
    su - postgres
createdb webcalendar
createuser -P webcal_user
  2. Import the tables: 
    psql -U webcal_user -d webcalendar -f install/sql/tables-postgres.sql

Using phpMyAdmin

If you have phpMyAdmin installed, you can use it to set up WebCalendar:

  1. Create Database: On the main page, enter a name (e.g., webcalendar) in the "Create new database" field and click Create.
  2. Create User (Optional): Click the Privileges tab, then Add a new user. Enter your chosen username and password. In the Global privileges section, select SELECT, INSERT, UPDATE, DELETE, FILE, CREATE, ALTER, INDEX, and DROP. Click Go.
  3. Import Tables: Click the name of your new database in the sidebar, then click the Import tab at the top. Use the Browse button to select install/sql/tables-mysql.sql from the WebCalendar directory and click Go.

Configuration

The wizard writes includes/settings.php. This file contains database connection details, authentication method, and install password. Key settings:

Setting Description
db_type Database driver name
db_host Database hostname
db_database Database name or SQLite file path
db_login Database username
db_password Database password
db_persistent Use persistent connections
db_cachedir Cache directory path
user_inc Auth backend file
single_user Single-user mode (Y/N)
readonly Read-only mode (Y/N)
use_http_auth HTTP authentication
mode dev or prod

Authentication Backends

Configured during installation via the wizard's Authentication step or the --user-db flag in headless mode.

Backend File Notes
Database user.php Default; users stored in webcal_user
LDAP user-ldap.php LDAP/Active Directory
IMAP user-imap.php IMAP server authentication
NIS user-nis.php Network Information Service
Joomla user-app-joomla.php Joomla CMS integration

Composer and Assets

Releases ship with front-end dependencies pre-built in the pub/ directory. Composer is only needed for development.

composer install
make              # copies vendor assets to pub/

The make target requires sha384sum (Linux). It copies Bootstrap, jQuery, and other front-end assets from vendor/ into pub/ where the application loads them. make mcp-sdk runs on any OS and refreshes the MCP SDK copy in includes/classes/mcp-sdk/, which is how the MCP server works in releases without Composer.

Upgrading

The web wizard and headless installer both detect the current database version and apply any needed upgrade SQL automatically. Run the wizard (web or CLI) against your existing database and it will upgrade the schema in place.