Address book

Give this sync'ed contacts list/address book/digital rolodex a try. We use this exact protocol (CardDAV) for many simple, sharable people directory needs, and it has made our lives so much easier. This is a one-time setup situation that you barely have to think about after it's done.

TK-TODO: Write an introduction?

Background

All corporate services (Google Contacts, Apple iCloud Contacts, etc.) use a publicly available, standard protocol for communicating about actors such as people or organizations called CardDAV, the Calendaring extensions to the Web-based Distributed Authoring and Versioning protocol. When you’re using Google Contacts, you’re using CardDAV. But you can use CardDAV without using Google (or Apple, Microsoft, etc.) by replacing your Google-provided applications with one or more of the many alternative free software programs capable of providing the same CardDAV features. This guide shows you how.

Instructions

This section describes the general process of setting up software that understands CardDAV. We call these various software tools “CardDAV clients” or “CardDAV servers.” In most cases, you will only have to concern yourself with learning to use one CardDAV client. People who wish to administer a shared calendar service for their comrades will also need to familiarize themselves with at least one CardDAV server.

Client setup

This section describes setting up a client for a CardDAV account. Please note the following before you begin:

  • You almost certainly already have a CardDAV client available to you on your existing smartphone or laptop computer; most people will likely have no need to download and install an additional app. That said, you are welcome to choose the software you prefer, and can generally mix-and-match such softwares as you wish.
  • You will need access to a CardDAV server. If you were pointed at this page by a comrade, that comrade may already have set up a CardDAV server for you to use. If not, see the Server setup section for some guidance regarding how to set up your own CardDAV server.
  • The guidance in this section assumes you (i.e., the client) are not using the privacy-enhancing overlay network known as Tor. Please see the CardDAV over Tor subsection(s) for additional guidance regarding how to make your client application(s) work while connecting through the Tor network.

Apple Contacts

macOS computers supply an application called Contacts as part of their base system. If you have a Mac, you already have the “Contacts” app, which is a CardDAV client. This means you already have everything you need to use a CardDAV shared address book (including Google Contacts, but also any other CardDAV service).

Do this to add a CardDAV address book to your macOS computer:

  1. Open the “Contacts” application (Contacts.app) on your computer. You can do this by searching for “Contacts” from a Spotlight search, or navigate to the /Applications folder in a Finder window.
  2. Go to the application menu (the one that reads Contacts), and select Add Account…. The “Choose a Contacts account provider…” sheet will appear.
  3. Select the option that reads Other Contacts Account… and then click Continue. The “Add a Contacts account” sheet will appear.
  4. From the Account Type drop-down menu, choose Manual. You will be presented with three text fields asking for your CardDAV account details, labelled:
    1. User Name – This is your account’s username. This is usually your email address or a name you chose. (For a Sandstorm-provided account, it will probably be sandstorm).
    2. Password – This is your account’s password. This is almost always something you chose. (For a Sandstorm-provided account, it will be a randomly generated string available from the Web Browser interface of the Radicale grain.)
    3. Server Address – This is the address of the CardDAV server itself; this will be provided to you by your system administrator or the service you use. (For a Sandstorm-provided account, it will be a regular Web address—i.e., a URL—findable by clicking the small cloud icon to the left of the Web Browser interface of the Radicale grain.)
  5. Press the Sign In button on the “Add a Contacts account” sheet. Your new address book will appear in the Apple Contacts application’s sidebar.

Mozilla Thunderbird

Mozilla Thunderbird is a free, cross-platform personal information manager, which is also a CardDAV client. You can use it as an alternative to Apple Contacts on macOS, or to Microsoft Outlook on Windows, as well as on GNU/Linux.

Do this to add a CardDAV address book to your computer with Mozilla Thunderbird:

  1. Open Mozilla Thunderbird on your computer.
    1. If this is your first time running Thunderbird, it will prompt you to make a new email address or use your existing address. You can do this if you want, but for the purposes of CardDAV it is unnecessary, so you can just click “I think I’ll configure my account later.”
  2. Install the CardBook add-on to Thunderbird:
    1. From the Tools menu, choose Add-ons.
    2. Click on Extensions in the left-hand sidebar.
    3. In the search field, enter CardBook.
    4. Click the Install button next to the CardBook add-on.
    5. Click on Restart now to restart Thunderbird and load the CardBook add-on.
  3. Click on the “Contacts” icon near the upper-right corner of the Thunderbird window to view Thunderbird’s CardBook address book interface.
  4. Right click below the Address Books menu and click New Address Book. The “Add a new address book” dialogue will appear.
  5. Under the Address book location: field set, choose Remote, and then press the Continue button.
  6. In the Type field set, choose CardDAV.
    1. In the Location text field, put the address of the CardDAV server itself; this will be provided to you by your system administrator or the service you use. (For a Sandstorm-provided account, it will be a regular Web address—i.e., a URL—findable by clicking the small cloud icon to the left of the Web Browser interface of the Radicale grain.)
    2. In the Username field, enter your account’s username. This is usually your email address or a name you chose. (For a Sandstorm-provided account, it will probably be sandstorm).
    3. In the Password field, enter your account’s password. This is almost always something you chose. (For a Sandstorm-provided account, it will be a randomly generated string available from the Web Browser interface of the Radicale grain.)
    4. Click the Validate button. This will test your connection settings and, when successful, will enable the Continue button, which you should click.
  7. In the next screen, choose a meaningful Name and your preferred Color for the address book. (Leave the other settings at their default values.)
  8. After clicking Continue, then clicking Done, your new address book should appear!

Mozilla Thunderbird with Tor

Additional configuration steps are required for Mozilla Thunderbird to successfully route its requests through the Tor privacy-enhancing overlay network. Note that if you will be accessing an authenticated Tor Onion service ("hidden service"), you will also need to configure your Tor client itself.

Do this to have Mozilla Thunderbird connect to servers over Tor:

  1. Download and install the Tor Browser. The Tor Browser installer contains a Web browser and bundles the complete Tor software along with it.
  2. Open (launch) the Tor Browser. To use your CardDAV client through Tor, the Tor Browser must be open and running at all times.
  3. Open (launch) Mozilla Thunderbird, if it is not already open.
  4. Configure Thunderbird to use a SOCKS proxy from its Preferences window, which is accessible under the Thunderbird (macOS) or Tools (Windows and GNU/Linux) menu, depending on your Operating System:
    1. Click on the Advanced pane.
    2. Click on the Network & Disk Space tab.
    3. Under the Connection heading, click the Settings… button. The “Configure Proxies to Access the Internet” sheet will appear:
      1. Choose the Manual proxy configuration radio button.
      2. For SOCKS Host, enter 127.0.0.1.
      3. For Port, enter 9150; this is the default port number used by Tor Browser. If your Tor uses a different SocksPort, you should enter it here.
      4. Choose the SOCKS v5 radio button.
      5. Press the OK button to save your new settings.
  5. Configure Thunderbird to use the same SOCKS proxy for its DNS resolution queries; this is required to access CardDAV servers running as Tor Onion services (i.e., servers available at domain names that end in .onion addresses).
    1. From Thunderbird’s Preferences window:
      1. Click on the Advanced pane.
      2. Click on the General tab. (Do not confuse this with the “General” pane.)
      3. Click on the Config Editor… button. Thunderbird’s about:config interface will appear.
        1. If this is the first time you have opened the Config Editor, you may be presented with a warning telling you that you will “void your warranty” if you continue. This is a joke in arguably poor taste; Mozilla Thunderbird provides users with no warranties of any kind, and never has. Proceed through the warning to access the Config Editor.
        2. In the Search field, enter network.proxy.socks_remote_dns to filter the advanced configuration options down to this specific option:
        3. Double-click on the network.proxy.socks_remote_dns line item to toggle its value from false to true:
  6. Close (quit) and re-open (launch) Mozilla Thunderbird again.

iOS

TK-TODO

Android-based phone

Most Android smartphones come with an address book application, typically called “Contacts,” but out-of-the-box support for CardDAV sync features is arbitrarily limited to technocapitalist products such as Google Calendar that demand possession of all your data (which is why we call them “possessors”). Thankfully, several free software alternatives exist for Android, but you will need to install them yourself. This section shows you how.

Overview for Android:

  1. Install F-Droid
  2. Install DAVdroid
  3. Configure DAVdroid

Install F-Droid

F-Droid is an app store for Android phones, much like the Google Play Store, but enhanced with a number of important features. It gives you access to numerous apps that you would otherwise have to pay for if you bought them on the Google Play Store, as well as additional apps not available on the Play Store because their developer cannot afford the listing fee Google requires to list apps in the Play Store in the first place. Moreover, F-Droid also allows you to share an app without the Internet; if you and a friend both have F-Droid installed, but you have an app your friend doesn’t, your friend can get the app onto their phone from your phone instead of from a far away device across the Internet.

Installing F-Droid from the Internet

If you don’t have a friend with F-Droid installed on their phone physically near you already, you need to get F-Droid from the Internet.

Do this to download and install F-Droid from the Internet:

  1. In your phone’s Web browser, visit F-Droid.org. The F-Droid homepage will load.
  2. Click the Download F-Droid button on the F-Droid homepage. The F-Droid installation package for Android (.apk file) will be downloaded to your phone.
  3. Open the downloaded installer package using the notification shade or any file manager. Your phone’s package installer will open.
  4. If this is the first time you’ve tried to install an app from somewhere other than the Google Play Store, you will see a dialogue box that reads something like “For security, your phone is set to block installation of apps obtained from unknown sources.” If you see this, Tap the Settings button to go to the Security section of your phone’s system settings.
    1. Toggle the Unknown sources option on (enable it). This allows you to install software from downloaded files. After you finish this procedure, we recommend that you return here and toggle the option back off.
    2. Return to your file manager and re-open the F-Droid installer package.
  5. Tap Install to install F-Droid.
Installing F-Droid from a friend’s phone
TK-TODO

Install DAVdroid

DAVdroid is a CardDAV client that integrates well with the built-in address book applications on Android phones. It is available for purchase from the Google Play Store and is available for free from the free software F-Droid catalog. We recommend you install DAVdroid from the free software F-Droid catalog. If you don’t have F-Droid yet, install F-Droid first, then return here.

Do this to install DAVdroid:

  1. Open the F-Droid app on your phone.
  2. Tap the magnifying glass icon and search for DAVdroid, then tap on the DAVdroid search result to view the DAVdroid package detail screen.
  3. Tap the Install button to download DAVdroid from the Internet and attempt to install it. The package installer will open.
  4. If this is the first time you’ve tried to install an app from somewhere other than the Google Play Store, you will see a dialogue box that reads something like “For security, your phone is set to block installation of apps obtained from unknown sources.” If you see this, Tap the Settings button to go to the Security section of your phone’s system settings.
    1. Toggle the Unknown sources option on (enable it). This allows you to install software from downloaded files. After you finish this procedure, we recommend that you return here and toggle the option back off.
    2. Return to F-Droid’s package detail page and tap the Install button again.

Configure DAVdroid

Do this to configure DAVdroid to sync with a CardDAV server:

  1. Open the DAVdroid app on your phone.
  2. Tap the + (add new account) button. The “Add Account” activity screen will open.
  3. Tap Login with URL and user name. Three text fields will appear:
    • Base URL is the server address of the CardDAV server; this will be provided to you by your system administrator or the service you use. (For a Sandstorm-provided account, it will be a regular Web address—i.e., a URL—findable by clicking the small cloud icon to the left of the Web Browser interface of the Radicale grain.)
    • User name is your CardDAV account’s username; this is usually your email address or a name you chose. (For a Sandstorm-provided account, it will probably be sandstorm).
    • Password is your CardDAV account’s password; this is almost always something you chose. (For a Sandstorm-provided account, it will be a randomly generated string available from the Web Browser interface of the Radicale grain.)
  4. Tap the Login button. The “Create Account” screen will appear.
  5. Give the account a meaningful name.
  6. Tap the Create Account button. The DAVdroid main activity screen will appear.
  7. Tap the account you created. The account detail screen will appear, showing a list of the address books available to your account.
  8. Tap the checkbox next to the address books you want to synchronize to your phone from the CardDAV server.
  9. Tap the “Synchronize now” button to begin syncing. DAVdroid will now periodically check for updates to the selected calendar(s).

Your smartphone’s built-in address book application should now be able to display contacts from the synchronized address book. If you have permission to make changes to the contacts in the address book, you can use your smartphone’s built-in address book application to update the synchronized address book, as well.

Server setup

TK-TODO

Self-hosted Radicale instance as a Tor Onion service

See Radicale.

Radicale+InfCloud on Sandstorm

TK-TODO

See also

Calendar
Digital calendars, journals, and task lists (using CalDAV).