Download the file ks-install.jar from the download site and save it in a known location. The file is a self-extracting JAR file. Start the installation process by double clicking the file or, if you are using a terminal, by typing:
java -jar ks-install.jar
The following window will pop-up
Read the installation details
Read and accept the license agreement to continue
The installer will ask you for an installation directory (the default is a directory called Kaleidoscope under your home page). Take note of the chosen directory. You will need that information later on.
You will be asked what packs to install. For a regular installation you may keep the default selection. If you are upgrading and wish to save all of your existing configuration data (Contacts, Public keys, etc...) choose Upgrade Only. On a Windows platform you may choose to unpack the attached Apache Installer to be used as a proxy server with Kaleidoscope.
The installer will unpack the necessary files into your chosen directory.
The installer will now invoke a series of post-install tasks. Those may vary between different platforms. Kaleidoscope is generating a public/private key pair for this host (your Kaleidscope identity), random ports are chosen, and a certificate is generated to be used with TLS protocol. Finally, the installer will start Kaleidoscope and run it in the background.
Important note: On Windows, Kaleidoscope is installed as a service and will be restarted after reboots. On other platforms, you will need to start Kaleidoscope after reboots by changing the directory to one where Kaleidoscope was installed and typing ./ksctl start
The last page will appear. That's It. You are half way there. See the next section on installing the Firefox plug-in.
Before starting this part, make sure that the back-end was installed successfully and you know the installation directory.
Start-up Firefox and open a new screen (or tab). In the address line type:
file://<path_to_installation_directory>. E.g. file://home1/user/Kaleidoscope
A list of all files in Kaleidoscope's installation directory will appear. Locate a file called kscope.xpi and click on it. Firefox will ask you a series of installation-related questions which should guide to the point where you are asked to restart Firefox.
After Firefox restarts, Kaleidoscope's Configuration Wizard should appear.
Select the directory in which Kaleidoscope was installed. If you choose the wrong directory, or the installation process completed with errors, the Wizard may complain and you will not be able to proceed until those problems are solved (try reinstalling the back-end.)
The main configuration window will show you the ports that Kaleidoscope randomly selected for its operation. You may keep them or change them. You are also asked for your Hostname. If you have a Domain name, a Dynamic DNS domain name (recommended), or a globally routable IP address - you should enter them here. If you are behined a NAT, it is not important what hostname you specify.
This section guides you through an installation as a client (not running a proxy server), so we keep the bottom checkbox unchecked. See below how to install Kaleidoscope to work with an existing proxy server.
You are asked whether you are behind a NAT or not. See this Wikipedia article to learn more about NATs. Hosts behind NATs may not be reachable from the Internet (unless port forwarding is used). Kaleidoscope uses a system of so-called mailboxes to allow hosts behind NATs to receive data. Kaleidoscope uses some well-known mailbox servers, but you may choose a different one if you know one. (When you are connected to other contacts, Kaleidoscope will be able to suggest new mailboxes.) If you choose an invalid mailbox, or one that is down, It will only affect your communications with other hosts behind NATs.
At this point Kaleidoscope has enough information to generate your full identity details. This is the data that you will send to your trusted friends to make them your Kaleidoscope contacts. Admire this for a while and move on. You may copy this data to a different location or even send it now to other Kaleidoscope users. You will always be able to view this data by using Kaleidoscope's configuration menu.
This page lets you add contacts if you already have their contact details. Moreover, you will be asked whether you would like to add a special kind of contact called an Initial Contact. The Initial Contact is a central contact that may help you to bootstrap the system, however, since establishing trust in Kaleidoscope is a mutual process, this will invlove sending your contact details to that central server. The data is sent over an encrypted channel authenticated by a certificate shipped with the software. Since anyone can establish trust with the Initial Contact, we recommend that if you already know some Kaleidoscope users, then do not add the the Initial Contact. However, If you do not know anyone using Kaleidoscope and you would still like to benefit from this system, then choose to add the Initial Contact.
That's it. All done and you are good to go. To really make use of Kaleidoscope, see the section about adding contacts.
Configuring Kaleidoscope on a host running a proxy server is only slightly different from the instructions above. First of all you will need to have your proxy server running and accepting connections. You should know what port your proxy server is listening on. It is highly recommended that you use a dedicated proxy server for Kaleidoscope only. This will allow you to harden the security of that server. Mainly, it is recommended that you configure your Proxy Server to only accept connection for the localhost (i.e. Kaleidoscope). This should make it harder for malicious users to abuse your proxy server.
Check the box saying I am running a Proxy Server and click next.
You will be asked what port your server is listening on. Click Run Tests To check your server for compatibility with Kaleidoscope. If all tests pass, your server should work well with Kaleidoscope. If some tests fail, see the displayed details. This may block users from using your proxy server.
Follow the instructions regarding the rest of the Wizard pages as described above.
You may access Kaleidoscope's configuration window by opening Firefox's Tools menu and choosing Kaleidoscope. All of the information gathered by the Wizard plus more system information and other advanced features are found under that window.
Adding a contact in Kaleidoscope is a mutal process that requires both parties to know and trust each other. You will exchange Identity details with your new contact. only when both sides have entered into the system the details they received, will you and your new contact be able to exchange Kaleidoscope messges. Do not establish trust with people you do not know or trust. This will affect your ability to use Kaleidoscope, but may also indirectly affect other users. The system will allow you to add at most 30 contacts. Still, if have no contacts at all or a very small number of contacts, you might not learn any addresses of proxy servers.
As part of the process, you will need to send you contact details to the new contact. Choose the This Host tab and copy the entire text in the My Details textbox. Make sure you copy all the text. You may use the Copy to Clipboard button.
You and your new contact need to choose a mechanism to exchange your details. This may vary according to your beliefs in the security of different communication media. You may send it by email, meet in person and exchange printed details, use carrier pigeons or use any other discreet communication mechanism of choice.
You should have the details that you received from your new contact. Choose the Contacts tab and click on the Add a Contact button.
A dialog with two textboxes will appear. Use the upper box to give your new contact an internal name. This can be any name, but avoid duplicates. Paste the details you received from your contact in the lower box. Make sure all the data was pasted correctly. Clicking Advanced will you give the more tedious option of adding the new contact's details field by field. When all the details are entered click on OK.
You now have the new Contact in your Contacts List. You may delete it or edit its details at any time. Close the configuration window for the changes to take effect. Kaleidoscope will show you when was the last time a message was received from this contact. If this value does not change, but you know your contact is up, perhaps there is a problem with the contact details. (It is possible that some of your contact's details changed and he/she failed to notify you.)
On Windows - go to Control Panel->Administrative Tools->Services and select Kaleidoscope. You may start, stop and restart the service.
On Linux and Mac - use the ksctl script found under Kaleidoscope's installation directory.