*********************************************************************
*                                                                   *
*                      KIWIX-PLUG                                   *
*                                                                   *
*********************************************************************

This is the documentation about Kiwix-plug. Kiwix-plug is a solution
allowing everyone to set up an open Wifi kiosk to deliver contents
available in the ZIM format. The solution is adapated for the
Globalscape Dreamplug, use the Kiwix-serve technology and many open
source softwares. This documentation explains how to setup Kiwix-plug.

If you want to install kiwix-plug on a RaspberryPi, please read
README_RASPBERRYPI

== Requirements ==
* A Dreamplug
  (http://www.globalscaletechnologies.com/p-54-dreamplug-devkit.aspx)
* An empty USB key or SDcard (with enough space, be careful) to store
  the ZIM files an a few other things
* ZIM files you want to spread
  (http://openzim.org/ZIM_File_Archive)
* A wireline LAN allowing access to Internet with a free RJ45 port
* A DHCP on the LAN able to automaticaly deliver IPs to new devices
* A computer with a UNIX and a root access, GNU/Linux is perfect. This
  computer needs a free USB/SDcard port to put the flash drive to
  setup. You need free space on your hard-disk: at least 3x the size
  of the ZIM files you want to copy on the USB key.
* Preparing the "master" (mainly downloading the ZIM files and computing
  the full-text search engine indexes) can take hours, depending of
  the size of the contents and the power of your computer. Do not wait
  the last minute!

The setup process has 3 steps, based on 3 scripts:

0 Get the code to do all the stuff

1 Run "setup_master.sh" to prepare everything on your computer. It
  especialy downloads the binaries to install on the plug, compute
  indexes, etc.

2 Run "setup_plug.sh" to configure your plug.

3 Run "setup_usbkey.sh" to copy everything necessary on your usb key

4 OPTIONAL: Add a router to the plug to increase the wireless coverage

== Retrieving the code ==

The code to setup the Dreamplug and the flash drive is available on
Internet here: https://github.com/kiwix/plug

To retrieve it you need to have git (code version control system)
client installed on your computer. If you use a Debian based GNU/Linux
distribution you can type (like Ubuntu): "apt-get install git"
in the console.

To download the code, type:
git clone https://github.com/kiwix/plug.git

You will get a "kiwix-other/plug" directory. Go inside.

== Setup the master ==

This will do all preparatory work before setting up the Dreamplug and
the flash drive.

You need to know at this moment what for contents (ZIM files) you want
to install on the plug computer. Copy thus file in "./data/content/"

Run "./setup_master.sh", this will take many minutes to downloads
binaries for the plug and also compute fulltext indexes for each ZIM
files. Be patient...

Run "./setup_master.sh clean" to clean everything (but not the ZIM
files) was downloaded before re-preparing the master.

== Setup the plug ==

We will now do a minimal configuration of the plug computer. You need
to plug it to the power and link it (using the "external" RJ45 LAN
port on the side) with a RJ45 on the same LAN switch as your master
computer.

The plug should be automaticaly detected, but to avoid any conflicts
and problem put always only one plug at the same time to the LAN. If
everything goes right the plug should get an IP and the blue LED
should blink.

Run "./setup_plug.sh", this should find the plug, connect per ssh to it
and do a few things. This will be fast, because this only install if
necessary a few packages, add an init.d script and initiate the clock.

== Setup the flash storage ==

You need to put a free USB key to your computer and run the script
"./setup_usbkey.sh". This will copy many things to the USB key, so
this can take many minutes, be patient...

== Optional: Add a router ==

This could be useful to increase the wifi coverage of the whole setup.
To achieve to do that, you can add a new wifi hotspot which is linked
per RJ45 to the plug. the router you add acts like a new wifi hotspot
providing exactly the same as the original hotspot... So it's like
having two plugs.

So, you need an additional router. This tutorial works with the
Netgear N300 but you can use any router providing similar
functionalities.

To configure the router, connect to its web user interface (default IP
should be 192.168.1.1) and:
* Change its ip to 192.168.2.2
* Shutdown its DHCP daemon
* Remove any password from the WIFI configuration
* Change the SSID to "KIWIX"

We provide a pre-configured file you can already play in the Netgear N300:
http://download.kiwix.org/dev/kiwix-plug/NETGEAR_WNR3500Lv2_KIWIX-PLUG.cfg

After that you need to plug the router with a RJ45 cable to the
*external* (they are two) RJ45 plug of the dreamplug. You should get
in addition a new "KIWIX" hotspot.

== Conclusion ==

You should have now a perfectly working kiwix-plug. Remove the RJ45
cable from the plug computer, put the flash drive to the plug computer
and restart it. You should see now a new Wifi network called
"KIWIX_PLUG" appearing. Connect to it using your
laptop/smartophone/tablet and open a new Web browser windows. You
should land to the Kiwix-plug Welcome page.

Enjoy! To any problem: http://reportabug.kiwix.org