Debian Codegraph @

manual/server.rst

raw
1 The calibre Content server
2 ==============================
3
4 The calibre :guilabel:`Content server` allows you to access your calibre
5 libraries and read books directly in a browser on your favorite mobile phone or
6 tablet device. As a result, you do not need to install any dedicated book
7 reading/management apps on your phone. Just use the browser. The server
8 downloads and stores the book you are reading in an off-line cache so that you
9 can read it even when there is no internet connection.
10
11 .. contents:: Contents
12 :depth: 2
13 :local:
14
15 To start the server, click the :guilabel:`Connect/share` button and choose
16 :guilabel:`Start Content server`. You might get a message from your computer's
17 firewall or anti-virus program asking if it is OK to allow access to
18 ``calibre.exe``. Click the ``Allow`` or ``OK`` button. Then open a browser
19 (preferably Chrome or Firefox) in your computer and type in the following
20 address:
21
22 http://127.0.0.1:8080
23
24 This will open a page in the browser showing you your calibre libraries, click
25 on any one and browse the books in it. Click on a book, and it will show you
26 all the metadata about the book, along with buttons to :guilabel:`Read` and
27 :guilabel:`Download` the book. Click the :guilabel:`Read` button to start
28 reading the book.
29
30 .. note:: The address used above ``http://127.0.0.1:8080`` will only work on
31 the computer that is running calibre. To access the server from other
32 computers/phones/tablets/etc. you will need to do a little more work,
33 as described in the next section.
34
35
36 Accessing the Content server from other devices
37 ---------------------------------------------------
38
39 There are two types of remote device access that you will typically need. The
40 first, simpler kind is from within your home network. If you are running
41 calibre on a computer on your home network and you have also connected your
42 other devices to the same home network, then you should be easily able to
43 access the server on those devices.
44
45 Accessing the server from devices on your home network
46 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
47
48 After starting the server in calibre as described above, click the
49 :guilabel:`Connect/share` button again. Instead of the :guilabel:`Start Content
50 server` action, you should see a :guilabel:`Stop Content server` action
51 instead. To the right of this action will be listed an IP address
52 and port number. These look like a bunch of numbers separated by periods. For
53 example::
54
55 Stop Content server [192.168.1.5, port 8080]
56
57 These numbers tell you what address to use to connect to the server in your
58 devices. Following the example above, the address becomes::
59
60 http://192.168.1.5:8080
61
62 The first part of the address is always ``http://`` the next part is the IP
63 address, which is the numbers before the comma and finally we have the port
64 number which must be added to the IP address with a colon (``:``). If you are
65 lucky, that should be all you need and you will be looking at the
66 calibre libraries on your device. If not, read on.
67
68
69 Trouble-shooting the home network connection
70 __________________________________________________
71
72 If you are unable to access the server from your device, try the following
73 steps:
74
75 #. Check that the server is running by opening the address
76 ``http://127.0.0.1:8080`` in a browser running on the same computer as
77 the server.
78
79 #. Check that your firewall/anti-virus is allowing connections to your
80 computer on the port ``8080`` and to the calibre program. The
81 easiest way to eliminate the firewall/anti-virus as the source of
82 problems is to temporarily turn them both off and then try connecting. You
83 should first disconnect from the internet, before turning off the
84 firewall, to keep your computer safe.
85
86 #. Check that your device and computer are on the same network. This means
87 they should both be connected to the same wireless router. In particular
88 neither should be using a cellular or ISP provided direct-WiFi connection.
89
90 #. If you have non-standard networking setup, it might be that the IP
91 address shown on the :guilabel:`Connect/share` menu is incorrect.
92 In such a case you will have to figure out what the correct IP address
93 to use is, yourself. Unfortunately, given the infinite diversity of
94 network configurations possible, it is not possible to give you a
95 roadmap for doing so.
96
97 #. If you have set up a username and password, first try it without that
98 to see if it is causing issues. Some e-ink devices have browsers that
99 do not handle authentication. You can sometimes workaround this by
100 including the username and password in the URL, for example:
101 ``http://username:[email protected]:8080``.
102
103 #. If you are stuck, you can always ask for help in the `calibre user forums`_.
104
105
106 Accessing the server from anywhere on the internet
107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
108
109 .. warning::
110
111 Before doing this you should turn on username/password protection in the
112 server, otherwise anyone in the world will be able to access your books.
113 Go to :guilabel:`Preferences->Sharing->Sharing over the net` and enable the
114 option to :guilabel:`Require username and password to access the content
115 server`.
116
117 While the particular details on setting up internet access vary depending on
118 the network configuration and type of computer you are using, the basic schema
119 is as follows.
120
121 #. Find out the external IP address of the computer you are going to run the
122 server on. You can do that by visiting the site `What is my IP address
123 <https://www.whatismyip.com/>`_ in a browser running on the computer.
124
125 #. If the computer is behind a router, enable port forwarding on the router
126 to forward the port ``8080`` (or whatever port you choose to run the
127 calibre Content server on) to the computer.
128
129 #. Make sure the calibre server is allowed through any firewalls/anti-virus
130 programs on your computer.
131
132 #. Now you should be able to access the server on any internet-connected
133 device using the IP address you found in the first step. For example,
134 if the IP address you found was ``123.123.123.123`` and the port you are
135 using for the calibre server is ``8080``, the address to use on your
136 device becomes: ``http://123.123.123.123:8080``.
137
138 #. Optionally, use a service like `no-ip <https://www.noip.com/free>`_ to
139 setup an easy to remember address to use instead of the IP address you
140 found in the first step.
141
142
143 .. _cs_https_mode:
144
145 .. note::
146 For maximum security, you should also enable HTTPS on the Content server.
147 You can either do so directly in the server by providing the path to
148 the HTTPS certificate to use in the advanced configuration options for
149 the server, or you can set up a reverse proxy as described below, to use
150 an existing HTTPS setup.
151
152
153 The server interface
154 -----------------------
155
156 The server interface is a simplified version of the main calibre interface,
157 optimised for use with touch screens. The home screen shows you books
158 you are currently reading as well as allowing you to choose a calibre library you
159 want to browse. The server in calibre gives you access to all your libraries,
160 not just a single one, as before.
161
162 The book list
163 ^^^^^^^^^^^^^^
164
165 The server book list is a simple grid of covers. Tap on a cover to see the
166 detailed metadata for a book, or to read the book. If you prefer a more
167 detailed list, you can change the default view by clicking the three vertical
168 dots in the top right corner.
169
170 Sorting and searching of the book list should be familiar to calibre users.
171 They can be accessed by clicking their icons in the top right area. They both
172 work exactly the same as in the main calibre program. The search page even
173 allows you to construct search queries by clicking on authors/tags/etc., just as
174 you can using the Tag browser in the main program.
175
176 A much loved feature of the main program, :guilabel:`Virtual libraries` is
177 present in the server interface as well. Click the three vertical dots in the
178 top right corner to choose a Virtual library.
179
180 The book viewer
181 ^^^^^^^^^^^^^^^^
182
183 You can read any book in your calibre library by simply tapping on
184 it and then tapping the :guilabel:`Read` button. The book viewer
185 is very simple to operate. You can both tap and swipe to turn pages. Swiping
186 up/down skips between chapters. Tapping the top quarter of the screen gets you
187 the detailed controls and viewer preferences.
188
189 If you leave the Content server running, you can even open the same book on
190 multiple devices and it will remember your last read position. If it does not
191 you can force a sync by tapping in the top quarter and choosing
192 :guilabel:`Sync`.
193
194 Browser support
195 ------------------
196
197 The new calibre server makes lots of use of advanced HTML 5 and CSS 3 features.
198 As such it requires an up-to-date browser to use. It has been tested on Android
199 Chrome and iOS Safari as well as Chrome and Firefox on the desktop.
200
201 The server is careful to use functionality that has either been already
202 standardised or is on the standards track. As such if it does not currently
203 work with your favorite browser, it probably will once that browser has caught
204 up.
205
206 If you are using a particularly old or limited browser or you don't like to run
207 JavaScript, you can use the *mobile* view, by simply adding ``/mobile`` to the
208 server address.
209
210 .. note::
211 On iOS, Apple allows only a single browser engine, so Firefox, Chrome and
212 Safari are all actually the same browser under the hood. The new server
213 interface requires iOS 10.3.2 or newer. On Android, the server has been
214 tested with Chrome version 58 and newer.
215
216 Enabling offline support
217 ---------------------------
218
219 The server has full support for offline mode, you can open a book and once it
220 is loaded, continue reading it offline. However, typical browsers require the
221 use of HTTPS connections to enable offline mode (service workers).
222 So :ref:`setup HTTPS support <cs_https_mode>` as described above. Scroll to the
223 bottom of the home page and you will see a message about the status of offline
224 mode.
225
226 Alternately, you can open a book and keep the browser tab open. As long as the
227 tab stays open you can continue reading the book, even when offline.
228
229 Managing user accounts from the command-line only
230 -----------------------------------------------------
231
232 The calibre program has a nice section in :guilabel:`Preferences` to allow you
233 to manage user accounts for the server. However, if you want to run the
234 standalone server and cannot run the main calibre program on the same
235 computer/user account, you can also manage users using just the command-line.
236
237 You can manage user accounts using the ``--manage-users`` option
238 to the standalone ``calibre-server`` program. Suppose you want to store
239 the user database in the folder ``/srv/calibre``, then you create it
240 by running::
241
242 calibre-server --userdb /srv/calibre/users.sqlite --manage-users
243
244 Just follow the prompts to create user accounts, set their permissions, etc.
245 Once you are done, you can run the server as::
246
247 calibre-server --userdb /srv/calibre/users.sqlite --enable-auth
248
249 It will use the user accounts you created in the previous step.
250
251
252 Integrating the calibre Content server into other servers
253 ------------------------------------------------------------
254
255 Here, we will show you how to integrate the calibre Content server into another
256 server. The most common reason for this is to make use of SSL or to serve the
257 calibre library as part of a larger site. The basic technique is to run the
258 calibre server and set up a reverse proxy to it from the main server.
259
260 A reverse proxy is when your normal server accepts incoming requests and passes
261 them onto the calibre server. It then reads the response from the calibre
262 server and forwards it to the client. This means that you can simply run the
263 calibre server as normal without trying to integrate it closely with your main
264 server.
265
266 Using a full virtual host
267 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268
269 The simplest configuration is to dedicate a full virtual host to the calibre
270 server. In this case, run the calibre server as::
271
272 calibre-server
273
274 Now setup the virtual host in your main server, for example, for nginx::
275
276 http {
277 client_max_body_size 64M; # needed to upload large books
278 }
279
280 server {
281 listen [::]:80;
282 server_name myserver.example.com;
283
284 location / {
285 proxy_pass http://127.0.0.1:8080;
286 }
287 }
288
289 Or, for Apache::
290
291 LoadModule proxy_module modules/mod_proxy.so
292 LoadModule proxy_http_module modules/mod_proxy_http.so
293
294 <VirtualHost *:80>
295 ServerName myserver.example.com
296 AllowEncodedSlashes On
297 ProxyPreserveHost On
298 ProxyPass "/" "http://localhost:8080/"
299 </VirtualHost>
300
301
302
303 Using a URL prefix
304 ^^^^^^^^^^^^^^^^^^^^^^^
305
306 If you do not want to dedicate a full virtual host to calibre, you can have it
307 use a URL prefix. Start the calibre server as::
308
309 calibre-server --url-prefix /calibre --port 8080
310
311 The key parameter here is ``--url-prefix /calibre``. This causes the Content server to serve all URLs prefixed by ``/calibre``. To see this in action, visit ``http://localhost:8080/calibre`` in your browser. You should see the normal Content server website, but now it will run under ``/calibre``.
312
313 With nginx, the required configuration is::
314
315 http {
316 client_max_body_size 64M; # needed to upload large books
317 }
318
319 proxy_set_header X-Forwarded-For $remote_addr;
320 location /calibre/ {
321 proxy_buffering off;
322 proxy_pass http://127.0.0.1:8080$request_uri;
323 }
324 location /calibre {
325 # we need a trailing slash for the Application Cache to work
326 rewrite /calibre /calibre/ permanent;
327 }
328
329
330 For Apache, first enable the proxy modules in Apache, by adding the following to :file:`httpd.conf`::
331
332 LoadModule proxy_module modules/mod_proxy.so
333 LoadModule proxy_http_module modules/mod_proxy_http.so
334
335 The exact technique for enabling the proxy modules will vary depending on your Apache installation. Once you have the proxy modules enabled, add the following rules to :file:`httpd.conf` (or if you are using virtual hosts to the conf file for the virtual host in question)::
336
337 AllowEncodedSlashes On
338 RewriteEngine on
339 RewriteRule ^/calibre/(.*) http://127.0.0.1:8080/calibre/$1 [proxy]
340 RedirectMatch permanent ^/calibre$ /calibre/
341
342 That's all, you will now be able to access the calibre Content server under the ``/calibre`` URL in your main server. The above rules pass all requests under ``/calibre`` to the calibre server running on port 8080 and thanks to the ``--url-prefix`` option above, the calibre server handles them transparently.
343
344
345 .. note::
346
347 When using a reverse proxy, you should tell the calibre Content server to
348 only listen on localhost, by using ``--listen-on 127.0.0.1``. That way,
349 the server will only listen for connections coming from the same computer,
350 i.e. from the reverse proxy.
351
352 .. note::
353
354 If you have set up SSL for your main server, you should tell the calibre
355 server to use basic authentication instead of digest authentication, as it
356 is faster. To do so, pass the ``--auth-mode=basic`` option to
357 ``calibre-server``.
358
359 .. _calibre user forums: https://www.mobileread.com/forums/forumdisplay.php?f=166
360
361
362 Creating a service for the calibre server on a modern Linux system
363 --------------------------------------------------------------------
364
365 You can easily create a service to run calibre at boot on a modern
366 (`systemd <https://www.freedesktop.org/wiki/Software/systemd/>`_)
367 based Linux system. Just create the file
368 ``/etc/systemd/system/calibre-server.service`` with the contents shown below::
369
370 [Unit]
371 Description=calibre Content server
372 After=network.target
373
374 [Service]
375 Type=simple
376 User=mylinuxuser
377 Group=mylinuxgroup
378 ExecStart=/opt/calibre/calibre-server "/path/to/calibre library folder"
379
380 [Install]
381 WantedBy=multi-user.target
382
383
384 Change ``mylinuxuser`` and ``mylinuxgroup`` to whatever user and group you want
385 the server to run as. This should be the same user and group that own the files
386 in the calibre library folder. Note that it is generally not a good idea to
387 run the server as root. Also change the path to the calibre library
388 folder to suit your system. You can add multiple libraries if needed. See
389 the help for the ``calibre-server`` command.
390
391 Now run::
392
393 sudo systemctl start calibre-server
394
395 to start the server. Check its status with::
396
397 sudo systemctl status calibre-server
398
399 To make it start at boot, run::
400
401 sudo systemctl enable calibre-server
402
403 .. note::
404
405 The calibre server *does not* need a running X server, but it does need
406 the X libraries installed as some components it uses link against them.
407
408 .. note::
409
410 The calibre server also supports systemd socket activation, so you can use
411 that, if needed, as well.