How to Use Radicale: The Beginner's Guide to Self-Hosted Calendar and Contact Sync
CodexFuse Team · 2026-11-01T15:34:50.160Z · 14 min read
Learn how to use Radicale: install the self-hosted CalDAV/CardDAV server with Docker, create your first user, sync Android, iPhone and desktop, share calendars and back up.
Learning how to use Radicale means taking back your calendar and contacts from Google and Apple and running them on a server you own. Radicale is a tiny, free, open-source server that speaks the same calendar and contact sync standards your phone already understands, so your events and address book keep working everywhere while your data lives on your hardware. This radicale tutorial walks you through installing Radicale with Docker, creating your first user and calendar, connecting Android, iPhone and desktop clients, sharing a calendar with another person, and backing everything up — one complete beginner arc for a self-hosted calendar and self-hosted contacts, no gaps.
If you are brand new to containers, start with our Docker beginner guide first, because every step below runs Radicale as a Docker container. You will need a VPS or home server and a domain name for HTTPS.
What Is Radicale?
Radicale is a small, free, open-source CalDAV and CardDAV server that syncs your calendars, contacts and tasks across all your devices, storing everything as plain files with no database. CalDAV and CardDAV are the open standards behind calendar and contact sync: the same protocols iPhones, Android (through sync apps) and Thunderbird already speak. Your phone keeps its own calendar app; Radicale just becomes the central copy that everything syncs to instead of Google or iCloud.
The key mental model is this: as a dedicated CalDAV/CardDAV server, Radicale is the server, your devices are the clients, and the clients do all the work. Radicale 3.x ships a minimal built-in web page at its address for creating and managing calendars and address books, but there is no full calendar or contact editor UI — your real daily interface stays on your phone and desktop. That is by design: it keeps the server tiny and your data in standard .ics and .vcf files you can read, copy and back up with ordinary tools.
Before You Start: What You'll Need
You need a server that runs Docker and a domain name you can point at it. A small VPS is the classic choice, and our VPS hosting guide explains what that gives you if the term is new. You will run Radicale on port 5232 internally, then put it behind a reverse proxy with TLS — never expose port 5232 to the open internet without HTTPS and a password in front of it.
The current stable release is Radicale 3.9.0 (published 25 October 2026), and the de-facto Docker image is tomsquest/docker-radicale — the Radicale project itself ships no official container image. The image's latest tag rebuilds daily on Alpine for security patches, and version tags like 3.9.0.1 pin a Radicale version to an image revision. Pin a version tag for a server you depend on, so an update only happens when you decide.
How Do I Install Radicale with Docker?
You install Radicale with a single docker-compose file: this radicale install is one service, two volumes, one environment variable for the listen address. The radicale docker approach below is also the easiest to back up, because the whole server lives in one folder. The container runs as a non-root radicale user and keeps a read-only filesystem, so mounting a data directory and (optionally) a config file is the whole deployment.
Create a folder for Radicale and add a docker-compose.yml:
services:
radicale:
image: tomsquest/docker-radicale:3.9.0.1
container_name: radicale
restart: unless-stopped
ports:
- "127.0.0.1:5232:5232"
volumes:
- ./data:/data
environment:
- RADICALE_CONFIG_SERVER_HOSTS=0.0.0.0:5232
- RADICALE_CONFIG_AUTH_TYPE=htpasswd
- RADICALE_CONFIG_AUTH_HTPASSWD_FILENAME=/config/users
- RADICALE_CONFIG_AUTH_HTPASSWD_ENCRYPTION=autodetect
read_only: trueTwo lessons hide in this file. First, the data volume ./data:/data is the whole server: inside the image, Radicale's collections live at /data/collections, so this bind-mount is both the live storage and your backup source. Second, the config uses the image's env-var convention RADICALE_CONFIG_SECTION_KEY — here setting the server bind, the htpasswd auth backend, and the password-file encryption. You can mount a full config file at /config:ro instead if you outgrow env vars.
Start it with docker compose up -d. Note that Radicale binds to 127.0.0.1:5232 on the host side of the port mapping: even though the container listens on all interfaces, nothing outside this machine can reach it until you add the reverse proxy in a later step. That is deliberate defense in depth.
How Do I Create the First User in Radicale?
You create users with htpasswd against a password file Radicale reads, because since version 3.5.0 the default auth type is denyall — the server rejects every login until you explicitly configure an auth backend. (Before 3.5.0 there was no auth check by default, which the project flags as dangerous; if you followed an old tutorial, this is the change that breaks its login step.)
Install apache2-utils (Debian/Ubuntu) or httpd-tools (Fedora/RHEL) to get htpasswd, then create the users file inside the folder you mounted:
mkdir -p config
htpasswd -5 -c config/users [email protected]Use -5 for SHA-512 password hashing. On older distros whose htpasswd lacks SHA-512 (Ubuntu 22 LTS is one), use -B for bcrypt instead. To add more users later, run the same command without -c, because -c creates a fresh file and would wipe your existing users. Radicale 3.3.0 and newer default htpasswd_encryption to autodetect, so either hash works without extra config.
Lock down permissions: the storage directory should be owned by the radicale user with mode 750, and the users file 640, so only the server process can read your password hashes. Restart the container after changing auth settings — the auth backend is read at startup.
How Do I Create My First Calendar and Address Book?
You create your first calendar and address book in Radicale's minimal built-in web interface at http://localhost:5232, which the 3.x series provides for managing collections (an alternative UI called InfCloud can be embedded if you want more). SSH into the server with port forwarding or open it from a browser on the machine itself, log in with the user you just created, and add one calendar (for example "Personal") and one address book ("Contacts").
The important idea to internalize: a "collection" in Radicale is just a folder of .ics files (calendar) or .vcf files (contacts) on disk. There is no database row to corrupt and no web panel to babysit. Everything your clients do — create events, edit contacts — translates into file writes Radicale serves over CalDAV and CardDAV.
How Do I Put Radicale Behind HTTPS?
You put Radicale behind a reverse proxy with TLS because CalDAV and CardDAV clients send your password on every sync, and self-signed certificates break mobile sync. Our Caddy beginner guide walks through Caddy setup; the Caddyfile for Radicale is short:
cal.example.com {
reverse_proxy 127.0.0.1:5232
}With nginx the equivalent is a proxy_pass block plus Certbot for Let's Encrypt, and you should also add the .well-known redirects for caldav and carddav, which let clients auto-discover your server. iOS in particular has required real SSL since iOS 12 — a self-signed certificate pops a "Cannot Verify Server Identity" warning that you must tap through, and some clients refuse entirely.
One safety rule, once: never publish port 5232 directly to the internet without the reverse proxy and its auth in front. The bind in the compose file (127.0.0.1:5232) already keeps Radicale local-only; keep it that way.
How Do I Sync Radicale on Android with DAVx5?
You sync Radicale on Android with DAVx5, because stock Android has no native CalDAV/CardDAV support — Google deliberately routes you through its servers. DAVx5 (current release 4.5.10) is the open-source sync adapter that bridges that gap, and this radicale android setup is the single most-used Radicale client configuration, so the steps matter. The radicale davx5 combination keeps working even when Google changes its own sync rules, because nothing in this sync path depends on Google.
Install DAVx5 from F-Droid or Google Play, tap the plus button to add an account, choose "Login with URL and username," and enter your base URL (https://cal.example.com/) plus your username and password. DAVx5 discovers your calendars and address books automatically, then lets you tick exactly which ones sync. It writes into Android's calendar provider, so after setup your ordinary calendar app — Google Calendar, Samsung Calendar, whatever you use — shows Radicale events alongside everything else, with no Google account involved in the sync path.
If you would rather skip opening anything to the internet at all, our Tailscale beginner guide shows how to reach Radicale over a private mesh network instead: same DAVx5 base-URL step, but the URL stays yours alone.
How Do I Set Up Radicale on iPhone?
You set up Radicale on iPhone with iOS's native CalDAV and CardDAV accounts — this radicale iphone setup needs no extra app. For calendars, open Settings, go to Calendar (listed under Apps on recent iOS), then Calendar Accounts → Add Account → Other → Add CalDAV Account, and enter your server domain, username and password. For contacts, go to Settings → Contacts → Contacts Accounts → Add Account → Other → Add CardDAV Account, with the same details.
iOS sends each sync over HTTPS and requires a valid certificate (Let's Encrypt from the previous step), so this is where the reverse proxy earns its keep. iOS syncs both calendars and address books to the stock Calendar and Contacts apps, and reminders flow through the CalDAV task support Radicale includes.
How Do I Connect Radicale to Thunderbird on the Desktop?
You connect Thunderbird's calendar over CalDAV and its address book over CardDAV, which Thunderbird supports natively. Open the Calendar tab, click New Calendar in the lower-left (or File → New → Calendar), choose "On the Network," select the CalDAV format, enter your username and the location URL, click Find Calendars, enter your password when prompted, and subscribe. For contacts, open the Address Book, create a new address book, choose "Add CardDAV Address Book," and enter the server URL, username and password.
GNOME users can do the same through Settings → Online Accounts by adding a generic CalDAV/CardDAV account with the server URL. Radicale's documentation also lists the CardBook add-on route for Thunderbird if you want a more capable contact editor than the built-in address book.
How Do I Share a Calendar with Another User?
You share a Radicale calendar with another user using the native sharing introduced in Radicale 3.7.0, configured through a [sharing] section in the config, or with filesystem symlinks between users' collections for the simplest family setup. This is the feature people graduate to after their own sync works — a shared family calendar or a team on-call calendar.
The 3.7.0+ native mechanism supports token-based and map-based sharing, stores its state in a small database inside your storage folder ((filesystem_folder)/collection-db/sharing.csv for the csv type, or a files type instead), and is disabled by default — you opt in per deployment. The low-tech alternative is symlinking: inside each user's collection folder, link the shared calendar into the other user's collection directory, and both accounts see it.
One caution, once: the 3.8.x and 3.9.0 releases included security fixes in group-based sharing (the 3.8.3 release fixed auth issue FO-RAD-2026-001 and the 3.9.0 notes urge anyone using sharing, group-based permissions or the login cache to update immediately). If multiple people log into your Radicale, treat updates like patches, not chores.
How Do I Back Up Radicale?
You back up Radicale by copying the collections directory, because there is no database to dump. Every calendar is a directory of .ics files, every address book a directory of .vcf files, and every contact and event is a human-readable text file. The plain-text backup rule is: whatever you would do with a folder of documents, do that with /data/collections.
rsync -a --delete /srv/radicale/data/collections/ /backup/radicale-collections/That one command is a complete, restorable backup — copy the folder back and you are done. For versioned history, Radicale supports a post-change hook you can point at a git commit, giving you an event-by-event timeline of your calendar for free. Run the rsync on a cron schedule and keep an off-site copy, and your self-hosted calendar is more durable than most cloud ones.
Radicale vs Baïkal vs Nextcloud: Which Should a Beginner Pick?
Radicale is one of three common self-hosted sync answers, and the right one depends on how much server you want to run. Baïkal is the closest alternative: a lightweight PHP (sabre/dav) CalDAV/CardDAV server, currently at version 0.13.0, that ships a web admin panel for managing users, calendars and address books — pick it if you want GUI administration and already run Apache or nginx. Nextcloud is a full cloud suite whose Calendar and Contacts apps expose standards-compliant CalDAV/CardDAV at /remote.php/dav/, so the exact same client setup in this guide works against it — but you pay for it with a much heavier footprint.
| Server | Language / stack | Admin UI | Best for |
|---|---|---|---|
| Radicale | Python daemon, plain-file storage | Minimal collection manager | Beginners who want one tiny service on a VPS |
| Baïkal | PHP (sabre/dav), runs under Apache/nginx | Full web admin panel | Beginners who want point-and-click user management |
| Nextcloud | PHP cloud suite | Complete web suite | People who also want files, photos and office apps under one login |
The honest graduation line, once: if you ever need files, photos and mobile apps under one login, Nextcloud is the upgrade path and your Radicale clients keep working against it unchanged. Until then, Radicale's one-container footprint is the lighter, faster choice.
Common Beginner Mistakes
| Mistake | Why it happens | The fix |
|---|---|---|
| Login fails right after install | Radicale 3.5.0+ defaults auth to denyall | Set [auth] type = htpasswd and create the users file |
| htpasswd -c wipes all users | -c creates a fresh file every time | Add users after the first one without -c |
| Android shows no calendars | Stock Android has no native CalDAV/CardDAV | Install DAVx5 and use "Login with URL and username" |
| iPhone refuses to connect | Self-signed or missing TLS certificate | Put Radicale behind a real Let's Encrypt certificate |
| Port 5232 exposed directly | Port mapping published 0.0.0.0:5232 | Bind 127.0.0.1:5232 and use a reverse proxy |
| Latest tag breaks on update | latest rebuilds daily with new versions | Pin a version tag like 3.9.0.1 and update on purpose |
| Skipping updates with shared users | Sharing code had security fixes in 3.8.x/3.9.0 | Update promptly when multiple people log in |
Your First Sync: The 8-Step Arc
- Install Docker on your VPS or home server
- Deploy Radicale with the docker-compose file above and pin the version tag
- Create your first user with
htpasswd(remember: no-cafter the first user) - Add your first calendar and address book at
http://localhost:5232 - Put Radicale behind HTTPS with a reverse proxy — never expose port 5232 directly
- Connect your phone: DAVx5 with "Login with URL and username" on Android, native CalDAV/CardDAV accounts on iPhone
- Connect your desktop: Thunderbird's CalDAV calendar and CardDAV address book
- Copy the collections directory with rsync — that copy is your complete first backup
Sources
- Radicale official documentation, v3 configuration — https://radicale.org/v3.html
- tomsquest/docker-radicale, GitHub (1,113 stars, image tags and config convention) — https://github.com/tomsquest/docker-radicale
- Radicale v3.9.0 release, published 2026-10-25 — https://newreleases.io/project/github/Kozea/Radicale/release/v3.9.0
- Arch Linux package: radicale 3.9.0-1, packaged 2026-10-31 — https://archlinux.org/packages/extra/any/radicale/
- DAVx5 manual, introduction — https://manual.davx5.com/introduction.html
- DAVx5 on Google Play (v4.5.10, updated Mar 2026) — https://play.google.com/store/apps/details?id=at.bitfire.davdroid
- Nextcloud docs: syncing iOS — https://docs.nextcloud.com/server/latest/user_manual/en/groupware/sync_ios.html
- mailbox.org knowledge base: CalDAV/CardDAV for iOS and macOS — https://kb.mailbox.org/en/business/addressbook-and-calendar/caldav-and-carddav-for-mac-os-and-ios/
- hostpoint: setting up calendar and contact synchronization (CalDAV/CardDAV) — https://support.hostpoint.ch/en/products/cloud-office/frequently-asked-questions/setting-up-calendar-and-contact-synchronization-caldav-carddav
- Zoho Calendar help: CalDAV sync setup — https://www.zoho.com/calendar/help/setup-caldav-sync.html
- Baïkal 0.13.0, FreshPorts (packaged 2026-10-26) — https://www.freshports.org/www/baikal/
- ssdnodes: self-hosted calendar server with CalDAV — https://www.ssdnodes.com/learn/self-hosted-calendar-server-caldav
- landchad.net: Radicale guide — https://landchad.net/radicale/
- taborsky.cz: self-hosted calendar and contacts with Radicale — https://taborsky.cz/posts/2019/selfhosted-calendar-contacts/
- naut.ca: self-hosting series part 3, Radicale server — https://www.naut.ca/blog/2019/11/16/self-hosting-series-part-3-radicale-server/
- gofoss.net: contacts, calendars and tasks (book chapter) — https://gofoss.net/contacts-calendars-tasks/
Frequently Asked Questions
Is Radicale free to use?
Yes. Radicale is free and open-source software you run on your own server, so there are no accounts, tiers or subscriptions — your only cost is the VPS or hardware you already have.
Does Radicale have a web interface?
Radicale 3.x ships a minimal built-in web page for creating and managing calendars and address books, and InfCloud can be embedded for a richer view, but there is no full calendar or contact editor UI. Your phone and desktop clients are the real interface.
How is Radicale different from Nextcloud?
Radicale is a single-purpose CalDAV/CardDAV sync server with a one-container footprint, while Nextcloud is a full cloud suite with files, photos and apps. Both speak the same sync standards, so the client setup in this guide works against either.
Can I migrate my Google Calendar to Radicale?
Yes. If your goal is to replace Google Calendar sync entirely, export your Google calendars as .ics files from Google Calendar settings, then import each file into your Radicale calendar using any CalDAV client (Thunderbird's calendar import works well). Contacts export as a single .vcf from Google Contacts and import the same way.
Do I need a domain name for Radicale?
Technically no — DAVx5 and other clients can reach an IP address — but a domain name with Let's Encrypt TLS is strongly recommended. iOS requires real SSL for CalDAV/CardDAV accounts, and exposing sync over plain HTTP sends your password in the clear.
