AgenDAV 2.2.0 documentation

AgenDAV is a CalDAV web client which features an AJAX interface to allow users to manage their own calendars and shared ones. It’s released under the GPLv3 license.

Contents:

Installation and configuration

Installation

In this section you will found instructions on how to install AgenDAV.

Requirements

AgenDAV 2.2.0 requires the following software to be installed:

  • A CalDAV server
  • A web server
  • PHP >= 5.5.0
  • PHP extensions:
    • ctype
    • curl
    • curl
    • mbstring
    • mcrypt
    • tokenizer
    • xml
    • xmlreader
    • xmlwriter
  • A database backend

Warning

Some PHP releases have issues with digest authentication under Windows. If your CalDAV server uses digest authentication and you are hosting AgenDAV on a Windows server, make sure your PHP version is not affected.

See PHP bug #70101 for more details.

Most popular database backends are supported, such as MySQL, PostgreSQL or SQLite.

Look for supported databases on this Doctrine DBAL driver list.

Download AgenDAV

AgenDAV 2.2.0 can be obtained at AgenDAV webpage.

Uncompress it using tar:

$ tar agendav-...tar.gz
$ cd agendav-.../

PHP configuration

Make sure that you have the following PHP settings set:

  • magic_quotes_runtime: disabled
  • date.timezone: choose a valid time zone from this list.

This is usually done on your php.ini file.

Database requirements

AgenDAV requires a database to store some extra information.

First of all you have to set up your database. If you plan using MySQL or PostgreSQL, here you will find some basic instructions about how to set up them.

Setting up a MySQL/MariaDB database

Warning

If you have binary logging enabled in MySQL/MariaDB, make sure it is configured to use binlog_format = MIXED. Or just disable binary logging in case you don’t actually need it.

AgenDAV will complain and exit in case you have a different binary logging configuration.

Create a user in MySQL and let it use a new agendav database:

$ mysql --default-character-set=utf8 -uroot -p
Enter password:
[...]
mysql> GRANT ALL PRIVILEGES ON agendav.* TO agendav@localhost IDENTIFIED BY 'yourpassword'
mysql> CREATE DATABASE agendav CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql> FLUSH PRIVILEGES;
mysql> ^D

Setting up a PostgreSQL database

Use the special postgres system user to manage your installation. You can add a new user and a new database the following way:

# su postgres
$ psql
postgres=# CREATE USER agendav WITH PASSWORD 'somepassword';
postgres=# CREATE DATABASE agendav ENCODING 'UTF8';
postgres=# GRANT ALL PRIVILEGES ON DATABASE agendav TO agendav;
postgres=# \q
$ exit

Then you have to edit the file pg_hba.conf, which is usually located at /var/lib/pgsql/. Add the following line before other definitions:

# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
local   agendav     agendav                           md5

Setting up a SQLite database

SQLite is not recommended for production environments, but will be more than enough for testing and single user environments.

You will need a dedicated directory for the database:

# mkdir database
# touch database/agendav.sqlite
# chown -R www-data:www-data database/

Web server configuration

It is recommended to read the Silex Webserver configuration guide to learn how to configure your preferred web server software to serve AgenDAV. Just make sure to point your web server to the web/public subdirectory.

Being Apache one of the most used web servers, a sample configuration is shown below for reference:

<VirtualHost 1.2.3.4:443>
 ServerAdmin admin@email.host
 DocumentRoot /path/to/agendav/web/public
 ServerName agendav.host
 ErrorLog logs/agendav_error_log
 CustomLog logs/agendav_access_log common

 <Location />
   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteRule ^ index.php [QSA,L]
 </Location>
</VirtualHost>

You can enable development mode by following the instructions at Development environment.

Fix directory permissions

You should change the owner and group for all AgenDAV files to the ones your webserver uses. Make sure you allow your webserver user to write on the var/ directory. The following example assumes your web server runs as www-data user and www-data group:

# chown -R www-data:www-data web/
# chmod -R 750 web/var/

Configuration

Now you should configure AgenDAV following the Configuration section.

