Repositories

A directory which is synchronised by CloudStore is called a repository. CloudStore synchronises all files and sub-directories of such a repository. This means: If you for example add or modify a file, then this file is automatically copied to the other repositories.

Only files and directories within a repository are replicated. Other files/directories on your computer are - of course - ignored.

Client and server

CloudStore consists of a client and a server component. The client alone can synchronise between local repositories (e.g. backup from your hard drive to your USB stick). To synchronise from/to a remote repository requires the CloudStore server to be online there.

The client establishes the connection to one or more remote servers as needed.

The most common use-case is you running a server at home (using a dynamic-DNS-provider) and wanting to synchronise your files on your workstations, your notebooks etc. Of course, you might run CloudStore on a rented server in a data center or within your LAN only, too.

Install Java

If you didn't install Java, yet, you should do this now. Please download and install either Oracle Java or the OpenJDK.

If you use Ubuntu, you could open a shell and enter the following command to install the OpenJDK:

sudo apt-get install openjdk-7-jre

Download

Please download the CloudStore client and server to your local machine. It is recommended that you download the PGP signatures, too, and verify the authenticity of the binaries.

If you prefer to build directly from the sources, please consult the Development page.

In the following, we assume that you downloaded the files into your ~/Downloads/ directory.

Copy the CloudStore archive to your server machine

The CloudStore server needs to be running on your server myserver.mydomain.tld. Therefore, you have to copy it to this machine. Additionally, you'll need the CloudStore client to perform administrative tasks like creating repositories. However, the CloudStore client is contained in the server archive, hence you only have to upload one file.

We recommend using rsync or scp to copy the file:

rsync -avP ~/Downloads/co.codewizards.cloudstore.server-1.0.1-SNAPSHOT-bin.tar.gz user@myserver.mydomain.tld:/tmp/

or

scp -p ~/Downloads/co.codewizards.cloudstore.server-1.0.1-SNAPSHOT-bin.tar.gz user@myserver.mydomain.tld:/tmp/

Extract the CloudStore archive on the server

Now, one tar.gz file is located in the /tmp/ folder on your server. To continue, you open a shell to the server machine:

ssh user@myserver.mydomain.tld

We uploaded the file to /tmp/, hence we go into this directory, extract the tarball there and then move the extracted directory into the user's home:

cd /tmp
tar xzf co.codewizards.cloudstore.server-1.0.1-SNAPSHOT-bin.tar.gz
mv cloudstore ~/

Create a repository on the server

There is the directory named cloudstore in your user's home containing both server and client with its CLI (command line interface). We use this CLI to create a new directory and make it a CloudStore repository:

cd ~
~/cloudstore/bin/cloudstore createRepo cloudstore-repos/myDocuments -createDir

Note, that this creates all parent-directories as needed. Hence the folder ~/cloudstore-repos, which likely didn't exist yet, is created together with the actual repository “myDocuments”.

Additionally, this command automatically creates an alias named "myDocuments" (case-sensitive!).

Start the CloudStore server

There is the directory named cloudstore in your user's home containing the server. Inside this directory, there's a shell script which can be used to start the server:

cloudstore/bin/cloudstore-server

By default, the server listens on port 8443. Please make sure, this port is accessible. You may need to modify your firewall's rules.

Extract the CloudStore client archive on the workstation

Locally, on your workstation, you have to extract the client and move it to your home directory:

cd ~/Downloads
tar xzf co.codewizards.cloudstore.client-1.0.1-SNAPSHOT-bin.tar.gz
mv cloudstore ~/

Create a repository on the client

Let's assume you want to synchronise your existing ~/Documents folder with the repository myDocuments you just created on the server. You have to convert the existing directory into a CloudStore repository:

cd ~
~/cloudstore/bin/cloudstore createRepo Documents

Since the directory already exists, the -createDir option is not needed (it would not do any harm, though).

Note, that the repository-alias "Documents" is automatically created, this way. If you do not want this or you want another alias, you can add either "-noAlias" or "-alias <myAlias>".

Connect the repositories - step 1 of 2

The repositories do not know each other, yet. We have to connect them in order to be able to synchronise them. A connection is established in two steps: First, the client requests the connection:

~/cloudstore/bin/cloudstore requestRepoConnection Documents https://myserver.mydomain.tld:8443/myDocuments

Instead of the alias "myDocuments", you could use the repository's unique ID (so-called repositoryId), which was shown when you created the repository before.

The same applies to the local side: Instead of "Documents" you could specify the local repository's ID. Or alternatively, you could pass the local repository's file-system-path as well.

Here an alternative example (assuming that the repositoryId on your server is 2cb46e10-c076-466b-a944-2c1914076fe1):

~/cloudstore/bin/cloudstore requestRepoConnection /home/user/Documents https://myserver.mydomain.tld:8443/2cb46e10-c076-466b-a944-2c1914076fe1

Important: You are asked to verify the server's SSL certificate, because this is the first time that your client connects to this server. The server's certificate is verified by comparing the SHA1 fingerprint which is printed to the console whenever the server starts with the fingerprint displayed by the client.

If the fingerprint shown by the server does not exactly match the fingerprint shown by the client, someone is tampering with your connection and you must not continue!

You can read more about this on the Security page.

Connect the repositories - step 2 of 2

In the previous step, a connection was requested by the client and the server stored this request. Only after this request is accepted, access to the repository is granted.

You can accept this request via the following command, executed on the server-side (via SSH):

~/cloudstore/bin/cloudstore acceptRepoConnection myDocuments

Synchronise

All is set up. You can synchronise now. Execute the following command on the client-side:

~/cloudstore/bin/cloudstore sync Documents

This synchronises the local repository with the alias "Documents".

To synchronise all known local repositories, use "ALL" instead:

~/cloudstore/bin/cloudstore sync ALL