JUpdater - 0.5 - Server
From LokDoc
| Important note This is the preliminary documentation for version 0.5 . It will replace the old documentation as soon as the new version is released. |
JUpdater consists of two parts, one part sits in a server and the other in the programs that you want to keep updated. This article is about the server part which requires PHP (>= 4.3) and MySQL.
The server's job is to store information about the the latest version of programs, all previous versions, changes between the versions, a lists of the different files, their different versions and sizes. The server then uses this information in conjunction with information given by the client to figure out what files the client should update.
Contents |
Installation
The server part can be downloaded from http://www.lokorin.com/jupdater/download .
- Uploaded everything in the server directory to the server.
- The server requires permission to create files in the jupdater and jupdater/_includes directories, so if it does not have that by default then it has to be set.
- Access the uploaded installation file at jupdater/install.php, it should present a couple of forms.
- The first form displayed is the Database configuration form, in which the following can be entered.
- Database name - The name of the database that should be used for storing information.
- Host - The host of the database, typically localhost.
- User name - The user name used to access the database.
- Password - The password used to access the database.
- Table prefix - The prefix that should precede all JUpdater's tables in the datase. Soo if this is set to foo_ then all tables created by JUpdater will begin with foo_, for example foo_bar.
- Then the Admin account form is displayed, in which the following can be entered.
- Login name - This is the login name that you want the JUpdater administration account to have. The administration account is then used to log into the JUpdater admin panels, from which one can add programs, versions and more.
- Password - The password that you want the JUpdater administration account to have.
- Password (retype) - Retype the password, this is just to verify that there were no typos in the first entry.
- The installation will now begin. First it will attempt to create a configuration file at jupdater/_includes/config.php, the it will write the configuration to that file. It will then create the required tables.
Trouble shooting
If the installer complains about being unable to create a file then it's probably because the server lacks permission to create files in the jupdater/_includes directory.
After the installation
The jupdater/_includes/config.php file contains the server user name and password. Read access to that file should therefor be restricted. The installation process attempts to set the permissions so that only the server can read and write to the file. The installer is however not guaranteed to succeed, so it's probably a good idea to double check that reading is restricted.
The jupdater/install.php file should be removed once the installation is complete, as it is a security risk if it's left there. In fact, it is not possible to use JUpdater until that file has been removed.
Log in via the jupdater/admin/login.php file to access the administration panels and to confirm that the installation was a success.
Admin panels
The admin panel is the only page meant for humans in the JUpdater server pack. Everything can be controlled from these panel.
You first have to log in, the login screen at jupdater/admin/login.php, to gain access the panels. Links to the panels are then shown in the menu to the left.
Files
This panel displays all files that are part of a program's latest version. It's possible to delete individual files, but it should be avoided if possible. All files associated with a program are removed when the program is removed.
This panel is mostly provided for completeness and to provide a way to check if certain files have been uploaded and synchronized properly.
Programs
This is the most important panel. From here one can add new programs and add new versions for those programs.
How to add a program
Here is a brief example of how to add a program using the panel.
- Either upload the JAR file, which contains you program, manually to the jupdater/_jars folder or click on the Upload JAR file button and do it via the form.
- Click on New entry once the jar has been uploaded. This opens up a form where you name the program and select the JAR file. If the JAR file is not in the list then make sure that it is present in the jupdater/_jars folder. The program name is used to identify the program in the JUpdater clients, so pick a good one. Finally click Add to add the program.
- You should now be back at the original panel, there should also be a row with the program that you just added. Click on the Synchronise button next to the program. A list detailing that the server has found a lot of new files should now be displayed. That means that the server has successfully scanned the JAR file and indexed it.
That's it, JUpdater clients can now query the server about programs.
How to add a new program version
Here is a brief example of how to add a new version once a program has been added as described above.
- Either upload the JAR file, which contains the new version, manually to the jupdater/_jars folder or click on Upload JAR file and do it via the form. The new version's JAR can either replace the old version's JAR or have a name of its own, both are fine. If the old version's JAR was not overwritten by the new one then the program entry has to be edited so that it points at the new jar. To do that, do the following.
- Click on Edit next to the program that should be updated.
- Select the JAR file containing the new version in the JAR name drop-down and click Edit. The JAR file that the program points on should now have changed.
- Now click Synchronise next to the program that should be updated. A list detailing the changes that the server has found between the previous version and the new one should now be displayed.
That's it, now the server will make sure that everyone who queries the server receive the new version, unless they already have it.
Versions
One entry for each new versions synchronized with the server end up in this panel. By using the Edit buttons one can edit the Changes field, which contains the text that is sent to the clients when they request a change log. So it's a good habit to go to the panel and write down am explainations of the changes after adding a version.
View log
This panel displays JUpdater's logs of all connections made with the server. Its purpose is to give a understanding of how the users update the versions. For instance the following questions are usually interesting.
- How many are currently using the latest version?
- How often do the users check for new updates?
- How often do they find that their version is out of date?
Those questions, and many more, are answered by the log. JUpdater by default logs every connection attempt to the jupdater/update.php file, but the behaviour can be deactivated by setting the JUPDATER_LOG_ACTIVITY constant to false in the jupdater/upgrade.php file. The following information is logged.
- The IP of the user.
- The point in time of the connection.
- The program that the user is requesting information about.
- The program version that the user is running.
- The program version that the user is attempting to update to.
- The number of the user's files that are out of date.
- The total size of the files that are out of date.
- The JUpdater client version that the user's version is running.
- Whether or not the user's version is out of date.
- Whether or not the user successfully checked if an update was available.
- Whether or not the user downloaded anything.
The panel currently only shows a fraction of that data, but that fraction contains the most interesting data.
Overview
The log overview is the default log view, it can be accessed by clicking the link named Overview at the top of the page.
When looking at the overview each row in the Requests from versions table displays how many that have updates from the row's version. I.e. how many that have connected with e.g. the version of program Foo that was uploaded on 21st Mar 2006. The Upgrades to versions table, on the other hand, displays how many that have updated to the row's version. I.e. how many that have connected to the server while the 21st Mar 2006 version was the latest version.
Each version and each program are displayed as links. The programs can be filtered by clicking a program link. By clicking a version link one is brought to a new pair of tables that display the information for that version in greater details.
Detailed view
Lets say that one for example clicks on the 21st Mar 2006 version link. The Versions requested from clients of version 21st Mar 2006 table will then display which versions that the 21st Mar 2006 version was updated to. And the Versions upgraded to version 21st Mar 2006 table will display which versions that were updated to 21st Mar 2006.
Contents
Here's a list of everything all files in the server/jupdater directory along with a description of their purpose.
- install.php - The installer - creates a configuration and the required tables.
- update.php - The file that handles the incoming requests of clients.
- upgrade.php - An upgrade script for migrating the table contents from JUpdater version 0.3 and 0.4 to 0.5, see Upgrading old JUpdater versions for more information.
- _css/ - A directory that contains all CSS files.
- admin_panel.css - Controls the look of the admin panel.
- forms.css - Controls the look of forms.
- main.css - Controls the general page layout and look.
- menu.css - Controls the look of the menu.
- table_displayer.css - Controls the look of the menus associated with displayed tables.
- tables.css - Controls the look of the tables.
- _includes/ - Directory that contains the libraries that are included in various pages.
- admin_auth.php - A page used to make sure that users have the correct admin authentication.
- common.php - Defines common properties, is used by most pages. It also defines a how pages should be displayed. You can easily assimilate the JUpdater's pages into your own site by modifying the display() function.
- config.php - Stores the configuration set in the installation.
- lib_admin_panel.php - Used to construct the admin panels.
- lib_db.php - An abstraction library for DB interaction.
- lib_dir.php - A directory related library.
- lib_displayer.php - Used by the control panels to display table contents.
- lib_forms.php - Used to create forms.
- lib_jupdater.php - Contains functions specific to JUpdater.
- lib_pclzip.php - A third party library for zip management. See http://www.phpconcept.net/ for more information.
- lib_tables.php - Used to construct (XHTML) tables.
- lib_util.php - Contains various utility functions.
- _jars - The directory where the server will look for uploaded jars.
- admin - A directory that contains all admin panels.
- files.php - The admin panel for files.
- login.php - The login form.
- programs.php - The admin panel for programs.
- versions.php - The admin panel for program versions.
- view_log.php - The admin panel for viewing logs.
- xmlrpc - A directory that contains an php library for XML-RPC, see http://phpxmlrpc.sourceforge.net/ for more information.
- xmlrpc.php - See above.
- xmlrpcs.php - See above.
Tables
The following database tables are created and used by JUpdater. The prefix chosen during the installation is used in front of each table's name.
- files - Stores information about each file that is currently part of some program's latest version. Each file is connected to exactly one program.
- logs - Stores all logged information.
- programs - Stores information about all registered programs and about the jar files that are backing them.
- tags - Stores information about each program version. One entry is added for each synchronization.
- versions - Stores information about each file version. This is not the information shown in the version panel, in fact this information can not be directly viewed from any of the panels.
Upgrading old JUpdater versions
The table structure was changed in JUpdater version 0.5, so all previous versions' tables have to be migrated to a new tables. A script for doing that is provided in the 0.5 release and is located at jupdater/upgrade.php.
This is how it's used.
- Backup the old tables.
- Install the new JUpdater version, just be careful not to overwrite the old tables in the process.
- Edit the jupdater/upgrade.php file.
- Set the variables at lines 31-33 to the names of the tables that should be converted.
- Comment or remove the line that says exit; on line 25.
- Run the file (by for instance accessing it with your web browser). It should display some lines showing the progress, followed by a message saying Migration complete.
- Delete the jupdater/upgrade.php file or uncomment the exit; line. If the file is left alone then it poses a security risk.
The newly installed tables should now contain all of the old version's data.
