====== Installing a patch server ======

{{:fr:matrix-1027571_640.jpg?direct&350|}}

Patching the client is a good way to keep it "up to date" with your game server.
It's usually a fast and easy process ones configured.

===== How it works! =====
The patching commences when the client(**on startup**) compares it's own **Lirria.version**(residing in folder: ''/unpack'' or ''/data'') file **against the patch server**(residing in: ''/patch_service/patch_game/patch/Lirria.version'').
**IF** the patch version(of this file) has a:  + value(**bigger value**), the client then receives the updated content
to it's folder: ''/unpack'' __or__ ''/data'' (__or both depending on configuration__).
It then **unpacks** the "data" and **installs** it accordingly to the information given by the "patch".

To make all this happen, a procedure is needed for creating the files, support for the operations, and even a dedicated service(via Apache) must be in place for the connecting clients.

<WRAP center round info 90%>
Let's assume the identity of home-user(named "compil" following the Linux Inst guide) for the procedures explained below.
This user must belong to the "www-data" group(and the files and directories it generates) so the apache may
be able to read the data.
The user must also be a member of the "sudo'er-list" to be able to carry out several system operations.
</WRAP>


===== Installing the patch service =====
==== Needed packages ====
Your server must have the following packages installed:
   - lzma
   - xdelta

The installation is quite easy, just type the following:
<code bash>
~/$ sudo aptitude install lzma xdelta OR (Ubuntu) ~/$ sudo apt-get install lzma xdelta
</code>

Compiling the Nel tools(from Ryzom Core) give us(among other things) two command line utilities named ''patch_gen'' and ''bnp_make'' .
These are the executables we will work with.

It is also necessary to have the .bnp files(which are used to organize the game data).
These files are in their turn manipulated by the "bnp_make" executable of Ryzom Core's NeL tools.
This section explains in detail the management of .bnp files: [[en:files_bnp|Making .bnp data files]].

==== Establishing the Data Hierarchy ====

We must first place ourselves in a directory where we can generate the patches. One of these areas will be made public by the Apache server, as a service for the web/game clients.

Create the folder ''/patch_service'' in your ''/home/compil/'' directory and move into it:
<code bash>
~/$ mkdir ~/patch_service
~/$ cd ~/patch_service
</code>

The following commands will install everything needed for the patch service:
<code bash>
~/patch_service$ patch_gen createNewProduct patch_game/ryzom.xml
</code>
If executable(patch_gen) isn't installed globaly, do this: 
<code bash>
cp /usr/local/bin/patch_gen /home/compil/patch_service/

THEN..

./patch_gen createNewProduct patch_game/ryzom.xml
</code>

This will set up all the essential files and folders(below):
  * patch_service/patch_game/
    * bnp/
    * patch/
    * ref/
    * ryzom.xml




OBS: In this guide as an example, there will only be one file indicated hereafter, called ''patch_lirria.bnp''

Next, create an empty file, which will be used as a index-file for the patches. Name the file after your own shard, followed by ".version"(we will use Lirria as an example here, because it is the name of the Khaganat development shard), and then save it to the patch_game directory:
<code bash>

cd ~/patch_service && touch patch_game/Lirria.version
</code>
==== Configuring the patch server ====
Now, edit the file: ''patch_service/patch_game/ryzom.xml'' :
<code bash>
~/patch_service$ nano patch_game/ryzom.xml
</code>

And now, we will simply create the implementation of the file: '' patch_lirria.bnp '', intended for copying into the client data subdirectory: '' /user ''  to do tests.

