Radicale is a small but powerful CalDAV (calendars, todo-lists) and CardDAV (contacts) server, that:
Radicale is really easy to install and works out-of-the-box.
$ python3 -m pip install --upgrade radicale
$ python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collectionsWhen your server is launched, you can check that everything's OK by going to http://localhost:5232/ with your browser! You can login with any username and password.
-Want more? Why don't you check our wonderful documentation?
+When the server is launched, open http://localhost:5232/ in your browser! You can login with any username and password.
+Want more? Check the tutorials and the documentation.
Read the changelog on GitHub.
You're new to Radicale and you want to know how to use it? Welcome aboard!
- -Now that you have Radicale running, let's see what we can configure to make it fit your needs.
- -Using is fun, but hacking is soooooooo coooooool. Radicale is a really small and simple piece of code, it may be the perfect project to start hacking!
- -You want to try Radicale but only have 5 minutes free in your calendar? Let's go right now! You won't have the best installation ever, but it will be enough to play a little bit with Radicale.
-When everything works, you can get a client and start creating calendars and address books. The server only binds to localhost (is not reachable over the network) and you can log in with any user name and password. If Radicale fits your needs, it may be time for some basic configuration.
+You want to try Radicale but only have 5 minutes free in your calendar? Let's go right now and play a little bit with Radicale!
+When everything works, you can get a client and start creating calendars and address books. The server only binds to localhost (is not reachable over the network) and you can log in with any user name and password. If Radicale fits your needs, it may be time for some basic configuration.
Follow one of the chapters below depending on your operating system.
-First of all, make sure that python 3.3 or later (python ≥ 3.6 is recommended) and pip are installed. On most distributions it should be enough to install the package python3-pip.
First of all, make sure that python 3.5 or later (python ≥ 3.6 is recommended) and pip are installed. On most distributions it should be enough to install the package python3-pip.
Then open a console and type:
# Run the following command as root or
# add the --user argument to only install for the current user
@@ -306,34 +271,27 @@
$ python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collectionsVictory! Open http://localhost:5232/ in your browser! You can login with any username and password.
The first step is to install Python. Go to python.org and download the latest version of Python 3. Then run the installer. On the first window of the installer, check the "Add Python to PATH" box and click on "Install now". Wait a couple of minutes, it's done!
Launch a command prompt and type:
C:\Users\User> python -m pip install --upgrade radicale
C:\Users\User> python -m radicale --storage-filesystem-folder=~/radicale/collectionsVictory! Open http://localhost:5232/ in your browser! You can login with any username and password.
To be written.
Installation instructions can be found on the Tutorial page.
-Installation instructions can be found in the simple 5-minute setup tutorial.
Radicale tries to load configuration files from /etc/radicale/config and ~/.config/radicale/config. Custom paths can be specified with the --config /path/to/config command line argument or the RADICALE_CONFIG environment variable. Multiple configuration files can be separated by : (resp. ; on Windows). Paths that start with ? are optional.
You should create a new configuration file at the desired location. (If the use of a configuration file is inconvenient, all options can be passed via command line arguments.)
-All configuration options are described in detail on the Configuration page.
-All configuration options are described in detail in the Configuration section.
+In its default configuration Radicale doesn't check user names or passwords. If the server is reachable over a network, you should change this.
First a users file with all user names and passwords must be created. It can be stored in the same directory as the configuration file.
The users file can be created and managed with htpasswd:
Create the users file by hand with lines containing the user name and password separated by :. Example:
user1:password1
user2:password2
@@ -364,21 +322,21 @@ user2:password2
htpasswd_encryption = plainThe default configuration binds the server to localhost. It can't be reached from other computers. This can be changed with the following configuration options (IPv4 and IPv6):
Data is stored in the folder /var/lib/radicale/collections. The path can be changed with the following configuration:
Security: The storage folder should not be readable by unauthorized users. Otherwise, they can read the calendar data and lock the storage. You can find OS dependent instructions in the Running as a service section.
Radicale enforces limits on the maximum number of parallel connections, the maximum file size (important for contacts with big photos) and the rate of incorrect authentication attempts. Connections are terminated after a timeout. The default values should be fine for most scenarios.
The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.
-Create the file ~/.config/systemd/user/radicale.service:
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-
-[Install]
-WantedBy=default.targetRadicale will load the configuration file from ~/.config/radicale/config. You should set the configuration option filesystem_folder in the storage section to something like ~/.var/lib/radicale/collections.
To enable and manage the service run:
-The method to run Radicale as a service depends on your host operating system. Follow one of the chapters below depending on your operating system and requirements.
+Create the radicale user and group for the Radicale service. (Run useradd --system --home-dir / --shell /sbin/nologin radicale as root.) The storage folder must be writable by radicale. (Run mkdir -p /var/lib/radicale/collections && chown -R radicale:radicale /var/lib/radicale/collections as root.)
Security: The storage should not be readable by others. (Run chmod -R o= /var/lib/radicale/collections as root.)
Create the file /etc/systemd/system/radicale.service:
[Unit]
-Description=A simple CalDAV (calendar) and CardDAV (contact) server
-After=network.target
-Requires=network.target
-
-[Service]
-ExecStart=/usr/bin/env python3 -m radicale
-Restart=on-failure
-User=radicale
-# Deny other users access to the calendar data
-UMask=0027
-# Optional security settings
-PrivateTmp=true
-ProtectSystem=strict
-ProtectHome=true
-PrivateDevices=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectControlGroups=true
-NoNewPrivileges=true
-ReadWritePaths=/var/lib/radicale/collections
-
-[Install]
-WantedBy=multi-user.target[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+After=network.target
+Requires=network.target
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+User=radicale
+# Deny other users access to the calendar data
+UMask=0027
+# Optional security settings
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+NoNewPrivileges=true
+ReadWritePaths=/var/lib/radicale/collections
+
+[Install]
+WantedBy=multi-user.targetRadicale will load the configuration file from /etc/radicale/config.
To enable and manage the service run:
+ +Create the file ~/.config/systemd/user/radicale.service:
[Unit]
+Description=A simple CalDAV (calendar) and CardDAV (contact) server
+
+[Service]
+ExecStart=/usr/bin/env python3 -m radicale
+Restart=on-failure
+
+[Install]
+WantedBy=default.targetRadicale will load the configuration file from ~/.config/radicale/config. You should set the configuration option filesystem_folder in the storage section to something like ~/.var/lib/radicale/collections.
To enable and manage the service run:
# Enable the service
-$ systemctl enable radicale
+$ systemctl --user enable radicale
# Start the service
-$ systemctl start radicale
+$ systemctl --user start radicale
# Check the status of the service
-$ systemctl status radicale
+$ systemctl --user status radicale
# View all log messages
-$ journalctl --unit radicale.serviceTo be written.
-First install NSSM and start nssm install in a command prompt. Apply the following configuration:
RadicaleThe service is configured to start automatically when the computer starts. To start the service manually open Services in Computer Management and start the Radicale service.
When a reverse proxy is used, the path at which Radicale is available must be provided via the X-Script-Name header. The proxy must remove the location from the URL path that is forwarded to Radicale.
Example nginx configuration:
location /radicale/ { # The trailing / is important!
@@ -503,8 +457,8 @@ user2:password2
RequestHeader set X-Script-Name /radicale/
</Location>Be reminded that Radicale's default configuration enforces limits on the maximum number of parallel connections, the maximum file size and the rate of incorrect authentication attempts. Connections are terminated after a timeout.
-Set the configuration option type in the auth section to http_x_remote_user. Radicale uses the user name provided in the X-Remote-User HTTP header and disables HTTP authentication.
Example nginx configuration:
location /radicale/ {
@@ -533,8 +487,8 @@ user2:password2
</Location>Security: Untrusted clients should not be able to access the Radicale server directly. Otherwise, they can authenticate as any user.
SSL certificates can be used to encrypt and authenticate the connection between Radicale and the reverse proxy. First you have to generate a certificate for Radicale and a certificate for the reverse proxy. The following commands generate self-signed certificates. You will be asked to enter additional information about the certificate, the values don't matter and you can keep the defaults.
@@ -556,8 +510,8 @@ user2:password2Radicale is compatible with the WSGI specification.
A configuration file can be set with the RADICALE_CONFIG environment variable, otherwise no configuration file is loaded and the default configuration is used.
Be reminded that Radicale's default configuration enforces limits on the maximum upload file size.
@@ -571,14 +525,14 @@ user2:password2 env = RADICALE_CONFIG=/etc/radicale/configExample Gunicorn configuration:
-Set the configuration option type in the auth section to remote_user. Radicale uses the user name provided by the WSGI server and disables authentication over HTTP.
This page describes how to keep track of all changes to calendars and address books with git (or any other version control system).
+This tutorial describes how to keep track of all changes to calendars and address books with git (or any other version control system).
The repository must be initialized by running git init in the file system folder. Internal files of Radicale can be excluded by creating the file .gitignore with the following content:
.Radicale.cache
.Radicale.lock
@@ -588,115 +542,27 @@ user2:password2
The command gets executed after every change to the storage and commits the changes into the git repository.
Radicale has been tested with:
-Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and manage address books and calendars.
-In some clients you can just enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. In others, you have to enter the URL of the collection directly (e.g. http://localhost:5232/user/calendar).
Enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.
GNOME Calendar and Contacts do not support adding WebDAV calendars and address books directly, but you can add them in Evolution.
-In Evolution add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. Clicking on the search button will list the existing calendars and address books.
Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. http://localhost:5232/user/addressbook) and your user name.
Add a new calendar on the network with CalDAV. (Don't use iCalendar (ICS)!) You have to enter the full URL of the collection (e.g. http://localhost:5232/user/calendar). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. http://user@localhost...)
You can integrate InfCloud into Radicale's web interface with RadicaleInfCloud. No additional configuration is required.
-Set the URL of the Radicale server in config.js. If InfCloud is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the same-origin policy. You have to add additional HTTP header in the headers section of Radicale's configuration. The documentation of InfCloud has more details on this.
This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. DAVx⁵).
-To create a new collection, you have to create the corresponding folder in the file system storage (e.g. collection-root/user/calendar). To tell Radicale and clients that the collection is a calendar, you have to create the file .Radicale.props with the following content in the folder:
The calendar is now available at the URL path /user/calendar. For address books the file must contain:
Calendar and address book collections must not have any child collections. Clients with automatic discovery of collections will only show calendars and addressbooks that are direct children of the path /USERNAME/.
Delete collections by deleting the corresponding folders.
-To create a new calendar run something like:
-$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
- <set>
- <prop>
- <resourcetype>
- <collection />
- <C:calendar />
- </resourcetype>
- <C:supported-calendar-component-set>
- <C:comp name="VEVENT" />
- <C:comp name="VJOURNAL" />
- <C:comp name="VTODO" />
- </C:supported-calendar-component-set>
- <displayname>Calendar</displayname>
- <C:calendar-description>Example calendar</C:calendar-description>
- <I:calendar-color>#ff0000ff</I:calendar-color>
- </prop>
- </set>
-</create>'To create a new address book run something like:
-$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
-'<?xml version="1.0" encoding="UTF-8" ?>
-<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
- <set>
- <prop>
- <resourcetype>
- <collection />
- <CR:addressbook />
- </resourcetype>
- <displayname>Address book</displayname>
- <CR:addressbook-description>Example address book</CR:addressbook-description>
- </prop>
- </set>
-</create>'The collection /USERNAME will be created automatically, when the user authenticates to Radicale for the first time. Clients with automatic discovery of collections will only show calendars and address books that are direct children of the path /USERNAME/.
Delete the collections by running something like:
- -Radicale can be configured with a configuration file or with command line arguments.
An example configuration file looks like:
-[server]
-# Bind all addresses
-hosts = 0.0.0.0:5232, [::]:5232
-
-[auth]
-type = htpasswd
-htpasswd_filename = /path/to/users
-htpasswd_encryption = md5
-[storage]
-filesystem_folder = ~/.var/lib/radicale/collections[server]
+# Bind all addresses
+hosts = 0.0.0.0:5232, [::]:5232
+
+[auth]
+type = htpasswd
+htpasswd_filename = ~/.config/radicale/users
+htpasswd_encryption = md5
+
+[storage]
+filesystem_folder = ~/.var/lib/radicale/collectionsRadicale tries to load configuration files from /etc/radicale/config and ~/.config/radicale/config. Custom paths can be specified with the --config /path/to/config command line argument or the RADICALE_CONFIG environment variable. Multiple configuration files can be separated by : (resp. ; on Windows). Paths that start with ? are optional.
The same example configuration via command line arguments looks like:
-python3 -m radicale --server-hosts 0.0.0.0:5232,[::]:5232 --auth-type htpasswd --htpasswd-filename /path/to/htpasswd --htpasswd-encryption md5python3 -m radicale --server-hosts 0.0.0.0:5232,[::]:5232 --auth-type htpasswd --htpasswd-filename ~/.config/radicale/users --htpasswd-encryption md5Add the argument --config "" to stop Radicale from loading the default configuration files. Run python3 -m radicale --help for more information.
In the following, all configuration categories and options are described.
File for the rights backend from_file. See the Rights page.
File for the rights backend from_file. See the Rights section.
Command that is run after changes to storage. Take a look at the Versioning page for an example.
+Command that is run after changes to storage. Take a look at the Versioning with Git tutorial for an example.
Default:
In this section additional HTTP headers that are sent to clients can be specified.
An example to relax the same-origin policy:
- + +Radicale has been tested with:
+Many clients do not support the creation of new calendars and address books. You can use Radicale's web interface (e.g. http://localhost:5232) to create and manage address books and calendars.
+In some clients you can just enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. In others, you have to enter the URL of the collection directly (e.g. http://localhost:5232/user/calendar).
Enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. DAVx⁵ will show all existing calendars and address books and you can create new.
GNOME Calendar and Contacts do not support adding WebDAV calendars and address books directly, but you can add them in Evolution.
+In Evolution add a new calendar and address book respectively with WebDAV. Enter the URL of the Radicale server (e.g. http://localhost:5232) and your user name. Clicking on the search button will list the existing calendars and address books.
Add a new address book on the network with CardDAV. You have to enter the full URL of the collection (e.g. http://localhost:5232/user/addressbook) and your user name.
Add a new calendar on the network with CalDAV. (Don't use iCalendar (ICS)!) You have to enter the full URL of the collection (e.g. http://localhost:5232/user/calendar). If you want to add calendars from different users on the same server, you can specify the user name in the URL (e.g. http://user@localhost...)
You can integrate InfCloud into Radicale's web interface with RadicaleInfCloud. No additional configuration is required.
+Set the URL of the Radicale server in config.js. If InfCloud is not hosted on the same server and port as Radicale, the browser will deny access to the Radicale server, because of the same-origin policy. You have to add additional HTTP header in the headers section of Radicale's configuration. The documentation of InfCloud has more details on this.
This is not the recommended way of creating and managing your calendars and address books. Use Radicale's web interface or a client with support for it (e.g. DAVx⁵).
+To create a new calendar run something like:
+$ curl -u user -X MKCOL 'http://localhost:5232/user/calendar' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:I="http://apple.com/ns/ical/">
+ <set>
+ <prop>
+ <resourcetype>
+ <collection />
+ <C:calendar />
+ </resourcetype>
+ <C:supported-calendar-component-set>
+ <C:comp name="VEVENT" />
+ <C:comp name="VJOURNAL" />
+ <C:comp name="VTODO" />
+ </C:supported-calendar-component-set>
+ <displayname>Calendar</displayname>
+ <C:calendar-description>Example calendar</C:calendar-description>
+ <I:calendar-color>#ff0000ff</I:calendar-color>
+ </prop>
+ </set>
+</create>'To create a new address book run something like:
+$ curl -u user -X MKCOL 'http://localhost:5232/user/addressbook' --data \
+'<?xml version="1.0" encoding="UTF-8" ?>
+<create xmlns="DAV:" xmlns:CR="urn:ietf:params:xml:ns:carddav">
+ <set>
+ <prop>
+ <resourcetype>
+ <collection />
+ <CR:addressbook />
+ </resourcetype>
+ <displayname>Address book</displayname>
+ <CR:addressbook-description>Example address book</CR:addressbook-description>
+ </prop>
+ </set>
+</create>'The collection /USERNAME will be created automatically, when the user authenticates to Radicale for the first time. Clients with automatic discovery of collections will only show calendars and address books that are direct children of the path /USERNAME/.
Delete the collections by running something like:
+This page describes the format of the rights file for the from_file authentication backend. The configuration option file in the rights section must point to the rights file.
This section describes the format of the rights file for the from_file authentication backend. The configuration option file in the rights section must point to the rights file.
The recommended rights method is owner_only. If access to calendars and address books outside of the home directory of users (that's /USERNAME/) is granted, clients won't detect these collections and will not show them to the user. This is only useful if you access calendars and address books directly via URL.
An example rights file:
-# The user "admin" can read and write any collection.
-[admin]
-user = admin
-collection = .*
-permission = rw
-
-# Block access for the user "user" to everything.
-[block]
-user = user
-collection = .*
-permission =
-
-# Authenticated users can read and write their own collections.
-[owner-write]
-user = .+
-collection = %(login)s(/.*)?
-permission = rw
-
-# Everyone can read the root collection
-[read]
-user = .*
-collection =
-permission = r# Allow reading root collection for authenticated users
+[root]
+user: .+
+collection:
+permissions: R
+
+# Allow reading and writing principal collection (same as user name)
+[principal]
+user: .+
+collection: %(login)s
+permissions: RW
+
+# Allow reading and writing calendars and address books that are direct
+# children of the principal collection
+[calendars]
+user: .+
+collection: %(login)s/[^/]+
+permissions: rwThe titles of the sections are ignored (but must be unique). The keys user and collection contain regular expressions, that are matched against the user name and the path of the collection. Permissions from the first matching section are used. If no section matches, access gets denied.
The user name is empty for anonymous users. Therefore, the regex .+ only matches authenticated users and .* matches everyone (including anonymous users).
The path of the collection is separated by / and has no leading or trailing /. Therefore, the path of the root collection is empty.
%(login)s gets replaced by the user name and %(path)s by the path of the collection. You can also get groups from the user regex in the collection regex with {1}, {2}, etc.
%(login)s gets replaced by the user name and %(path)s by the path of the collection. You can also use groups from the user regex in the collection regex with {1}, {2}, etc.
The following permissions are recognized:
This document describes the layout and format of the file system storage (multifilesystem backend).
It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with cron) or after each change to the storage with the configuration option hook in the storage section (e.g. Git Versioning).
It's safe to access and manipulate the data by hand or with scripts. Scripts can be invoked manually, periodically (e.g. with cron) or after each change to the storage with the configuration option hook in the storage section (e.g. Versioning with Git).
The file system contains the following files and folders:
@@ -929,10 +877,10 @@ user2:password2Use the flock utility.
- +Use LockFile for exclusive access or LockFileEx which also supports shared access. Setting nNumberOfBytesToLockLow to 1 and nNumberOfBytesToLockHigh to 0 works.
To create a new collection, you have to create the corresponding folder in the file system storage (e.g. collection-root/user/calendar). To tell Radicale and clients that the collection is a calendar, you have to create the file .Radicale.props with the following content in the folder:
The calendar is now available at the URL path /user/calendar. For address books the file must contain:
Calendar and address book collections must not have any child collections. Clients with automatic discovery of collections will only show calendars and addressbooks that are direct children of the path /USERNAME/.
Delete collections by deleting the corresponding folders.
+Radicale is a really small piece of software, but understanding it is not as easy as it seems. But don't worry, reading this short page is enough to understand what a CalDAV/CardDAV server is, and how Radicale's code is organized.
-Radicale is a really small piece of software, but understanding it is not as easy as it seems. But don't worry, reading this short section is enough to understand what a CalDAV/CardDAV server is, and how Radicale's code is organized.
+Here is a simple overview of the global architecture for reaching a calendar or an address book through network: