Readerware Client/Server Edition

Readerware Client/Server edition is designed to allow multiple users to connect to a central database. It can be used on home networks to manage personal collections. It can also be used in libraries, churches, schools and enterprise locations to catalog and manage a library.

Installing the Readerware Server

The Readerware Server is included in all distributions. Installation is a little different on each platform. We recommend that you install the full Readerware distribution on the server machine, not just the Readerware server itself. As you configure the server it will be much easier to test your setup if you can run Readerware on the same machine as the server. Also when you are running Readerware and the server on the same machine, firewall software is not usually an issue. If you can run Readerware in client/server mode on the same machine as the server but are unable to connect from another machine, then chances are it is a firewall issue. You may also need the Readerware client programs to create or migrate your database.

Before you start the server you must create your Readerware databases on the server machine.

If this is a new installation you can create a new empty database using the normal Readerware program, select the File->New Database menu item.

If you have an existing database on another machine you can use backup & restore to transfer it to the server machine.

Installing the Readerware Server on Windows

We recommend using the Windows Web Installer when installing Readerware on your server machine. This will ensure that the best version of Readerware is installed on your machine, i.e. the 64bit version of Readerware on a 64bit machine.

We recommend that you do a full install on your Windows server machine, install the full product not just the Readerware server. This will help you when setting up your Readerware server. As you go through the installer look for the Desktop Shortcuts screen. You might want to add a desktop shortcut for the RWServer Config utility as you will be using it a lot on the server machine.

On Windows the Readerware Server is run as a Windows service. This means that the Readerware server can be started with the machine and it will always be available. You don't have to manually start the server first.

To configure the Readerware server as a Window service, start the RWServer Config utility. Double-Click on the RWServer Config desktop shortcut or select it from the Windows Start menu. Select Start->All Programs->Readerware 4->RWServer Config.

RWServer Config requires administrator rights so Windows should prompt you to approve the program before it is launched. If RWServer Config is not run as an administrator, you will not be able to install the Readerware server as a Windows service.

Select the Service->Install RWServer Service menu item, this will install the Readerware server as a Windows service that will be started automatically every time you start your computer. You only need to install the Readerware server as a service the first time you install it. You do not have to do this every time you upgrade Readerware. You can also use the Service menu to check the status of the Readerware server, stop and start the server etc.

Once installed, another way to stop and start the server is by using the Windows Control Panel, (Windows 7) or Settings, (Windows 10), search for Services. The Windows Services settings can also be used to change the Readerware server properties. Locate RWServer in the list and double click on it to open the properties dialog. There are a couple of settings you might want to change:

Startup type - The default setting is Automatic, Windows will start the Readerware Server as Windows starts. You can change this to Automatic (Delayed Start). Windows will still start the Readerware Server automatically but not until Windows is fully launched. Choose this option if you need to have other processes start before the Readerware Server. For example you might have your Readerware database on an encrypted drive. If started right away the drive may not be available. Using the delayed start option gives you a chance to load the encrypted drive first.

Log on as - By default the Readerware server runs as a local system account. This normally works fine unless you have your database stored in a folder owned by a particular user. In this case the system account may be denied access to the database. You can fix this by providing the appropriate log on credentials and Windows will start the Readerware Server under that account.

Important note for Windows 10 users: It is strongly recommended that you use the Automatic (Delayed Start) startup type on Windows 10. Windows 10 is upgraded automatically by Microsoft and the upgrade process can involve several system restarts. By using the delayed start option, the Readerware Server is not constantly being started and stopped during the upgrade process which can cause issues. The Readerware server will still be automatically restarted once the upgrade is complete.

Once you have installed the Readerware server as a Window service, you can continue with the normal setup.

Installing the Readerware Server on Linux

You can just install Readerware on your Linux server machine and run the Readerware server by launching the RWServer application. However we recommend that you take the time to set up the Readerware Server as a Linux systemd service. That way the Readerware server will be started automatically when the machine starts.

Setting up the Readerware server as a systemd service is a one time thing, you do not need to repeat this every time you upgrade Readerware. Here are the steps you need to follow:

Create a Readerware user - You should create a new user for the Readerware server. The server will then be run under this ID. We recommend adding a new standard user called "rware". If you cannot use this name, you may pick another and update the rwserver.service file to point to the correct user.

Readerware provides the systemd rwserver.service file as part of the standard distribution. It is located in the Readerware installation folder. By default Readerware is installed in "/opt/readerware4". You should open this file in a text editor and check the settings. If you are using a different user, you should change "user=rware" to point to your Readerware user name. If you installed Readerware in another location, you should change the "ExecStart=/opt/readerware4/rwserver.sh" line to point to your installation. When ready you should copy this file to the systemd folder, normally "/lib/systemd/system".

After copying the service file to the systemd folder issue the following command to enable the rwserver service and have it started automatically when the system starts:

systemctl enable rwserver
Now whenever you start your system the Readerware server will be started automatically. If you ever want to change this behavior use the disable command.

To start the Readerware server manually use the following command:

systemctl start rwserver
To stop the Readerware server manually use the stop command.

The full Readerware server log is written to the Documents/Readerware/Logs folder of the user the server is running under. By default that is rware i.e. /home/rware/Documents/Readerware/Logs/rwserver.log.

You can also use the standard systemd journal service to view the Readerware server log. For example:

journalctl _SYSTEMD_UNIT=rwserver

Important: When running the RWServer Config utility to configure the Readerware server, you must first login as the Readerware user you created above. This ensures that the server configuration files are saved in the correct location. You can also create your databases under this user.

Once you have installed the Readerware server with systemd, you can continue with the normal setup.

Installing the Readerware Server on macOS

You can just install Readerware on your Mac server machine and run the Readerware server by launching the RWServer application. However we recommend that you take the time to set up the Readerware Server as a macOS launchd daemon. That way the Readerware server will be started automatically when the machine starts.

Setting up the Readerware server as a launchd daemon is a one time thing, you do not need to repeat this every time you upgrade Readerware. Here are the steps you need to follow:

Create a Readerware user - You should create a new user for the Readerware server. The server will then be run under this ID. We recommend adding a new standard user called "rware". You should then login to this account and create your Readerware databases. If you have existing databases you can use backup & restore to transfer them to the rware account. If you cannot use this name or would prefer not to relocate your databases, you may pick another user and update the com.readerware.rwserver.plist file to point to the correct user.

Readerware provides the launchd plist file as part of the standard distribution. It is located in the Readerware Client/Server disk image. It is called com.readerware.rwserver.plist. You should open this file in a text editor and check the settings. If you are using a different user, you should change "<string>rware</string>" to point to your Readerware user name. The RWServer application is normally installed in your Applications folder. If you installed it in another location, you should change the "<string>/Applications/RWServer 4.app/Contents/MacOS/JavaAppLauncher</string>" line to point to your installation. When ready you should copy this file to the launchd daemon folder, normally "/Library/LaunchDaemons". You can simply drag and drop this file to the launchd daemon folder, you will need to authenticate the operation.

When you reboot your Mac, the Readerware server will be started automatically. As you test the server configuration you can manually start the server by double-clicking on the RWServer 4 application. You can use the RWServer Config utility to restart or stop the Readerware server.

The full Readerware server log is written to the Documents/Readerware/Logs folder of the user the server is running under. By default that is rware i.e. /Users/rware/Documents/Readerware/Logs/rwserver.log.

Important: When running the RWServer Config utility to configure the Readerware server, you must first login as the Readerware user you created above. This ensures that the server configuration files are saved in the correct location. You should also create your databases under this user.

Once you have installed the Readerware server with launchd, you can continue with the normal setup.

Installing the Readerware Server on macOS Catalina or better

You can just install Readerware on your Mac server machine and run the Readerware server by launching the RWServer application or setting it up as a login item. However we recommend that you take the time to set up the Readerware Server as a macOS launchd agent. That way the Readerware server will be started automatically when the machine starts.

Setting up the Readerware server as a launchd agent is a one time thing, you do not need to repeat this every time you upgrade Readerware. Here are the steps you need to follow:

The Readerware Server will run under the logged in user, so you should use the normal user that you will log into on the server machine. You should then login to this account and create your Readerware databases. If you have existing databases you can use backup & restore to transfer them to your user account.

Readerware provides the launchd plist file as part of the standard distribution. It is located in the Readerware Client/Server disk image. It is called com.readerware.rwserver.plist. You should open this file in a text editor and check the settings. The RWServer application is normally installed in your Applications folder. If you installed it in another location, you should change all references to the application location to your new location. When ready you should copy this file to the launchd agents folder, normally "/Library/LaunchAgents". You can simply drag and drop this file to the launchd agents folder, you will need to authenticate the operation.

Important: In earlier versions of Readerware we told you to store the "com.readerware.rwserver.plist" file in your "/Library/LaunchDaemons" folder. This was the wrong location, please delete the file from LaunchDaemons and copy the new version included in this distribution to your "/Library/LaunchAgents" folder.

When you reboot your Mac, the Readerware server will be started automatically. As you test the server configuration you can manually start the server by double-clicking on the RWServer 4 application. You can use the RWServer Config utility to restart or stop the Readerware server.

The full Readerware server log is written to the Documents/Readerware/Logs folder of the user the server is running under.

As the Readerware server is started two files are written to the /tmp folder:

com.readerware.rwserver.out
com.readerware.rwserver.err

If the server does not start you can check these files to see what the problem is.

Once you have installed the Readerware server with launchd, you can continue with the normal setup.

Running Readerware in Client/Server Mode

In a Readerware client/server configuration you run the Readerware server on one machine. Typically the database is also on that machine. The Readerware server opens the database and provides database access to the Readerware client programs, including the Readerware Loan Client. It can also provide database access to mobile devices.

The Readerware server can run on any platform, Windows, Linux or macOS. It does not need a dedicated server, it will run in the background on any machine.

You can run the Readerware client programs on the same machine as the server as well as other machines on your network. You configure Readerware to connect to the Readerware server rather than open the database directly. That way multiple users can connect to the same central database.

You can have any mix of client machines, Windows, Linux and macOS users can all connect to the same Readerware server, regardless of what platform the server is running on.

You can publish your database in read only, checkout or full access mode. Selected users can be given full access. So for example you could publish your database in checkout mode so that all users can browse the database and check items in and out. However they will not be allowed to make any other changes to the database. Selected users can be given full access so that they can add new items and maintain the database.

Configuring the Readerware Server

Before you can run Readerware in client/server mode, you must configure the Readerware server. For example you must tell the server where the databases are located.

The Readerware server itself is what is known as a daemon task. It runs quietly in the background, it does not display any windows or interact with the user in anyway. This means that you can run the server automatically as the machine starts, and this is typically the way you run the Readerware server.

You configure the Readerware server using the RWServer Config utility. This is a typical graphical application and you make selections to configure the Readerware server. RWServer Config then writes out the configuration file which is used by the Readerware server.

The program presents a tab interface, click on the appropriate tab to configure that component of the Readerware server. There are three basic tab types. The Ports tab is where you define what network ports the Readerware server should use. There are three database tabs, one for each of the three databases, books, music and video. These tabs are where you define the databases the Readerware server should use, the access mode etc. The final three tabs are the mobile tabs, again one for each of the three databases. On these tabs you define whether or not mobile support should be enabled, which database columns should be transferred to Readerware Mobile etc.

The Ports Tab

The Readerware server users three TCP/IP ports.

The control port is used by the Readerware clients to request access to the server. The default control port is 9010.

The data port is used by the Readerware server to provide database access to the Readerware client programs. The default data port is 9001.

The mobile port is used by the Readerware server to provide mobile sync support to Readerware Mobile devices. The default mobile port is 9002.

It is strongly recommended that you use the default ports. However only one program can access a given port at a time. So there could be a problem if you have another program running on your server machine that is also trying to use one of these 3 ports. That is why you can change them if needed. If you do change a port, you must change it on both ends, i.e. you must change it in RWServer Config and in the Readerware client programs. By default the Readerware client programs use the same control port, that is why we recommend you use the default ports unless there is a port conflict.

The Readerware server will open these three ports for inbound connections. It will then listen on these ports for incoming messages from Readerware programs. If you are running firewall software on your server machine, you may need to configure it to allow Readerware to open these ports and accept incoming connections.

This is one more important field on the Ports tab. Readerware lists the Hostname and IP address of the server machine. This is the information you will need when connecting to the Readerware server from another machine or a mobile device. For example it might list "My Computer / 192.168.1.110". When connecting to the server from another computer or mobile device it is best to use the Host name, i.e. "My Computer". If for some reason you cannot connect using the Host name, select the IP address instead. i.e. "192.168.1.110 ". The advantage to using the Host name is that it will not change. Depending on your network configuration, the IP address can change.

The Server Tabs

Each server database is configured separately. You do not have to make all three databases available. If you are only using Readerware for books, then you only need to define the books database.

Click on the appropriate Server tab to configure the database. Start by checking the option to enable this database.

Click on the Browse button to select the database. The standard file selection dialog is displayed and you can navigate to your database folder and select the database.

Next you must select the database access mode. The access mode must be set to one of the following:

Read only - All users can view the database but cannot make any changes to the database, this includes checking out an item.

Checkout mode - All users can view the database and check items in and out. No other updates are permitted.

Full Access - All users have full access to the database.

The update password is used in read only and checkout modes. The Readerware client allows users to request update access. The user must provide this password to get full access to the database.

If you have purchased Readerware you must supply your registration name and code to register the server program. If running in evaluation mode, leave these fields blank. The easiest way to register is to copy the contents of your registration e-mail and the click on the Paste button. RWServer Config will the locate your registration information in the e-mail and insert it into the appropriate fields. Your registration e-mail has more information on how to copy/paste your registration.

There is one final option you need to set when configuring the Readerware server. This is required when using the Readerware Loan Client. The Readerware Loan Client provides a unified interface to all three databases so you can check items in and out using the one program. When using the loan client you have to decide which database should contain the borrowers. All borrowers will be stored in this database. Check the Store borrowers in this database option on the one database that you will use for borrowers. When saving the server configuration you will get an error if no database is defined as the borrower database. You will also get an error if multiple databases have this option checked. there should be one and only one borrower database selected.

