Difference between revisions of "Deployment/howto"

From Kiwix
Jump to navigation Jump to search
m
 
(10 intermediate revisions by 2 users not shown)
Line 7: Line 7:
Kiwix provides different technical solutions:
Kiwix provides different technical solutions:


* '''kiwix''', a desktop application. You may install it on any computer with a screen. It runs on Windows, OSX and Linux. This software provides a lot of features (bookmarks, content manager, ...) and is the most common used software.
* '''kiwix''', a desktop application. You may install it on any computer with a screen. It runs on Windows, OS X and Linux. This software provides a lot of features (bookmarks, content manager, ...) and is the most common used software.


* '''[[kiwix-serve]]'''. a HTTP daemon application. You may run kiwix-serve on any computer (which could be without screen, like a server) an each other computer (called client) may access to the content served by kiwix-serve through the network. Client should only start a Web browser, type the name or ip of the server to access to the content. With kiwix-serve you can read the article and use the fulltext search engine, but it does not provide all the feature of the Kiwix desktop application. Currently kiwix-serve only runs on Linux, but we will port it soon to Windows and Mac.
* '''[[kiwix-serve]]'''. a HTTP daemon application. You may run kiwix-serve on any computer (which could be without screen, like a server) and others computers (called clients) may access the content served by kiwix-serve through the network. Clients should only start a web browser, type the name or IP of the server to access the content. With kiwix-serve you can read the article and use the fulltext search engine, but it does not provide all the features of the Kiwix desktop application. Currently kiwix-serve only runs on Linux, but we will port it soon to Windows and Mac.


= Define your target =
= Define your target =
Line 15: Line 15:
Before starting to find a technical solution to deploy, you need to ask you a few essential questions:
Before starting to find a technical solution to deploy, you need to ask you a few essential questions:


* What is the audience? This is essential to know a little bit about the audience to increase the positive impact of your project. You have especially to choose a content which is adapted. You need also to check if the future users will need help to learn how to deal with what you will provide, content and software. Estimate the time you will need to invest to help your future users. You need also to know how much persons should be able to use Kiwix at the same time.
* What is the audience? It is essential to know a little bit about the audience to increase the positive impact of your project. You have especially to choose a content which is adapted. You need also to check if the future users will need help to learn how to deal with what you will provide, content and software. Estimate the time you will need to invest to help your future users. You need also to know how much persons should be able to use Kiwix at the same time.


* What is the technical environment? You need to know what is the best way to install Kiwix. So this is essential to know if the computer are not too old? What are the Operation systems? Do you have a LAN or not? How is it possible to install the software (perl LAN, DVD, USB)? etc.
* What is the technical environment? You need to know what is the best way to install Kiwix. So this is essential to know if the computer are not too old? What are the Operation systems? Do you have a LAN or not? How is it possible to install the software (perl LAN, DVD, USB)? etc.


= Choosing your content =
= Choose your content =


Kiwix is a pure ZIM reader, that means that the content should be in the ZIM format. You may find ZIM files here:
Kiwix is a pure ZIM reader, that means that the content should be in the ZIM format. You may find ZIM files here:


* Download ZIM files from Kiwix Web site at http://download.kiwix.org/zim/0.9/. You may find here big ZIM files with all articles, thumbnails and categories in a Wikipedia (one file per language).
* Download ZIM files from Kiwix website at http://download.kiwix.org/zim/0.9/. You may find here big ZIM files with all articles, thumbnails and categories in a Wikipedia (one file per language).
* Make your own ZIM files from Wikipedia itself using https://secure.wikimedia.org/wikipedia/en/wiki/Special:Book. This is a good solution for creating small collection of ZIM files.
* Make your own ZIM files from Wikipedia itself using https://secure.wikimedia.org/wikipedia/en/wiki/Special:Book. This is a good solution for creating small collection of ZIM files.


