1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<p align="center">
<img width="120" src="icon.svg" />
<h1 align="center">EteSync - Secure Data Sync</h1>
</p>
This is a CalDAV and CardDAV adapter for [EteSync](https://www.etesync.com)
[](https://pypi.python.org/pypi/etesync-dav/)
[](https://travis-ci.com/etesync/etesync-dav)
[](https://webchat.freenode.net/?channels=#etesync)
This package provides a local CalDAV and CardDAV server that acts as an EteSync compatibility layer (adapter).
It's meant for letting desktop CalDAV and CardDAV clients such as Thunderbird, Outlook and Apple Contacts connect with EteSync.
If all you want is to access your data from a computer, you are probably better off using [the web app](https://client.etesync.com).
**Note:** This software is still in beta. It should work well and is used daily by many users, but there may be some rough edges.
# Installation
The easiest way to start using etesync-dav is by getting one of the pre-built binaries from the [releases page](https://github.com/etesync/etesync-dav/releases).
These binaries are self-contained and can be run as-is, though they do not start automatically on boot. You'd need to either start them manually, or set up [autostart based on your OS](#autostart-on-system-boot).
# Configuration and running
1. Run `etesync-dav` and open the management UI in your browser: http://localhost:37358/
2. Add your EteSync user through the web UI.
3. Copy the DAV specific password by click the "Copy Password" button next to your newly added username.
For advanced usage and CLI instructions please refer to [the advanced usage section](#advanced-usage).
*Please note that some antivirus/internet security software may block the CalDAV/CardDAV service from running - make sure that etesync-dav is whitelisted.*
Don't forget to set up EteSync to automatically start on startup. Instructions for this are unfortunately OS dependent and out of scope for this README.
# Setting up clients
You now need to set up your CalDAV/CardDAV client using your username and the password you got in the previous step.
Depending on the client you use, the server path should either be:
* `http://localhost:37358/`
* `http://localhost:37358/user@example.com/`
On most clients this should automatically detect your collections (i.e.
calendars and address books).
If your client does not automatically detect your collections, you will
need to manually add them. You can find the links in the management UI
when you click on your username.
## Specific client notes and instructions
### Thunderbird
#### Thunderbird (using TbSync) - recommended
1. Install [TbSync](https://addons.thunderbird.net/en-us/thunderbird/addon/tbsync/) and the accompanying [DAV provider](https://addons.thunderbird.net/en-us/thunderbird/addon/dav-4-tbsync/).
2. Open the TbSync window: Edit -> TbSync
3. Add new DAV account (choose manual configuration).
4. Use `http://localhost:37358/user@example.com/` for both servers, your EteSync username as the username and the DAV password you got in [configuration and running](#configuration-and-running) as the password.
#### Thunderbird (no additional add-ons)
Using TbSync is recommended, because it includes address book support (Lightning does not), automatically discovers all your calendars/address books/tasks, and just works better in general. However, you *can* also do the following:
1. Install a CardDAV add-on such as Cardbook if you want to sync your contacts
2. Open http://localhost:37358 in a browser, log in with your username and account password (not encryption password), and click on the link to your DAV colection to see a list of all the calendars, tasks lists, and address books in that collection
3. For each item in the collection that you want to sync, copy the \[link] address and subscribe to that address in Thunderbird using `File > New Calendar > On the Network > CalDav` for calendars and tasks, or `New Address Book > Remote > CardDav` in Cardbook for address books
### Evolution / GNOME Calendar / GNOME Contacts
GNOME Calendar and Contacts do not support adding WebDAV calendars and address books directly, but you can add them in Evolution and they will appear correctly in all the apps.
1. Open Evolution and click File -> New -> Collection account
2. Put your username (user@example.com) in the user field.
3. Click Advanced Options and use `http://localhost:37358/` as the server.
4. Make sure "Look up for a CalDAV/CardDAV server" is ticked, and untick all the rest.
5. Click "Look Up" and when prompted, the DAV password you got in [configuration and running](#configuration-and-running).
6. Click Next/Finish until done.
### Windows 10 (Outlook, Windows Calendar and Windows People)
While EteSync-DAV works great on Windows 10, due to bugs in Windows itself, the instructions require a few extra steps for syncing with Outlook, Windows Calendar and Windows people. Other clients, such as Thunderbird, do no require these extra steps.
Please take a look at the [Windows 10 instructions](win10-instructions.md) for more information.
### macOS (Contacts.app and Calendar.app)
While EteSync-DAV works great on macOS, due to bugs in macOS Mojave, the instructions require a few extra steps for syncing with Contacts.app and Calendar.app. Other clients, such as Thunderbird, do no require these extra steps.
Please take a look at the [macOS instructions](macos-instructions.md) for more information.
### iOS
By default, iOS only syncs events 30 days old and newer, which may look as if
events are not showing. To fix this, got to: Settings -> Calendar -> Sync and
change to the wanted time duration.
Or better yet, just use the [EteSync iOS client](https://github.com/etesync/ios).
## Autostart on system boot
It's probably easiet to just follow [these instructions](https://www.howtogeek.com/228467/how-to-make-a-program-run-at-startup-on-any-computer/) for setting up autostart. Alternatively, you can try following the instructions below.
### Linux (systemd)
Make sure you have `/usr/lib/systemd/user/etesync-dav.service` on your system (should be there when installing from your distro's package manager), and then, to start the service:
`systemctl --user start etesync-dav`
To enable auto-start on boot:
`systemctl --user enable etesync-dav`
### macOS
Make sure you installed `etesync-dav.app` by dragging it to your `Applications` directory through finder.
Enable autostart by for example following [these instructions](https://www.howtogeek.com/228467/how-to-make-a-program-run-at-startup-on-any-computer/).
### Windows
Follow [these instructions](https://www.howtogeek.com/228467/how-to-make-a-program-run-at-startup-on-any-computer/).
# Alternative Installation Methods
This methods are not as easy as the pre-built binaries method above, but are also simple. Please follow the instructions below, following which follow the instructions in the [Configuration and running](#configuration-and-running) section below.
## Docker
Run one time initial setup to persist the required configuration into a docker volume. Check out the configuration section below for more information.
docker run -it --rm -v etesync-dav:/data etesync/etesync-dav manage add USER_EMAIL
Run etesync-dav in a background docker container with configuration from previous step. This wil (re)start the container on boot and after crashes.
docker run --name etesync-dav -d -v etesync-dav:/data -p 37358:37358 --restart=always etesync/etesync-dav
After this, refer to the [Setting up clients](#setting-up-clients) section below and start using it!
### Updating
To update to the latest version of the docker image, run:
docker pull etesync/etesync-dav
### Note for self-hosting:
If you're self-hosting the EteSync server, you will need to add the following before the `-v` in the above commands:
--env "ETESYNC_URL=https://your-etesync-url.com"
## Arch Linux
The package `etesync-dav` is [available on AUR](https://aur.archlinux.org/packages/etesync-dav/).
## Windows systems
You can either follow the Docker instructions above (get Docker [here](https://www.docker.com)), or alternatively install Python3 for windows from [here](https://www.python.org/downloads/windows).
## Python virtual environment (Linux, BSD and Mac)
Install virtual env (for **Python 3**) from your package manager, for example:
- Arch Linux: pacman -S python-virtualenv
- Debian/Ubuntu: apt-get install python3-virtualenv
The bellow commands will install etesync to a directory called `venv` in the local path. To install to a different location, just choose a different path in the commands below.
Set up the virtual env:
virtualenv -p python3 venv
source venv/bin/activate
pip install etesync-dav
Run the etesync commands as explained in the [Configuration and running](#configuration-and-running) section:
./venv/bin/etesync-dav manage ...
./venv/bin/etesync-dav ...
Please note that you'll have to run `source venv/bin/activate` every time you'd like to run the EteSync commands.
# Advanced usage
## CLI
1. Open a terminal and navigate to the binary's loctaion by typing `cd /path/to/file` (most likely `cd ~/Downloads`).
2. Rename the binary to `etesync-dav` for ease of use, by e.g: `mv linux-etesync-dav etesync-dav`
3. Make it executable: `chmod +x etesync-dav`
You need to first add an EteSync user using `./etesync-dav manage`, for example:
`./etesync-dav manage add user@example.com`
*Substitute `user@example.com` with the username or email you use with your
EteSync account or self-hosted server.*
and then run the server:
`./etesync-dav`
## Self-hosting
If you are self-hosting the EteSync server, you will need to set the
`ETESYNC_URL` environment variable to the URL of your server every time
you run etesync-dav.
By default it uses the official EteSync server at `https://api.etesync.com`.
## Using a proxy
EteSync-DAV should automatically use the system's proxy settings if set correctly. Alternatively, you can set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to manually set the proxy settings.
## Self Signed Certs
If the etesync backend server is using self signed certs, the DAV bridge may refuse to connect. To solve this, run the following commands prior to starting the DAV bridge.
`export REQUESTS_CA_BUNDLE=/path/to/your/certificate.pem`
or
`export SSL_CERT_FILE=/path/file.crt`
Alternatively, if the security of certificate is not an issue (say the server is on a private network and not publicly accessible), you can ignore the certificate completely with the following commands prior to starting the DAV bridge.
```bash
export CURL_CA_BUNDLE='';
export REQUESTS_CA_BUNDLE='';
```
## Config files
`etesync-dav` stores data in the directory specified by the `ETESYNC_CONFIG_DIR`
environment variable. This includes a database and the credentials cache.
This directory is not relocatable, so if you change
`ETESYNC_CONFIG_DIR` you will need to regenerate these files (which means
reconfiguring clients). It may be possible to manually edit these files to
the new path. Note that the database will just mirror the content of your
main EteSync database so in most cases you should not lose anything if you
delete it.
`ETESYNC_CONFIG_DIR` defaults to a subdirectory of the appropriate config directory
for your platform (`~/.config/etesync-dav` on Unix/Linux, see
[appdirs](http://pypi.python.org/pypi/appdirs) module docs for where it
will be on other platforms).
# Credits
This depends on the [Radicale server](http://radicale.org) for operation.
|