In earlier versions of the Readerware Loan Client only books were supported. If you have been using the loan client prior to Readerware 4, then you should select the book database as your borrower database. That is where your existing borrowers will have been stored.

Even if you are not using the Readerware Loan Client it is a good idea to select a borrower database. This will eliminate the error message when you save the server configuration.

The Mobile Tabs

Again mobile support for each database is configured separately. You do not have to enable mobile support for all three databases. If you are only using Readerware for music, then you only need to activate mobile support for the music database.

Select the appropriate mobile tab. Check the option to enable mobile support for this database.

You can select which database columns should be synced to your mobile device. Columns listed with a green check mark will by transferred to your mobile devices. Columns displayed with a red X will not. Double-Click on a column to toggle the status.

You can optionally define a maximum length for each column. For example the Album Info column can contain a lot of data. It might contain more than you need on your mobile device and by limiting the amount of data transferred you can save space on your mobile device. Select the column in the list and then enter the maximum length you want to transfer.

When transferring images to your mobile devices, Readerware will scale them to an appropriate size. You can set that size in the server configuration but it is recommended that you select the Use device defaults option. That way Readerware will scale the images to the appropriate size for each device. For example if you have a phone and tablet, Readerware can send bigger images to the tablet.

Configuring the Readerware Client

To use Readerware in client/server mode you must select the advanced open dialog option. Select the Preferences menu item, then Database, then Access.

Now when you open a Readerware database by selecting File->Open Database, you will see the advanced open dialog. Select the option to connect to a Readerware Server and enter the server name or IP address and the control port. The control port must be the same as the control port set in the server configuration utility.

Readerware will connect to the server and display your database as normal. Readerware remembers the last accessed database and will open it automatically the next time the program is started. So normally you set up Readerware to connect to the server once and Readerware connects to your server each time the program is started.

Configuring the Readerware Loan Client

Unlike Readerware the Readerware Loan Client can only connect to a Readerware server, it cannot open a Readerware database directly.

When you select the File->Open database menu item, the Database Chooser is displayed. The only option is to Connect to a Readerware Server. Select this option and enter the server name. The Readerware Loan Client will connect to the server and open all the configured databases. The Readerware Loan Client provides a unified view of all databases so that you can checkout books, music and videos with one program.

The Readerware Loan Client remembers the last accessed server and will connect to it automatically the next time the program is started.

Readerware Server Log File

The Readerware server logs basic activity and errors to a log file. The file is called rwserver.log and it will be created in your Documents folder, Readerware->Logs.

If you experience any problems, the answer can normally be found in the log file. This is a plain text file and can be viewed in any text editor.

Connection problems

If the client cannot connect to the Readerware server it is normally one of the following issues:

The Readerware server is not running or does not have the appropriate database open. Check the rwServer.LOG file on the server machine to verify that the Readerware server has started normally and that the database is open. If you start the server and open a Readerware and ReaderwareAW database but do not open a ReaderwareVW database, then you will receive an error if you try to connect from a ReaderwareVW client.

The operating system cannot resolve the server name. The first thing to check is that the two machines can communicate. From the remote machine, open a command prompt and enter the following command:

ping servername

where servername is the name of the machine running the Readerware server. If the ping works, then we know the two machines can communicate. If not there is some sort of networking problem between the two machines. Try using the machine IP address in place of the server name. Readerware will accept either.

Your Firewall is blocking the server ports. If the ping works but Readerware is still unable to connect, then it is probably your firewall software blocking the ports Readerware is using.

It is often easier to get started by running the server and client on the same machine. That takes things like firewalls out of the picture. Once you get it running on the same machine, you know the server is configured correctly and you can then try connecting from another machine.

Database Maintenance

You should perform periodic maintenance on your Readerware server databases.

As you add new items to your server databases, the database will grow in size and should be compacted for better performance and to reduce disk space usage. As your databases stabilize and you are no longer adding a lot of new items, the need to compact the database will be reduced.

Use the RWServer Config utility to compact your databases, select from the Database menu. Depending on the size of your database, it may take a while to compact a database. The server will be placed in maintenance mode while the database is compacted. No new connections will be accepted until the operation completes. You can not interrupt the process while the database is being compacted, it must be allowed to complete.

It is a good idea to backup your database before compacting it.

The Compact Database Wizard will guide you through the process. The first screen displays the full path of the database and the current database size. Verify that you are compacting the correct database and click Next to start compacting.

When the operation completes the Next button will be enabled. Click Next to display the results screen. RWServer Config will display the original size of the database and the new compacted size. This should give a good idea of how often your databases needs to be compacted.

Top of Page