From e22c566e0fcd7464e089dd0b7c55eb21bff8603d Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Tue, 30 May 2017 12:34:31 +0530 Subject: [PATCH] Add some documentation for the new server --- manual/faq.rst | 41 ++++------ manual/index.rst | 8 ++ manual/server.rst | 164 ++++++++++++++++++++++++++++++++++++++-- manual/simple_index.rst | 1 + manual/tutorials.rst | 1 - 5 files changed, 178 insertions(+), 37 deletions(-) diff --git a/manual/faq.rst b/manual/faq.rst index 07e6cfeda4..1f832974a7 100644 --- a/manual/faq.rst +++ b/manual/faq.rst @@ -351,11 +351,8 @@ like and in the URL field, enter the following:: http://192.168.1.2:8080/ Replace ``192.168.1.2`` with the local IP address of the computer running -calibre. If you have changed the port the calibre Content server is running on, you -will have to change ``8080`` as well to the new port. The local IP address is -the IP address your computer is assigned on your home network. A quick Google -search will tell you how to find out your local IP address. Now click "Save" -and you are done. +calibre. See :doc:`server` for details on running the server and finding out the +right IP address to use. If you get timeout errors while browsing the calibre catalog in Stanza, try increasing the connection timeout value in the stanza settings. Go to @@ -370,10 +367,8 @@ running the calibre server, like this:: http://192.168.1.2:8080/ Replace ``192.168.1.2`` with the local IP address of the computer running -calibre. If you have changed the port the calibre Content server is running on, you -will have to change ``8080`` as well to the new port. The local IP address is -the IP address your computer is assigned on your home network. A quick Google -search will tell you how to find out your local IP address. +calibre. See :doc:`server` for details on running the server and finding out the +right IP address to use. You will see a list of books in Safari, just click on the epub link for whichever book you want to read, Safari will then prompt you to open it with @@ -448,14 +443,10 @@ Now on your Android device, open the browser and browse to http://192.168.1.2:8080/ Replace ``192.168.1.2`` with the local IP address of the computer running -calibre. If your local network supports the use of computer names, you can -replace the IP address with the network name of the computer. If you have -changed the port the calibre Content server is running on, you will have to -change ``8080`` as well to the new port. +calibre. See :doc:`server` for details on running the server and finding out the +right IP address to use. -The local IP address is the IP address your computer is assigned on your home -network. A quick Google search will tell you how to find out your local IP -address. You can now browse your book collection and download books from calibre +You can now browse your book collection and download books from calibre to your device to open with whatever e-book reading software you have on your android device. @@ -468,22 +459,17 @@ reading software. Can I access my calibre books using the web browser in my Kindle or other reading device? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -calibre has a *Content server* that exports the books in calibre as a web page. You can turn it on under -:guilabel:`Preferences->Sharing->Sharing over the net`. Then just point the web browser on your device to the computer running -the Content server and you will be able to browse your book collection. For example, if the computer running -the server has IP address 63.45.128.5, in the browser, you would type:: - - http://63.45.128.5:8080 +calibre has a *Content server* that exports the books in calibre as a web page. See :doc:`server` for details. Some devices, like the Kindle (1/2/DX), do not allow you to access port 8080 (the default port on which the content server runs). In that case, change the port in the calibre Preferences to 80. (On some operating systems, you may not be able to run the server on a port number less than 1024 because of security settings. In this case the simplest solution is to adjust your router to forward requests on port 80 to port 8080). -I get the error message "Failed to start Content server: Port 8080 not free on '0.0.0.0'"? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Also some devices do not have browsers advanced enough to run the app-like +interface used by the content server. For such devices, you can simply add +``/mobile`` to the server URL to get a simplified, non-javascript interface. -The most likely cause of this is your antivirus program. Try temporarily disabling it and see if it does the trick. I cannot send emails using calibre? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -790,8 +776,7 @@ once again, bad things *will happen*. Consider using the calibre Content server to make your books available on other computers. Run calibre on a single computer and access it via the Content -server -or a Remote Desktop solution. +server or a Remote Desktop solution. If you must share the actual library, use a file syncing tool like DropBox or rsync instead of a networked drive. If you are @@ -1119,7 +1104,7 @@ a modern linux distro, you should have no problems installing calibre onto it. You can run the calibre server via the command:: - /opt/calibre/calibre-server --with-library /path/to/the/library/you/want/to/share + /opt/calibre/calibre-server /path/to/the/library/you/want/to/share You can download news and convert it into an e-book with the command:: diff --git a/manual/index.rst b/manual/index.rst index 43f44ba296..82789d7080 100644 --- a/manual/index.rst +++ b/manual/index.rst @@ -40,6 +40,14 @@ Editing e-books edit +The calibre Content server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 2 + + server + Comparing e-books ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/manual/server.rst b/manual/server.rst index 611289a701..f1f32d2c7d 100644 --- a/manual/server.rst +++ b/manual/server.rst @@ -1,18 +1,163 @@ -.. _servertutorial: +The calibre Content server +============================== -Integrating the calibre Content server into other servers -========================================================== - -Here, we will show you how to integrate the calibre Content server into another server. The most common reason for this is to make use of SSL or more sophisticated authentication. The basic technique is to run the calibre server and setup reverse proxying to it from the main server. +The calibre :guilabel:`Content server` allows you to access your calibre +libraries and read books directly in a browser on your favorite mobile phone or +tablet device. As a result, you do not need to install any dedicated book +reading/management apps on your phone. Just use the browser. The server +downloads and stores the book you are reading in an offline cache so that you +can read it even when there is no internet connection. .. contents:: Contents :depth: 2 :local: -A reverse proxy is when your normal server accepts incoming requests and passes them onto the calibre server. It then reads the response from the calibre server and forwards it to the client. This means that you can simply run the calibre server as normal without trying to integrate it closely with your main server, and you can take advantage of whatever authentication systems your main server has in place. +To start the server, click the :guilabel:`Connect/share` button and choose +:guilabel:`Start Content server`. You might get a message from your computer's +firewall or anti-virus program asking if it is OK to allow access to +``calibre.exe``. Click the ``Allow`` or ``OK`` button. Then open a browser +(preferably Chrome or Firefox) in your computer and type in the following +address: + + http://127.0.0.1:8080 + +This will open a page in the browser showing you your calibre libraries, click +on any one and browse the books in it. Click on a book, and it will show you +all the metadata about the book, along with buttons to :guilabel:`Read book` +and :guilabel:`Download book`. Click the :guilabel:`Read book` button to +start reading the book. + +.. note:: The address used above ``http://127.0.0.1:8080`` will only work on + the computer that is running calibre. To access the server from other + computers/phones/tablets/etc. you will need to do a little more work, + as described in the next section. + + +Accessing the Content server from other devices +--------------------------------------------------- + +There are two types of remote device access that you will typically need. The +first, simpler kind is from within your home network. If you are running +calibre on a computer on your home network and you have also connected your +other devices to the same home network, then you should be easily able to +access the server on those devices. + +Accessing the server from devices on your home network +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After starting the server in calibre as described above, click the +:guilabel:`Connect/share` button again. Instead of the :guilabel:`Start Content +server` action, you should see a :guilabel:`Stop Content server` action +instead. To the right of this action will be listed an IP addresses +and port numbers. These look like a bunch of numbers separated by periods. For +example:: + + Stop Content server [192.168.1.5, port 8080] + +These numbers tell you what address to use to connect to the server in your +devices. Following the example above, the address becomes:: + + http://192.168.1.5:8080 + +The first part of the address is always ``http://`` the next part is the IP +address, which is the numbers before the comma and finally we have the port +number which must be added to the IP address with a colon (``:``). If you are +lucky, that should be all you need and you will be looking at the +calibre libraries on your device. If not, read on. + + +Trouble-shooting the home network connection +__________________________________________________ + +If you are unable to access the server from your device, try the following +steps: + + #. Check that the server is running by opening the address + ``http://127.0.0.1:8080`` in a browser running on the same computer as + the server. + + #. Check that your firewall/antivirus is allowing connections to your + computer on the port ``8080`` and to the calibre program. The + easiest way to eliminate the firewall/anti-virus as the source of + problems is to temporarily turn them both off and then try connecting. You + should first disconnect from the internet, before turning off the + firewall, to keep your computer safe. + + #. Check that your device and computer are on the same network. This means + they should both be connected to the same wireless router. In particular + neither should be using a cellular or wifi broadband connection. + + #. If you have non-standard networking setup, it might be that the IP + address shown on the :guilabel:`Connect/share` menu is incorrect. + In such a case you will have to figure out what the correct IP address + to use is, yourself. Unfortunately, given the infinite diversity of + network configurations possible, it is not possible to give you a + roadmap for doing so. + + #. If you are stuck, you can always ask for help in the `calibre user forums`_. + + +Accessing the server from anywhere on the internet +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + Before doing this you should turn on username/password protection in the + server, otherwise anyone in the world will be able to access your books. + Go to :guilabel:`Preferences->Sharing->Sharing over the net` and enable the + option to :guilabel:`Require username and password to access the content + server`. + +While the particular details on setting up internet access vary depending on +the network configuration and type of computer you are using, the basic schema +is as follows. + + #. Find out the external IP address of the computer you are going to run the + server on. You can do that by visiting the site `What is my IP address + `_ in a browser running on the computer. + + #. If the computer is behind a router, enable port forwarding on the router + to forward the port ``8080`` (or whatever port you choose to run the + calibre Content server on) to the computer. + + #. Make sure the calibre server is allowed through any firewalls/anti-virus + programs on your computer. + + #. Now you should be able to access the server on any internet-connected + device using the IP address you found in the first step. For example, + if the IP address you found was ``123.123.123.123`` and the port you are + using for the calibre server is ``8080``, the address to use on your + device becomes: ``http://123.123.123.123:8080``. + + #. Optionally, use a service like `no-ip `_ to + setup an easy to remember address to use instead of the IP address you + found in the first step. + +.. note:: + For maximum security, you should also enable HTTPS on the content server. + You can either do so directly in the server by providing the path to + the HTTPS certificate to use in the advanced configuration options for + the server, or you can setup a reverse proxy as described below, to use + an existing https setup. + + +Integrating the calibre Content server into other servers +------------------------------------------------------------ + +Here, we will show you how to integrate the calibre Content server into another +server. The most common reason for this is to make use of SSL. The basic +technique is to run the calibre server and setup a reverse proxy to it from the +main server. + +A reverse proxy is when your normal server accepts incoming requests and passes +them onto the calibre server. It then reads the response from the calibre +server and forwards it to the client. This means that you can simply run the +calibre server as normal without trying to integrate it closely with your main +server, and you can take advantage of whatever authentication systems your main +server has in place. Using a full virtual host ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The simplest configuration is to dedicate a full virtual host to the calibre server. In this case, run the calibre server as:: @@ -44,7 +189,7 @@ Or, for Apache:: Using a URL prefix ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ If you do not want to dedicate a full virtual host to calibre, you can have it use a URL prefix. Start the calibre server as:: @@ -65,3 +210,6 @@ The exact technique for enabling the proxy modules will vary depending on your A RewriteRule ^/calibre http://localhost:8080 [proxy] That's all, you will now be able to access the calibre Content server under the /calibre URL in your Apache 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. + + +.. _calibre user forums: https://www.mobileread.com/forums/forumdisplay.php?f=166 diff --git a/manual/simple_index.rst b/manual/simple_index.rst index e3566ea2cd..1875bad1de 100644 --- a/manual/simple_index.rst +++ b/manual/simple_index.rst @@ -30,6 +30,7 @@ Sections viewer conversion edit + server diff metadata faq diff --git a/manual/tutorials.rst b/manual/tutorials.rst index 4176b324fe..d5971ee611 100644 --- a/manual/tutorials.rst +++ b/manual/tutorials.rst @@ -13,7 +13,6 @@ Here you will find tutorials to get you started using calibre's more advanced fe xpath template_lang regexp - server creating_plugins typesetting_math catalogs