| 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. |