If you search a content reviewed for Children, you may be interesting in the [http://download.kiwix.org/zim/0.9/schools-wikipedia-full-20081023-rc5.zim Wikipedia for School selection].
If you search a content reviewed for Children, you may be interesting in the [http://download.kiwix.org/zim/0.9/schools-wikipedia-full-20081023-rc5.zim Wikipedia for School selection].


= Building your package =
= Build your package =
[[File:Library screenshot.png|right|thumb|Screenshot of the library in Kiwix]]
[[File:Library screenshot.png|right|thumb|Screenshot of the library in Kiwix]]


Before deploying the solution, you have to put your content (the ZIM file(s)) with Kiwix (the software itself). Maybe The Kiwix project already did it for you, so check [http://download.kiwix.org/portable/ here] to see if you have your package. Otherwise, you will have to do it by yourself. This part of the process is the most complicated.  
Before deploying the solution, you have to put your content (the ZIM file(s)) with Kiwix (the software itself). Maybe the Kiwix project already did it for you, so check [http://download.kiwix.org/portable/ here] to see if we already provide what you need. Otherwise, you will have to do it by yourself and this part of the process is the most complicated.


To do that you will need the help of 3 different console tools:
To build packages, 3 different console tools are available:
* [[kiwix-index]], a tool to create a fulltext search index
* [[kiwix-index]], a tool to create a fulltext search index,
* [[kiwix-manage]], a tool to manipulate library XML file
* [[kiwix-manage]], a tool to manipulate library XML file,
* [[kiwix-install]], a tool which offers a simple way to create a data directory (beside the kiwix binary) with everything necessary (ZIM, index and library) and directly usable by kiwix.
* [[kiwix-install]], a tool which offers a simple way to create a data directory (beside the kiwix binary) with everything necessary (ZIM, index and library) and directly usable by kiwix.


Kiwix knows about the available contents and indexes (to allow the fulltext search) by reading one (or many) so called ''library file(s)'' which are XML files ([[FeedFormat|more information about the XML format]]). In kiwix, you have the so called "[[library]]" (see screenshot beside) which is the visualisation of the information available about contents. Each time kiwix starts, it try to find thes XML library file to know more about available content. So, library XML files should be located to [[Library#Location|specific places]] and in general kiwix data storage follow [[Build_a_DVD#File_structure|these rules]].
Kiwix knows about the available contents and indexes (to allow the fulltext search) by reading one (or many) so called ''library file(s)'' which are XML files ([[FeedFormat|more information about the XML format]]). In Kiwix itself, you have the "[[library]]" (see screenshot beside) which is the visual form of the information available in library XML files. Each time Kiwix starts, it tries to find the XML library files to know more about available content. So, library XML files should be located to [[Library#Location|specific predefined places]] and in general Kiwix data storage follow [[Build_a_DVD#File_structure|these rules]].


So if you want for example to spread Kiwix for Windows with foobar.zim, you have to do:
So if you want for example to spread Kiwix for Windows with foobar.zim, you have to do:
* Download the last version of kiwix for windows from http://www.kiwix.org
* Download the latest version of Kiwix for Windows from http://www.kiwix.org
* Unzip Kiwix in the directory "dvd" (so your binary should be in dvd/kiwix/kiwix.exe)
* Unzip Kiwix in the directory "dvd" (so your binary should be in dvd/kiwix/kiwix.exe)
* Download or build your ZIM file.
* Download or build your ZIM file.
* call kiwix-install like following: kiwix-install --buildIndex ADDCONTENT path/to/foobar.zim path/to/directory_called_dvd
* call kiwix-install like this: kiwix-install --buildIndex ADDCONTENT path/to/foobar.zim path/to/directory_called_dvd
* copy the "dvd" directory on a DVD or USB stick
* copy the "dvd" directory on a DVD or USB stick


At kiwix.org we have a PERL script to do that (and a few additional small things) quickly. If you are a PERL hacker you may [http://kiwix.svn.sourceforge.net/viewvc/kiwix/tools/scripts/buildDistributionFile.pl?view=markup have a look at it].
At kiwix.org we have a PERL script to do that (and a few additional small things) quickly. If you are a PERL hacker you may [http://kiwix.svn.sourceforge.net/viewvc/kiwix/tools/scripts/buildDistributionFile.pl?view=markup have a look to it].


But, because kiwix-serve is less developed as kiwix, both still work a little bit differently. [[Kiwix-serve]] does not work with libraries, we still do not have implemented that. To run kiwix-serve, you simply need to have a ZIM file and a fulltext search index in option. To build the fulltext search index, you need the kiwix-index binary which is trivial to use. Currently, kiwix-serve only runs on GNU/Linux. If you have a permission issue, please you a port over 1024, otherwise, you will need root permission to run it.
But, because kiwix-serve is less developed than Kiwix, both still work a little bit differently. [[Kiwix-serve]] does not work with libraries, we still do not have implemented that. To run kiwix-serve, you simply need to have a ZIM file and a fulltext search index in option. To build the fulltext search index, you need the kiwix-index binary which is trivial to use. Currently, kiwix-serve only runs on GNU/Linux. If you have a permission issue, please open a port over 1024, otherwise, you will need root permission to run it.


= Deploying =
= Deploy =


There are many way to deploy kiwix over network of using removable mass storage solution like DVDs or USB sticks. Here are a few remarks:
There are many ways to deploy Kiwix: over a local network or using removable mass storage solution like DVDs or USB sticks. Although we won't provide a big list of trivial ways to do that, we want to share with you a few remarks:


* '''Kiwix works without installation''', so you do not need to install it on the system (with administrator permission) to have a 100% working solution. Copy the data somewhere and the hard-disk and it will work. The only advantages to install it, is to have it for all users having an account on the computer and have nice icons in the application menu or associated to the ZIM files.
* '''Kiwix works without installation'''. You do not need to install it on the system (with administrator permission) to have a 100% working solution. Copy the data somewhere on the hard disk and it will work or if this is a Windows, run it directly from the DVD. The only advantages you will have by installing it, will to have it for all users having an account on the computer and have nice icons in the application menu or associated to the ZIM files.


* '''Take care to the OS''', OSes have their own restrictions and specificities. For example, this is not possible to have a portable version (everything running on a DVD/USB stick) with OSX, because for OSX, we only have a dmg file. On Linux, you can not really make a portable version because, removable storage are per default mounted with -noexe permission, so you will have to copy everything to the harddisk. See next point to get more informations about GNU/Linux.
* '''Take care to the computer OSes'''. OSes have their own restrictions and specifications. For example, it is not possible to have a portable version (everything running on a DVD/USB stick) with OS X, because for OS X, we only have a dmg file. On Linux, you can not really make a portable version because, removable storage are per default mounted with -noexe permission, so you will have to copy everything to the hard disk.


* '''On GNU/Linux, this is unusual to install software not coming from the software repository'''. So we (still) do not provide a method to install kiwix (the static version available online for download) with content on a GNU/Linux system. We recommand to use the packages if possible and copy the "[[Build_a_DVD#File_structure|data]]" directory to /usr/[local/]share/kiwix/
* '''On GNU/Linux, this is unusual to install software not coming from the software repository'''. So we (still) do not provide a method to install Kiwix (the static version available online for download) with content on a GNU/Linux system. We advise (if possible) to use instead the package and copy the "[[Build_a_DVD#File_structure|data]]" directory to /usr/[local/]share/kiwix/.


* ''Take care to architectures''. All kiwix binaries available to download on the Web site are statically linked binaries compiled for x86 32 architectures. All of them should work also on x86 64 architectures (for GNU/Linux: as long as the standart libs in 32 bits are installed).
* '''Take care to the computer architectures'''. All Kiwix binaries available to download on the website are statically linked binaries compiled for x86 32 architectures. All of them should work also on x86 64 architectures (for GNU/Linux: as long as the standard libs in 32 bits are installed).


= Getting Support & Assistance =
= Getting Support & Assistance =
* [http://reportabug.kiwix.org Report a bug] or [http://requestafeature.kiwix.org request a feature].
* Email: kiwix-developer (at) lists.sourceforge.net or kelson (at) kiwix.org
* Jabber: kelson (at) kiwix.org
* IRC: #kiwix on irc.freenode.net [irc://irc.freenode.net/kiwix join] or [http://webchat.freenode.net/?channels=#kiwix use web interface]


= See also =
= See also =
* [[File:Wikipedia_for_Schools_walkthrough.odt|Howto deploy Wikipedia for school]]
* [[File:Wikipedia_for_Schools_walkthrough.odt|Howto deploy Wikipedia for school]]
* [[Build a DVD]]
* [[Build a DVD]]

Latest revision as of 03:21, 15 August 2015

This Deployment HOWTO is an online documentation to help everyone wanting to provide deploy Kiwix. Feel free to make remarks or ask question in the talk page.

Kiwix 0.9 alpha1 screenshot en.png
0.9 alpha1 version screenshot (screencast)

Technical solutions

Article served via HTTP by kiwix-serve

Kiwix provides different technical solutions:

  • kiwix, a desktop application. You may install it on any computer with a screen. It runs on Windows, OS X and Linux. This software provides a lot of features (bookmarks, content manager, ...) and is the most common used software.
  • kiwix-serve. a HTTP daemon application. You may run kiwix-serve on any computer (which could be without screen, like a server) and others computers (called clients) may access the content served by kiwix-serve through the network. Clients should only start a web browser, type the name or IP of the server to access the content. With kiwix-serve you can read the article and use the fulltext search engine, but it does not provide all the features of the Kiwix desktop application. Currently kiwix-serve only runs on Linux, but we will port it soon to Windows and Mac.

Define your target

Before starting to find a technical solution to deploy, you need to ask you a few essential questions:

  • What is the audience? It is essential to know a little bit about the audience to increase the positive impact of your project. You have especially to choose a content which is adapted. You need also to check if the future users will need help to learn how to deal with what you will provide, content and software. Estimate the time you will need to invest to help your future users. You need also to know how much persons should be able to use Kiwix at the same time.
  • What is the technical environment? You need to know what is the best way to install Kiwix. So this is essential to know if the computer are not too old? What are the Operation systems? Do you have a LAN or not? How is it possible to install the software (perl LAN, DVD, USB)? etc.

Choose your content

Kiwix is a pure ZIM reader, that means that the content should be in the ZIM format. You may find ZIM files here:

If you search a content reviewed for Children, you may be interesting in the Wikipedia for School selection.

Build your package

Screenshot of the library in Kiwix

Before deploying the solution, you have to put your content (the ZIM file(s)) with Kiwix (the software itself). Maybe the Kiwix project already did it for you, so check here to see if we already provide what you need. Otherwise, you will have to do it by yourself and this part of the process is the most complicated.

To build packages, 3 different console tools are available:

  • kiwix-index, a tool to create a fulltext search index,
  • kiwix-manage, a tool to manipulate library XML file,
  • kiwix-install, a tool which offers a simple way to create a data directory (beside the kiwix binary) with everything necessary (ZIM, index and library) and directly usable by kiwix.

Kiwix knows about the available contents and indexes (to allow the fulltext search) by reading one (or many) so called library file(s) which are XML files (more information about the XML format). In Kiwix itself, you have the "library" (see screenshot beside) which is the visual form of the information available in library XML files. Each time Kiwix starts, it tries to find the XML library files to know more about available content. So, library XML files should be located to specific predefined places and in general Kiwix data storage follow these rules.

So if you want for example to spread Kiwix for Windows with foobar.zim, you have to do:

  • Download the latest version of Kiwix for Windows from http://www.kiwix.org
  • Unzip Kiwix in the directory "dvd" (so your binary should be in dvd/kiwix/kiwix.exe)
  • Download or build your ZIM file.
  • call kiwix-install like this: kiwix-install --buildIndex ADDCONTENT path/to/foobar.zim path/to/directory_called_dvd
  • copy the "dvd" directory on a DVD or USB stick

At kiwix.org we have a PERL script to do that (and a few additional small things) quickly. If you are a PERL hacker you may have a look to it.

But, because kiwix-serve is less developed than Kiwix, both still work a little bit differently. Kiwix-serve does not work with libraries, we still do not have implemented that. To run kiwix-serve, you simply need to have a ZIM file and a fulltext search index in option. To build the fulltext search index, you need the kiwix-index binary which is trivial to use. Currently, kiwix-serve only runs on GNU/Linux. If you have a permission issue, please open a port over 1024, otherwise, you will need root permission to run it.

Deploy

There are many ways to deploy Kiwix: over a local network or using removable mass storage solution like DVDs or USB sticks. Although we won't provide a big list of trivial ways to do that, we want to share with you a few remarks:

  • Kiwix works without installation. You do not need to install it on the system (with administrator permission) to have a 100% working solution. Copy the data somewhere on the hard disk and it will work or if this is a Windows, run it directly from the DVD. The only advantages you will have by installing it, will to have it for all users having an account on the computer and have nice icons in the application menu or associated to the ZIM files.
  • Take care to the computer OSes. OSes have their own restrictions and specifications. For example, it is not possible to have a portable version (everything running on a DVD/USB stick) with OS X, because for OS X, we only have a dmg file. On Linux, you can not really make a portable version because, removable storage are per default mounted with -noexe permission, so you will have to copy everything to the hard disk.
  • On GNU/Linux, this is unusual to install software not coming from the software repository. So we (still) do not provide a method to install Kiwix (the static version available online for download) with content on a GNU/Linux system. We advise (if possible) to use instead the package and copy the "data" directory to /usr/[local/]share/kiwix/.
  • Take care to the computer architectures. All Kiwix binaries available to download on the website are statically linked binaries compiled for x86 32 architectures. All of them should work also on x86 64 architectures (for GNU/Linux: as long as the standard libs in 32 bits are installed).

Getting Support & Assistance

See also