Create AgenDAV tables

AgenDAV tables are created by running the provided agendavcli script.

After configuring your AgenDAV instance, including your database settings, just run the script like this:

$ php agendavcli migrations:migrate

Confirm the operation, and your database should be ready.

Upgrading

Before starting this process, make sure you have a backup of your current AgenDAV directory, specially the web/config/ directory, and a dump of your database schema and contents.

Please, do not continue unless you have both backups.

Read all the Release notes starting at the version you are currently using, because some important changes may have happened. Apply those changes after updating the files from AgenDAV.

Make sure your system meets the requirements before upgrading. Read the Requirements section.

Upgrading from 1.x.x

If you are upgrading AgenDAV from 1.x.x, make sure you have the latest 1.x release installed.

The just follow the steps below. You will also have to update your web server configuration (see Web server configuration).

Upgrade AgenDAV code

a) Updating from a tar.gz file

After downloading the new tar.gz file and uncompressing it, copy your configuration files from the old directory:

$ cp -a /path/to/old_agendav/web/config/settings.php \
  /path/to/new/agendav/web/config/

This will only work if you are upgrading from AgenDAV 2.x, as older releases used different configuration files.

b) Updating from git

If you downloaded AgenDAV from the git repository at GitHub then you can checkout latest stable release from the master branch, or an specific version using its tag.

Just pull latest changes and checkout the release you want. For example, checking out AgenDAV 2.0.0 can be achieved with:

$ git pull
[...]
$ git checkout 2.0.0

Next step is downloading latest AgenDAV dependencies using Composer. If you already have Composer installed, just run:

$ cd web/
$ composer install

If you are upgrading from AgenDAV 1.2.x, you will need to install Composer. Follow the instructions you’ll find in the installation section.

Database upgrade

The database upgrade process included in AgenDAV lets you apply the latest schema changes without having to deal with .sql files and with no need to check which files you should apply to your current version.

Follow the guide at Configuration to create a new settings.php file inside web/config which contains at least the database connection details.

Once you have your database configuration prepared, run the provided agendavcli script this way:

$ php agendavcli migrations:migrate

Clear sessions and caches

It is recommended to remove all active sessions. Do it by running the following command:

$ php agendavcli sessions:clear

