+Simple 5-minute setup
+You want to try Radicale but only have 5 minutes free in your
+calendar? Let's go right now and play a 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 username 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.
+
+Linux / *BSD
+First, 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
+$ python3 -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+$ python3 -m radicale --storage-filesystem-folder=~/.var/lib/radicale/collections
Victory! Open http://localhost:5232 in your browser!
+You can log in with any username and password.
+
+
+Windows
+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:
+python -m pip install --upgrade https://github.com/Kozea/Radicale/archive/master.tar.gz
+python -m radicale --storage-filesystem-folder=~/radicale/collections
Victory! Open http://localhost:5232 in your browser!
+You can log in with any username and password.
+
+
+
+Basic Configuration
+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 in the Configuration section.
+
+Authentication
+In its default configuration Radicale doesn't check usernames or
+passwords. If the server is reachable over a network, you should change
+this.
+First a users file with all usernames and passwords must
+be created. It can be stored in the same directory as the configuration
+file.
+
+The secure way
+The users file can be created and managed with htpasswd:
+# Create a new htpasswd file with the user "user1"
+$ htpasswd -c /path/to/users user1
+New password:
+Re-type new password:
+# Add another user
+$ htpasswd /path/to/users user2
+New password:
+Re-type new password:
Authentication can be enabled with the following configuration:
+[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = md5
The simple but insecure way
+Create the users file by hand with lines containing the
+username and password separated by :. Example:
+user1:password1
+user2:password2
+Authentication can be enabled with the following configuration:
+[auth]
+type = htpasswd
+htpasswd_filename = /path/to/users
+# encryption method used in the htpasswd file
+htpasswd_encryption = plain
Addresses
+The 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):
+[server]
+hosts = 0.0.0.0:5232, [::]:5232
Storage
+Data is stored in the folder
+/var/lib/radicale/collections. The path can be changed with
+the following configuration:
+[storage]
+filesystem_folder = /path/to/storage
+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.
+
+
+
+Limits
+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.
+[server]
+max_connections = 20
+# 100 Megabyte
+max_content_length = 100000000
+# 30 seconds
+timeout = 30
+
+[auth]
+# Average delay after failed login attempts in seconds
+delay = 1
Running as a service
+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.
+
+Linux with systemd system-wide
+Create the radicale user and group for the Radicale
+service. (Run
+useradd --system --user-group --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
Radicale will load the configuration file from
+/etc/radicale/config.
+To enable and manage the service run:
+# Enable the service
+$ systemctl enable radicale
+# Start the service
+$ systemctl start radicale
+# Check the status of the service
+$ systemctl status radicale
+# View all log messages
+$ journalctl --unit radicale.service
Linux with systemd as a user
+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.target
Radicale 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 --user enable radicale
+# Start the service
+$ systemctl --user start radicale
+# Check the status of the service
+$ systemctl --user status radicale
+# View all log messages
+$ journalctl --user --unit radicale.service
Windows with "NSSM - the Non-Sucking Service Manager"
+First install NSSM and start
+nssm install in a command prompt. Apply the following
+configuration:
+
+- Service name:
Radicale
+- Application
+
+- Path:
C:\Path\To\Python\python.exe
+- Arguments:
-m radicale --config C:\Path\To\Config
+
+- I/O redirection
+
+- Error:
C:\Path\To\Radicale.log
+
+
+
+Security: Be aware that the service runs in the
+local system account, you might want to change this. Managing user
+accounts is beyond the scope of this manual. Also, make sure that the
+storage folder and log file is not readable by unauthorized users.
+
+The log file might grow very big over time, you can configure file
+rotation in NSSM to prevent this.
+The 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.
+
+
+
+Reverse Proxy
+When a reverse proxy is used, and Radicale should be made available
+at a path below the root (such as /radicale/), then this
+path must be provided via the X-Script-Name header (without
+a trailing /). The proxy must remove the location from the
+URL path that is forwarded to Radicale. If Radicale should be made
+available at the root of the web server (in the nginx case using
+location /), then the setting of the
+X-Script-Name header should be removed from the example
+below.
+Example nginx configuration:
+location /radicale/ { # The trailing / is important!
+ proxy_pass http://localhost:5232/; # The / is important!
+ proxy_set_header X-Script-Name /radicale;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header Host $http_host;
+ proxy_pass_header Authorization;
+}
+Example Caddy configuration with basicauth from
+Caddy:
+handle_path /radicale* {
+ basicauth {
+ user hash
+ }
+ reverse_proxy localhost:5232 {
+ header_up +X-Script-Name "/radicale"
+ header_up +X-remote-user "{http.auth.user.id}"
+ }
+}
+Example Apache configuration:
+RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+ ProxyPass http://localhost:5232/ retry=0
+ ProxyPassReverse http://localhost:5232/
+ RequestHeader set X-Script-Name /radicale
+ RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
+ RequestHeader unset X-Forwarded-Proto
+ <If "%{HTTPS} =~ /on/">
+ RequestHeader set X-Forwarded-Proto "https"
+ </If>
+</Location>
Example Apache .htaccess configuration:
+DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Forwarded-Port "%{SERVER_PORT}s"
+RequestHeader unset X-Forwarded-Proto
+<If "%{HTTPS} =~ /on/">
+RequestHeader set X-Forwarded-Proto "https"
+</If>
Example lighttpd configuration:
+server.modules += ( "mod_proxy" , "mod_setenv", "mod_rewrite" )
+
+$HTTP["url"] =~ "^/radicale/" {
+ proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => "5232" )) )
+ proxy.header = ( "map-urlpath" => ( "/radicale/" => "/" ))
+
+ setenv.add-request-header = (
+ "X-Script-Name" => "/radicale",
+ "Script-Name" => "/radicale",
+ )
+ url.rewrite-once = ( "^/radicale/radicale/(.*)" => "/radicale/$1" )
+}
+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.
+
+Manage user accounts with the reverse proxy
+Set the configuration option type in the
+auth section to http_x_remote_user. Radicale
+uses the username provided in the X-Remote-User HTTP header
+and disables HTTP authentication.
+Example nginx configuration:
+location /radicale/ {
+ proxy_pass http://localhost:5232/;
+ proxy_set_header X-Script-Name /radicale;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Remote-User $remote_user;
+ proxy_set_header Host $http_host;
+ auth_basic "Radicale - Password Required";
+ auth_basic_user_file /etc/nginx/htpasswd;
+}
+Example Apache configuration:
+RewriteEngine On
+RewriteRule ^/radicale$ /radicale/ [R,L]
+
+<Location "/radicale/">
+ AuthType Basic
+ AuthName "Radicale - Password Required"
+ AuthUserFile "/etc/radicale/htpasswd"
+ Require valid-user
+
+ ProxyPass http://localhost:5232/ retry=0
+ ProxyPassReverse http://localhost:5232/
+ RequestHeader set X-Script-Name /radicale
+ RequestHeader set X-Remote-User expr=%{REMOTE_USER}
+</Location>
Example Apache .htaccess configuration:
+DirectoryIndex disabled
+RewriteEngine On
+RewriteRule ^(.*)$ http://localhost:5232/$1 [P,L]
+
+AuthType Basic
+AuthName "Radicale - Password Required"
+AuthUserFile "/etc/radicale/htpasswd"
+Require valid-user
+
+# Set to directory of .htaccess file:
+RequestHeader set X-Script-Name /radicale
+RequestHeader set X-Remote-User expr=%{REMOTE_USER}
+Security: Untrusted clients should not be able to
+access the Radicale server directly. Otherwise, they can authenticate as
+any user.
+
+
+
+Secure connection between Radicale and the reverse proxy
+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.
+openssl req -x509 -newkey rsa:4096 -keyout server_key.pem -out server_cert.pem \
+ -nodes -days 9999
+openssl req -x509 -newkey rsa:4096 -keyout client_key.pem -out client_cert.pem \
+ -nodes -days 9999
Use the following configuration for Radicale:
+[server]
+ssl = True
+certificate = /path/to/server_cert.pem
+key = /path/to/server_key.pem
+certificate_authority = /path/to/client_cert.pem
If you're using the Let's Encrypt's Certbot, the configuration should
+look similar to this:
+[server]
+ssl = True
+certificate = /etc/letsencrypt/live/{Your Domain}/fullchain.pem
+key = /etc/letsencrypt/live/{Your Domain}/privkey.pem
Example nginx configuration:
+location /radicale/ {
+ proxy_pass https://localhost:5232/;
+ ...
+ # Place the files somewhere nginx is allowed to access (e.g. /etc/nginx/...).
+ proxy_ssl_certificate /path/to/client_cert.pem;
+ proxy_ssl_certificate_key /path/to/client_key.pem;
+ proxy_ssl_trusted_certificate /path/to/server_cert.pem;
+}
+
+
+
+WSGI Server
+Radicale 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.
+Example uWSGI configuration:
+[uwsgi]
+http-socket = 127.0.0.1:5232
+processes = 8
+plugin = python3
+module = radicale
+env = RADICALE_CONFIG=/etc/radicale/config
Example Gunicorn configuration:
+gunicorn --bind '127.0.0.1:5232' --env 'RADICALE_CONFIG=/etc/radicale/config' \
+ --workers 8 radicale
Manage user accounts with the WSGI server
+Set the configuration option type in the
+auth section to remote_user. Radicale uses the
+username provided by the WSGI server and disables authentication over
+HTTP.
+
+
+
+Versioning with Git
+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
+.Radicale.tmp-*
+The configuration option hook in the
+storage section must be set to the following command:
+git add -A && (git diff --cached --quiet || git commit -m "Changes by "%(user)s)
The command gets executed after every change to the storage and
+commits the changes into the git repository.
+For the hook to not cause errors either git user
+details need to be set and match the owner of the collections directory
+or the repository needs to be marked as safe.
+When using the systemd unit file from the Running as a service section this
+cannot be done via a .gitconfig file in
+the users home directory, as Radicale won't have read permissions!
+In /var/lib/radicale/collections/.git run:
+git config user.name "radicale"
+git config user.email "radicale@example.com"