<WRAP center round info 90%>
Now you need to(if you haven't done so already)edit the ryzom.xml file.
This because the patch service needs to know WHAT files to offer to the client(as an update).

Detailed "syntax explanation" about this file(ryzom.xml) are given in another article: ([[https://khaganat.net/wikhan/en:syntaxexmlpatchserver|The syntax of the patch server .xml files]]).
It explains how to configure the file for proper operation.
This guide will continue with the DEFAULT example below(and is only for testing purpose).
</WRAP>


Our(DEFAULT) configuration file will look like this:
<code xml ryzom.xml>
<xml>
	<_Categories>
		<_Category>
			<_Name type="STRING" value="khanat_lirria"/>
			<_IsOptional type="SINT32" value="0"/>
			<_UnpackTo type="STRING" value="./user/"/>
			<_IsIncremental type="SINT32" value="1"/>
			<_Files type="STRING" value="patch_lirria.bnp"/>
		</_Category>
	</_Categories>
	<_IndexFileName type="STRING" value="ryzom.hist"/>
	<_PatchDirectory type="STRING" value="patch_game/patch/"/>
	<_BnpDirectory type="STRING" value="patch_game/bnp/"/>
	<_RefDirectory type="STRING" value="patch_game/ref/"/>
	<_NextVersionFile type="STRING" value="patch_game/Lirria.version"/>
	<_ClientIndexFileName type="STRING" value="ryzom"/>
</xml>
</code>

These indicated parameters will gradually increment the content of our .bnp . 
It will add the new files(and the .bnp files itself), after being downloaded by the client.
The "data" will be unpacked in '' /user '' and will also overwrite old file versions.
This is considered good practice on a testing bases.

==== Enabling the patch server at the database level ====

Since the system is a "database kind", we must inform(the database) that we are activating the patch server. To do this, we will use some commands in MySQL.

We will assume that your domain number is 12, otherwise change the value to your liking.
First, activate the patch server(by setting the patch_version value to 1 instead of 0):
OBS: "0" is default!
<code sql>
USE nel;
UPDATE domain SET patch_version=1 WHERE domain_id=12;
</code>

Then enter the server address in the field ''patch_urls'':
<code sql>
USE nel;
UPDATE domain SET patch_urls='http://lirria.khaganat.net/patch' WHERE domain_id=12;
</code>

==== Creating the first patch ====
<WRAP center round info 90%>
OBS: From here on, we assume that you already have made .bnp files AND copied it to it's right place.
IF NOT, follow this guide: https://khaganat.net/wikhan/en:files_bnp before continuing.
</WRAP>
Now.. we are gonna create our patch, which will supply the .bnp in its original state to the client. We will 
reuse the same command, but with a different instruction this time:
<code bash>
~/patch_service$ patch_gen updateProduct patch_game/ryzom.xml
</code>

OR(if not global)..

<code bash>
~/patch_service$ ./patch_gen updateProduct patch_game/ryzom.xml
</code>



=== Creating the Release Note ===
Now, let's continue and create a info file(at the root directory of the patch) that will serve to disseminate information about patched data. This will be a .php file.. and it will be able to receive following client informations:
  * version: The patch version ;
  * lang: The language of the client ;
  * ca: The Shard connection
  * startPage : <wrap tip>to define</wrap>
So.. let's create a simple php index file(with html content):
<code bash>
~/patch_service$ nano patch_game/patch/index.php
</code>
<code html index.php>
<html>
  <head>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  </head>
 <body>
  <h1>New test data</h1>
  <p>An update will now be performed to your client(the /user directory to be exact).
   Please help us test the deployment of our free MMORPG server!!
 </body>
</html>

</code>

The content is now ready to be released, and it only remains to let customers know about it.

===== Configuring the Apache server =====

We will assume that you already have a functional Apache server, and that you just have created a new VirtualHost. If the "home" directory(of the user who manages the server) is named "compil", it must have these parameters(if not, needed to be adapted according to your own parameters):

Our wish here is to have a simple address(with port for the patch server), which will be in the form of: 
<code bash>
http://lirria.khaganat.net:43435

(Our game server being installed at): http://lirria.khaganat.net
</code>

Firstly, we must install some modules for the Apache server(if not already done in advance):

<code bash>
~/patch_service$ sudo a2enmod proxy
~/patch_service$ sudo a2enmod proxy_http
</code>

We then add in the VirtualHost file(listening to port 80) the following line:
<code conf>
ProxyPass       /patch/ http://lirria.khaganat.net:43435/
</code>

We then define our dedicated virtual host as follows:

<code conf>
<VirtualHost *:43435>
ServerName lirria.khaganat.net
DocumentRoot /home/compil/patch_service/patch_game/patch/

  <Directory "/home/compil/patch_service/patch_game/patch">
     Options -Indexes 
     AllowOverride All
     Require all granted
  </Directory>   

</VirtualHost>

</code>

OBS: Option ''-Indexes'' Blocks the display of default directories for security reasons.\\

Now open the port 43435 in Apache:
<code bash>
~/sudo nano /etc/apache2/ports.conf
</code>
Add the following line: 
<code>
Listen 43435
</code>
Once all this have been completed, we restart the Apache service by typing:
<code bash>
sudo service apache2 restart
</code>

And now we need to set the right rights(right? all righty then..).   .-)

<code bash>
cd && sudo chown -R compil:www-data patch_service | chmod g+w -R patch_service
</code>

===== Announcing the availability of the patch =====

We must then notify the customers that the patch number "1" is ready to be distributed.
This will be done by using the file ''Lirria.version'' located in the directory ''/patch'', served by Apache:
<code bash>
cd ~/patch_service && nano patch_game/patch/Lirria.version
</code>

OBS!! It is enough to indicate the values in order(1 - space - 1 - return carriage):
<code>
1 1

</code>
This will be enough to say that the patch number 1 is ready for patching. In the future, this syntax will change to something even easier, like: "2 to serve the patch 2".. and so on.

The function of the second digit is to announce itself to the .php page as '' version '', so it simply changes the version number.


===== Client Configuration =====

For the client to be able to access the patches, there are two solutions.

==== DEV Client ====


The better option is to tell the client through it's "client_default.cfg". Therefore, we will have a look at these lines:
<code xml|client_default.cfg>
PatchWanted          = 1;
PatchUrl = "http://lirria.khaganat.net:43435";
RingReleaseNotePath = "http://lirria.khaganat.net/patch/index.php";
</code>
<WRAP center round tip 90%>
OBS: It is now ''PatchUrl'' and NOT ''PatchServer'', as it is obsolete.
</WRAP>

The last line(in this config file) returns to the file that we created for the: [[https://khaganat.net/wikhan/en:realese_notes|Release Notes.]]

==== Client FV ====

For the "FV client" to work, it must be compiled with the option: ''WITH_RYZOM_PATCH''.. to be able to access the patch server. IF without any other option indicated, it will automatically connect to the patch server indicated by the server(noted above in the MySQL database).

The client will look for release notes at the following hardcoded addresses:
<code cpp>
RingReleaseNotePath = "http://" + WebIgMainDomain + "/releasenotes_ring/index.php";
ReleaseNotePath = "http://" + WebIgMainDomain + "/releasenotes/index.php";
</code>

It will therefore be necessary to ensure that the address ''WebIgMainDomain'' is correctly entered in the client_default.cfg

IF the FV client has also received the option ''WITH_RYZOM_CUSTOM_PATCH_SERVER'', It will behave like the DEV client...  and must therefore be given the necessary lines in its client_default.cfg:
<code xml|client_default.cfg>
PatchWanted          = 1;
PatchUrl = "http://lirria.khaganat.net:43435";
RingReleaseNotePath = "http://lirria.khaganat.net/patch/index.php";
</code>

===== And that is that! =====

With this kind of configuration, it is important to make sure that the directory ''unpack'' is empty of any file ''.version'' or''.idx''(under the first start) for this first patch to work. Afterwards, the system will keep track of the patches received in this directory, so be sure to leave these files untouched(under otherwise penalty of having to repatch your client of(now) value: 0). With our example, the new elements will automatically decompress in your ''user''directory when the client restarts after the download(patching).

Now, all you have to do is to launch your game client and see it patching!!

If you're working from repositories(like us) for server and client updates, you can see this "how to" for being able to quickly create patches when making new data available: [[en:Game Data Updates]]

{{tag>Server MMORPG tutorial shard}}