If you are running AgenDAV on a production environment, you should clear several caches:

  • Remove the contents of the _twig_ cache directory. The cache path is configured using the option twig.options on your settings.php file. If you did not override the default value, it should be found at web/var/cache/twig/ subdirectory:

    $ rm -rf web/var/cache/twig/*
    
  • Remove the Doctrine ORM metadata cache. Even if you didn’t configure it, the ORM tries to find any available caches (APC, memcached, etc). Clear it with:

    $ php agendavcli orm:clear-cache:metadata
    

Finishing the upgrade from AgenDAV 1.2.x (shares)

If you were using calendar sharing, there is an additional step required to complete the upgrade. The schema upgrading process from AgenDAV 1.2.x can’t handle the upgrade for the shares table. The old table schema makes hard to apply a clean migration, so you have to run a query to adapt the shares data to the new expected format.

The following queries will change the shares table for a DAViCal server, but can be adapted for other CalDAV servers.

MySQL

Run the following SQL queries:

UPDATE `shares` SET owner = CONCAT('/caldav.php/', owner, '/'),
calendar = CONCAT(owner, calendar, '/'),
`with` = CONCAT('/caldav.php/', `with`, '/');

UPDATE `shares` SET options = 'a:0:{}' WHERE options = '';
PostgreSQL

Run the following SQL queries:

UPDATE shares SET owner = '/caldav.php/' || owner || '/',
calendar = '/caldav.php/' || owner || '/' || calendar || '/',
"with" = '/caldav.php/' || "with" || '/';

UPDATE `shares` SET options = 'a:0:{}' WHERE options = '';

Configuration

Configuring AgenDAV requires creating a settings.php file in the web/config/ directory.

You will find all available settings inside the file default.settings.php. Please, do not modify default.settings.php, as any changes will be lost if you upgrade AgenDAV.

Save a copy of the default.settings.php file as settings.php, or just copy the settings you want to modify, and start configuring your instance.

site.title

Title of every page

Image filename which will be used as a logo. Has to be a valid filename placed inside web/public/img/ directory.

site.favicon

Icon filename which will be used as favicon. Has to be placed inside web/public/img/.

site.footer

Text to be placed in the footer.

proxies

Array of IPs of trusted proxies, on which the HTTP_X_FORWARDED_FOR header will be honored.

db.options

Database connection parameters. Uses Doctrine DBAL syntax, so follow the guide at http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html for a better reference. Example:

$app['db.options'] = [
    'dbname' => 'agendav',
    'user' => 'user',
    'password' => 'password',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
 ];

Warning

When using an SQLite database, note that there is a bug when using URL based configurations. Use the alternative syntax (path and driver) instead.

csrf.secret

Internal CSRF token id.

log.level

Level of logging. Can be one from DEBUG, INFO, WARNING, ERROR.

Default setting:

$app['log.level'] = 'INFO';
log.path

Full path where logs will be created. Add a trailing slash. Example:

$app['log.path'] = '/var/log/agendav/';

Make sure the user that runs your web server has write permission on that directory.

caldav.baseurl

Base CalDAV URL used to build all CalDAV URLs.

Examples:

// SabreDAV
$app['caldav.baseurl'] = 'http://caldav.server/cal.php';

// DAViCal
$app['caldav.baseurl'] = 'http://caldav.server/caldav.php';

Note

If you are configuring AgenDAV to connect to a CalDAV server using HTTPS, certificate validation will be performed. Both CA and hostname will be verified. If you are having trouble with your certificate, make sure you have your CA recognized by your system. See OpenSSL changes in PHP 5.6.x for more details.

caldav.authmethod

You have to specify which HTTP authentication method does your CalDAV server require. Both basic and digest authentication methods are supported.

Example:

// SabreDAV
$app['caldav.authmethod'] = 'digest';

// DAViCal
$app['caldav.authmethod'] = 'basic';
caldav.publicurls

Whether to show CalDAV URL links or not in the edit dialog

caldav.baseurl.public

The base URL that will be shown to users if caldav.publicurls is enabled. It’s not used for internal connections.

Do not add a trailing slash.

Example:

$app['caldav.baseurl.public'] = 'https://public.caldav.tld';
caldav.connect.timeout

Timeout in seconds for CalDAV connections. A value of 0 means to wait indefinitely, which is the default behaviour.

Eample:

// Timeout after 5 seconds if connection to the CalDAV server is not ready
$app['caldav.connect.timeout'] = 5;
caldav.response.timeout

Timeout in seconds while waiting for responses after a CalDAV request is sent. A value of 0 means to wait indefinitely, which is the default behaviour.

Example:

// Timeout after 10 seconds if server hasn't answered
$app['caldav.response.timeout'] = 10;
caldav.certificate.verify

Whether to verify the SSL certificate using available CA bundles. Defaults to yes, which is recommended, but can be disabled if the CalDAV server is using a self-signed certificate or a certificate issued by a non-trusted CA.

Example:

// Do not verify SSL certificate, it is self signed
$app['caldav.certificate.verify'] = false;
calendar.sharing

Enables calendar sharing between users

Note that calendar sharing requires full WebDAV ACL support on your CalDAV server. Sharing has been fully tested only with DAViCal, so it is recommended to disable calendar sharing on other CalDAV servers unless you know what you are doing.

calendar.sharing.permissions

Configures ACL permissions for calendar sharing. The default values will work with DAViCal.

defaults.timezone

Timezone to be used by default.

Make sure you use a valid timezone from http://php.net/timezones

defaults.language

Default language to be used on AgenDAV interface.

Have a look at directory web/lang for a list of available languages.

defaults.time_format

Preferred time format: 12 hours (e.g. 3pm / 2:30am) or 24 hours (e.g. 15:00 / 2:30).

Set this option using a string ('12' or '24').

defaults.date_format

Default date format.

Available options are:

  • ymd: e.g. 2011/10/22
  • dmy: e.g. 22/10/2011
  • mdy: e.g. 10/22/2011
defaults.weekstart

Which day should be considered the default first day of week.

0 means Sunday, 1 means Monday

Specify it as a number.

defaults.show_week_nb

Whether or not to show week numbers in views by default

Specify it as a boolean (“true” or “false”).

defaults.show_now_indicator

Whether or not to show a marker indicating current time

Specify it as a boolean (“true” or “false”).

defaults.list_days

Default number of days covered by the “list” (agenda) view. Allowed values: 7, 14 or 31

Specify it as an integer.

defaults.default_view

Default calendar view when accessing AgenDAV. Allowed values: month, week, day and list

Specify it as a string.

logout.redirection

When logging out from AgenDAV, the URL the user will be redirected to.

Can be left empty to redirect user to login page again.

Sessions

AgenDAV uses php.ini session settings. You can override most of them inside settings.php by using the session.storage.options. Just copy it from prod.php and set any parameters you wish.

The following example makes sessions expire after 20 minutes of closing your browser in a low traffic instance:

$app['session.storage.options'] = [
   'name' => 'agendav_sess',
   'cookie_lifetime' => 0,
   // Every request has 10% chance of triggering session GC
   'gc_probability' => 1,
   'gc_divisor' => 10,
   'gc_maxlifetime' => 1200,
   'lifetime' => 1200,
];

Troubleshooting AgenDAV

If you are having problems with AgenDAV, check you have met all the requisites and search AgenDAV logs/web server logs for error lines.

You can write to AgenDAV general list asking for help. Make sure you include the following information:

  • Software details (OS, PHP version, web server you’re using, CalDAV server)
  • Clear description of your problem
  • Important log lines

Try the following before writing:

Development environment

You can switch to development environment easily by setting the environment variable AGENDAV_ENVIRONMENT to dev.

Environment variables have to be set on your webserver configuration file. Apache lets you do it using SetEnv, or even better, using SetEnvIf to enable the development environment just for some IPs. Example:

<Location />
   SetEnvIf Remote_Addr ^1\.2\.3\.4$ AGENDAV_ENVIRONMENT=dev
</Location>

Then point your browser to http://your.agendav.host/. A debugging toolbar will appear, logs will be more verbose and a new HTTP debug log will be generated.

Note that your application will be more slow and logs will grow really fast.

Debug your browser status

Most browsers can show you network activity and JavaScript errors using its own interfaces. They can be very handful if you happen to find a bug on AgenDAV. Some examples of browser which include this support are:

  • Mozilla Firefox with Firebug extension
  • Google Chrome/Chromium with Developer Tools (no addon required)

Translating AgenDAV

AgenDAV translation system is based on labels which get translated into full sentences/paragraphs. They can contain placeholders which get replaced by the system depending on the context.

How to add a translation

Access AgenDAV project in Transifex and use the Create language_ to add the missing language. You’ll have to wait until I approve the request. Once you have it created, you’ll be able to use Transifex interface to translate AgenDAV strings.

Development

Please, read this section if you want to contribute to AgenDAV with code. You can even use this information to confirm a bug.

Virtual Machine

Configuring a working environment for AgenDAV can be difficult. There are so many requirements (web server, PHP, PHP libraries, Composer, a CalDAV server…).

To make the task of setting up an environment easier, AgenDAV ships with a Vagrant file and an Ansible playbook. If you don’t know what that means, don’t worry! They are just two tools used to generate a virtual machine with everything prepared to work on AgenDAV.

Software you will need:

Once you have them installed, let Vagrant initialize the virtual machine:

$ vagrant up

A base image has to be downloaded, and lot of packages have to be installed inside the machine, so this will take a while. Go grab a drink until the machine is ready!

The virtual machine can be stopped and started again using Vagrant. The initialization process will only run the first time you do vagrant up, and next starts will just require a few seconds.

You can stop the machine with vagrant halt, and running vagrant up again will bring it back to life.

Your current working directory is shared with the virtual machine, so you can develop on your local machine and your changes will be visible inside the virtual machine.

Accessing the virtual machine

The environment created inside the virtual machine will be accessible using the following URLs and commands:

The credentials for this environment are:

  • Username: demo
  • Password: demo

Note that Development environment will be enabled by default.

Building assets

If you are going to work on stylesheets, scripts or templates, you will need npm. Run the following command to download all required dependencies:

$ npm install
$ npm run bower

Stylesheets

Stylesheets are built using the Less pre-processor. They are written as .less files and can be found inside the assets/less directory.

Run the following command to rebuild them:

$ npm run build:css

Templates

Stylesheets are built using the dustjs templating engine. They can be found inside the assets/less directory.

Run the following command to rebuild them:

$ npm run build:templates

JavaScript

Run the following command to rebuild them:

$ npm run build:js

Release notes

2.2.0 (?)

  • PHP 5.6 or greater is required.
  • Silex 2.0 is now being used, so any modifications prepared for AgenDAV 2.1.x (which was based on Silex 1.x) will probably be broken.

2.0.0 (2016-11-19)

Relevant release notes from all 2.0.0 release candidates and betas:

  • Note that AgenDAV now requires PHP 5.5.9 or greater.
  • AgenDAV needs Composer. If you are using the tarball from the website you don’t have to worry at all. Otherwise, you’ll have to install it and fetch AgenDAV dependencies. You’ll find instructions on download_dependencies.
  • AgenDAV now uses a single settings.php file. Details on this file are provided on Configuration.
  • Deep database changes are required. Instructions are provided on Database upgrade
  • If you want to upgrade from AgenDAV 1.2.6.2 and you use calendar sharing, note that running an SQL statement is required to complete the upgrade. More details can be found in the Upgrading section.
  • Read the CHANGELOG for a detailed list of changes.

2.0.0-rc2 (2016-11-05)

  • This release includes updated translations. They were missing on rc1

2.0.0-rc1 (2016-11-05)

  • This release candidate handles shared calendars again. If you want to upgrade from AgenDAV 1.2.6.2 and you use calendar sharing, note that running an SQL statement is required to complete the upgrade. More details can be found in the Upgrading section.
  • Read the CHANGELOG for a detailed list of changes.

2.0.0-beta2 (2016-04-20)

  • Note that AgenDAV now requires PHP 5.5.0 or greater.
  • This beta release cannot handle shared calendars yet, and your existing shares will be removed from the database. Please, make sure you are not upgrading a production environment which uses calendar sharing.
  • Read the CHANGELOG for a detailed list of changes.

2.0.0-beta1 (2015-08-26)

  • AgenDAV needs Composer. If you are using the tarball from the website you don’t have to worry at all. Otherwise, you’ll have to install it and fetch AgenDAV dependencies. You’ll find instructions on download_dependencies.
  • AgenDAV now uses a single settings.php file. Details on this file are provided on Configuration.
  • Deep database changes are required. Instructions are provided on Database upgrade
  • This beta release cannot handle shared calendars, and your existing shares will be removed from the database. Please, make sure you are not upgrading a production environment which uses calendar sharing.
  • Read the CHANGELOG for a detailed list of changes.

1.2.6.1 and 1.2.6.2 (2012-10-15)

This release just fixes a problem with some timezones which have three components, such as America/Argentina/Cordoba. AgenDAV 1.2.6 refused to parse calendars that contained events with those kind of timezones.

1.2.6 (2012-09-03)

  • This release requires neither configuration changes nor DB schema updates.
  • Reminders feature has been added. Reminders will be attached to events, but this version of AgenDAV is not capable of showing popups for them yet. Other CalDAV clients, such as smartphones and desktop applications, will understand them.
  • A new log_create_permissions option has been added to advanced.php configuration file. Default is 0640

1.2.5.1 (2012-06-11)

Note

This version has a bug that will make Database upgrade to fail if you have AgenDAV configured to use a language other than English. Please, set default_language to en before running agendav dbupdate

  • This release fixes some invalid SQL queries included in the database update process

1.2.5 (2012-06-07)

  • DB schema needs to be updated, but a new database upgrade process is now available. No more *.sql files, just read Database upgrade section.
  • This release requires PHP cURL support. Make sure your PHP installation has the cURL module enabled
  • Now you can share a calendar in read-only mode. You’re advised to create a new caldav.php configuration file using the provided template
  • Date and time format options have been moved inside config.php. Prior to this release they were set inside lang files, which didn’t make much sense. Have a look at new options format_full_date, format_column_month, format_column_week, format_column_day, format_column_table, format_title_month, format_title_week, format_title_day and format_title_table
  • Translations are now managed using Transifex. Note that default language has been renamed from en_US to en, as I think it’s a neutral English

1.2.4 (2012-01-16)

This release requires no database changes. Contains a fix for localization support for IE7, and lots of aesthetical changes, besides upgraded libraries (jQuery 1.7.1, qTip2 and iCalcreator). Session cookies are now smaller and contain only session identifiers.

  • You have to create a new caldav.php config file using the provided template (caldav.php.template) because caldav_url has been split into two new configuration parameters. Some CalDAV servers use different URLs for principals and calendar collections/resources, and the previous model didn’t work with them:
  • caldav_principal_url will be used to generate principal URLs
  • caldav_calendar_url will be used to generate calendar and resource URLs
  • A new enable_calendar_sharing setting has been added to caldav.php to disable calendar sharing for those servers that don’t support WebDAV ACLs
  • advanced.php configuration file has been updated, make sure you don’t overwrite your own changes.
  • Note that required PHP version is 5.3.0 and not 5.2, there was an error on the requisites list.
  • A setup test script has been included to check if your system meets some basic requisites. Follow the Troubleshooting AgenDAV section for more details.

1.2.3 (2011-11-08)

This release fixes some bugs with am/pm indicators under some circumstances, editing recurring events, include_path problems and other bugs.

It also introduces dynamic text color calculation and new default calendar colors, so it’s recommended to remove the following settings from config.php:

  • default_calendar_color: now the first color from calendar_colors is used
  • additional_calendar_colors: this option has been replaced by calendar_colors

Copy calendar_colors definition from config.php.template to your config.php

This release requires no database upgrades.

1.2.2 (2011-10-25)

This release fixes important issues with recurrent events. It also fixes the am/pm indicator on times.

It requires no database upgrades.

1.2.1 (2011-10-24)

This release mainly fixes issues with timezone differences and Daylight Save Time problems.

Also updates iCalcreator library to latest version (2.10.15) and qTip2.

It requires no database upgrades.

1.2 (2011-10-17)

  • DB schema needs to be altered. UTF8 wasn’t being used by default, and sessions table wasn’t using InnoDB. Apply the changes on sql/changes/1.1.1_to_1.2.mysql, which are the following:

    ALTER DATABASE agendav CHARACTER SET utf8 COLLATE utf8_general_ci;
    ALTER TABLE sessions CONVERT TO CHARACTER SET utf8;
    ALTER TABLE sessions ENGINE InnoDB;
    ALTER TABLE shared CONVERT TO CHARACTER SET utf8;
    
  • Main configuration file (config.php) has been completely rewritten to make it easier to write. Please, use the provided config.php.template as the base for a new config.php

  • Interface translation and timezone configuration is now possible in AgenDAV. Please, make sure you set correct values on config.php

  • AgenDAV has lots of corrections and fixes. See the CHANGELOG

1.1.1 (2011-09-24)

  • Fix DB schema. Wasn’t properlty updated on sql/schema.sql, which caused a problem with sessions

    To correct this issue without completely recreating your current database, run the following two queries:

    CREATE INDEX last_activity_idx ON sessions(last_activity);
    ALTER TABLE sessions MODIFY user_agent VARCHAR(120);
    
  • Remove LDAP dependency. AgenDAV now authenticates against CalDAV server.

    Before this change, AgenDAV authenticated users at first using LDAP, and then your CalDAV server had to authenticate them again. With this change, AgenDAV completely relies on your CalDAV server.