-
Notifications
You must be signed in to change notification settings - Fork 6
Repository Setup
This can be confusing. We are not talking about the github repository for the source code of Bibledit-Desktop. Instead, we are talking about setting up a repository that contains your Bible translation. This repo is useful to track changes, share with others, etc. You can set up a repository in several different locations.
In this document we will set up a repository on a USB flash drive, also called a USB stick.
Normally a USB stick, as it comes out of the box, has been formatted with a FAT filesystem. Such a filesystem is not supported for collaboration. The stick needs to formatted to the ext3 filesystem for collaboration to work. How this is done will be described here.
Insert the stick into the computer, and wait a little till it gets mounted. It is supposed to mount automatically. If it does not mount on its own, then automatic mounting needs to be set up. Setting up automatic mounting goes beyond the scope of this tutorial.
In the terminal, give the command
df
The output of this command can be something like:
Filesystem 1K-blocks Used Available Use% Mounted on
/dev/sda1 93539428 76882380 11905428 87% /
tmpfs 1038428 0 1038428 0% /lib/init/rw
udev 10240 104 10136 2% /dev
tmpfs 1038428 0 1038428 0% /dev/shm
/dev/hda 629742 629742 0 100% /media/cdrom0
/dev/sdb5 306619956 189335920 101708620 66% /media/293gig
/dev/sdc1 240362656 64350876 163801980 29% /media/250gb
/dev/sdd1 1960684 660896 1200188 36% /media/usbdisk
Looking through the list of mounting points, we assume that the USB stick that was inserted mounts at /media/usbdisk. From there we can see that the device is /dev/sdd1. Once we have that information, we are ready for the next step.
Before the stick can be formatted, it must be unmounted first. Issue the following command to unmount the stick:
sudo umount /media/usbdisk
The "sudo" in the command means that root privileges are needed to execute the command.
To format the USB stick to the ext3 filesystem, issue the following command:
sudo mkfs.ext3 /dev/sdd1
The formatting process will be visible and at the end some information about it will be given. At this point it is important to see if no errors occurred.
The formatting command is very powerful. One could even format the main drive of the computer, wiping out all information. Extreme care should be used to ensure that the USB stick is going to be formatted, and nothing else.
A label needs to be written to the USB stick. The reason of this is so as to make sure that this stick will always mount at the same mounting point. In this tutorial we write the label "usbstick" to it.
We take it that the same device is being used as we used for formatting the stick. That is device /dev/sdd1. To write the label to the stick, issue the following two commands:
sudo e2label /dev/sdd1 usbstick
sync
After the label has been written to it, remove the stick from the computer, and insert it again. It should now mount to the name of the label. In this case it should mount under /media/usbstick.
This can be verified with command "df":
df
The output of this command:
Filesystem 1K-blocks Used Available Use% Mounted on
/dev/sda1 93539428 76882380 11905428 87% /
tmpfs 1038428 0 1038428 0% /lib/init/rw
udev 10240 104 10136 2% /dev
tmpfs 1038428 0 1038428 0% /dev/shm
/dev/hda 629742 629742 0 100% /media/cdrom0
/dev/sdb5 306619956 189335920 101708620 66% /media/293gig
/dev/sdc1 240362656 64350876 163801980 29% /media/250gb
/dev/sdd1 1960684 660896 1200188 36% /media/usbstick
This shows that it now mounts under the new name.
The USB stick will hold the data repository.
To make this stick fit for collaboration, there are a few steps to be taken. These steps are:
- The first step will be to create a directory for the repository, and to make that directory writable. If we assume that the stick mounts at /media/usbstick, then the command to create a directory called "repository" is:
sudo mkdir /media/usbstick/repository
Notice the "sudo" command, which means that this usually needs to be done by user root. If this is done by an ordinary user, permission would be denied.
Once the directory for the repository is there, this directory needs to be made writable for ordinary users. This is the command:
sudo chmod -R 0777 /media/usbstick/repository/
Note the "sudo" again.
Now it is time to check whether the USB stick is writable. We do this by trying to create a file in the repository. If this succeeds, then it is writable. Here's the command:
touch /media/usbstick/repository/testfile
This command should complete without errors. After that the file needs to be removed again:
rm /media/usbstick/repository/testfile
- The second step is to make the USB stick the current working directory. Type:
cd /media/usbstick/repository
- The next step is to create a repository on the USB stick, and to copy the data to it.
To create a shared repository on the USB stick, type:
git --bare init --shared
Git will respond saying that an empty shared Git repository has been created.
Before removing the stick, ensure that the data gets written to it, by issuing the command
sync
This finishes setting up the repository on the USB flash drive.
The repository that was created in this tutorial has the following URL:
file:///media/usbstick/repository
The users that are going to use this repository need this URL.
In this tutorial we are going to set up a secure network repository.
It uses a git repository on sourceforge.net.
Open an account on sourceforge.net. We will use the username "joe" in this tutorial.
Register a new project on your personal account page on sourceforge.net. Let's call this project "repo2".
Enable project feature "Git" on this project. This provides the repository.
The next thing is to try whether you can read the repository properly. To try that, open a terminal and issue the following command:
git ls-remote ssh://joe@repo2.git.sourceforge.net/gitroot/repo2/repo2
This command probably will ask for your password, and the first time it could ask you whether you want to continue connecting. But it should show no errors. If it completes without errors, then your secure repository works well.
The repository that was created in this tutorial has the following URL:
ssh://user@repo2.git.sourceforge.net/gitroot/repo2/repo2
The users that are going to use this repository need this URL. Where it says "user", each user would need to fill in his own username.
Each user will need to open his or her own account on sourceforge.net. After that, they need to open an e-mail from sourceforge.net and click the link to activate their account. Each user needs to be registered as a member of the project, in this example, project "repo2". This is so that the user can write to the repository.
So the moderator (or the person to first set up the repository) will need to log onto to his account at sourceforge.net,
-
click on “account� in the upper right, -
choose the projects tab, -
click on the project name, -
then click View all files. -
Now there will be a series of tabs at the top which expand if your mouse cursor hovers above them. Go to the last one, Project Admin, and click Members. -
Finally! From there you will be add any members who have activated their accounts by clicking in the e-mail that was sent to them. -
After this, each project member will be able to do the steps in Secure shell keys setup.
In this tutorial we are going to set up an open repository on the network.
To create the repository on we need a server. Any of your Linux computers that is attached to your network will do. In this tutorial we assume that the computer is accessible from the network through IP address 192.168.0.1. The user of this computer will be Jim.
To create the repository, login as user jim. Then open a terminal. The repository is going to be in Jim's home directory. In the terminal type the following:
cd
mkdir -p git/repository
cd git/repository
git --bare init --shared
The repository is now there, but it is not yet accessible from the network.
To make the repository available to the network, type
git daemon --export-all --base-path=/home/jim/git --detach --enable=receive-pack
Each time that the server boots, it is necessary to execute the above command again. It would be easier to put the command in the boot script. Then it will automatically be started after boot.
To test access to the new repository from another computer on the network, type
git ls-remote git://192.168.0.1/repository
If everything is fine, no errors will occur.
The repository that was created in this tutorial has the following URL:
git://192.168.0.1/repository
The users that are going to use this repository need this URL.
In this tutorial we are going to set up a secure network repository.
Doing this on github.com is easy. Create an account there, and then create a git repository. If your username is "joe", and your password is "pazz", and the repository is "repo", then accessing this repository through https works through this URL:https://joe:pazz@github.com/joe/repo.git
Another type of secure git repository can be created on sourceforge.net.
Open an account on sourceforge.net. We will use the username "joe" in this tutorial.
Register a new project on your personal account page on sourceforge.net. Let's call this project "repo2".
Enable project feature "Git" on this project. This provides the repository.
The next thing is to try whether you can read the repository properly. To try that, open a terminal and issue the following command:
git ls-remote ssh://joe@repo2.git.sourceforge.net/gitroot/repo2/repo2
This command probably will ask for your password, and the first time it could ask you whether you want to continue connecting. But it should show no errors. If it completes without errors, then your secure repository works well.
The repository that was created in this tutorial has the following URL:
ssh://user@repo2.git.sourceforge.net/gitroot/repo2/repo2
The users that are going to use this repository need this URL. Where it says "user", each user would need to fill in his own username.
Each user will need to open his or her own account on sourceforge.net. After that, they need to open an e-mail from sourceforge.net and click the link to activate their account. Each user needs to be registered as a member of the project, in this example, project "repo2". This is so that the user can write to the repository.
So the moderator (or the person to first set up the repository) will need to log onto to his account at sourceforge.net,
-
click on Account� in the upper right, -
choose the projects tab, -
click on the project name, -
then click View all files. -
Now there will be a series of tabs at the top which expand if your mouse cursor hovers above them. Go to the last one, Project Admin, and click Members. -
Finally! From there you will be add any members who have activated their accounts by clicking in the e-mail that was sent to them. -
After this, each project member will be able to do the steps in Secure shell keys setup.
When your remote repository is a secure one, and you'd like Bibledit to use it, then is is necessary to set up secure shell keys. These keys allow easy access to the secure repository. Please follow the tutorial exactly.
The first thing to do is to generate the keys.
On your Linux workstation, open a termial and enter the following:
cd (to make sure you are in your home directory)
ls .ssh (to check if there is an .ssh directory)
If there is no .ssh directory, create one:
mkdir .ssh
then
cd .ssh
ssh-keygen -t dsa -b 1024 -f bibledit-ssh-key
It will respond as follows:
Generating public/private dsa key pair.
Enter passphrase (empty for no passphrase):
At this stage press Enter. It will continue as follows:
Enter same passphrase again:
Press Enter again. It will continue as below:
Your identification has been saved in bibledit-ssh-key.
Your public key has been saved in bibledit-ssh-key.pub.
It will print some more lines of text. This is not relevant for our purpose.
This pair of keys is important. The pair is in the ".ssh" directory of your home directory. There is the private key, in a file called "bibledit-ssh-key", and the public key, in another file called "bibledit-ssh-key.pub". Store them safely.
Open a personal account at sourceforge.net. Let's choose user name "repouser". Ask the project administrator whether he can add user "repouser" to the "repo2" project as a member. Joining this project will give you the capability to write to the repository.
After logging onto sourceforge.net, click “account� in the upper right, and choose the Services tab, then choose “Edit SSH Keys for Shell/CVS.� (If the moderator of the project has not yet added you as a member, this page will not have a link to “Edit SSH...�) In the section above, you generated a file "bibledit-ssh-key.pub". Open it in gedit. Select all the text and copy it to the clipboard. In the screen titled "SSH Keys", there is a place where it says "Authorized keys:". Paste the text from gedit into that space on the web page. After checking that everything looks fine, press button "Update". Synchronizing the keys into the system has a 10 minute delay.
The next step is to tell the secure shell where to find the private key when we connect to sourceforge.net, and to set a few other important options. To do that, open file ~/.ssh/config in gedit. Enter the entry for sourceforge.net, like so:
Host *sourceforge.net
IdentityFile ~/.ssh/bibledit-ssh-key
BatchMode yes
StrictHostKeyChecking no
Save the file.
The above refers to a file called "bibledit-ssh-key". You have generated this key before.
If the delay of 10 minutes has expired, we can now try whether the key pair works well. In the terminal, try to access the repository at sourceforge:
git ls-remote ssh://repouser@repo2.git.sourceforge.net/gitroot/repo2/repo2
If it works then it will give no errors, and list a few commits. If it does that, then the keys works well. If it asks for a password, or if there are errors, follow the tutorial again to get everything right.
After reinstalling Bibledit on your computer and copying your backed-up .bibledit directory, be sure you have copied the back-up of your .ssh directory.
IMPORTANT: If after reinstalling Bibledit on your computer you have started Bibledit and edited your project since the remote repository was active, make an extra backup of the project now! When you reinitialize remote backup/sharing via Preferences > Remote Repository, the Clone the Remote Repository will erase all your recent edits!
Then reboot. Following reboot (or if you have already rebooted multiple times since reinstalling the above), test this:
git ls-remote ssh://repouser@repo2.git.sourceforge.net/gitroot/repo2/repo2
This should yield no errors but something like this:
8dc8c3e57a42654f5b4cbc938811c6f0b3c2a1ec HEAD
8dc8c3e57a42654f5b4cbc938811c6f0b3c2a1ec refs/heads/master
If you get something like that (no errors), then you ready to reinitialize remote backup/sharing via Preferences > Remote Repository. Second screen, choose the top option, Bible Repository. Choose all the defaults. You will be forced to clone the remote repository. (Did you make the backup above?!) Once that process completes, you will be sharing via the repository again. You can always check that changes are being written by logging into your sourceforge account, and check out the What's Happening page (visible when you click on your name at the upper right). If you got an error message, follow the steps below.
In order to reconfigure Bibledit after changing computers or reinstalling an operating system, you might not be able to just copy and reuse a backup copy of your original .ssh directory and the config file. Also, it seems that just remaking the shell keys in the old .ssh directory will not work. Make a new .ssh directory and follow the steps above to create secure shell keys. You can copy and reuse the backed-up config file. Then replace your old ...key.pub at sourceforge.net/Services with your new key, then click to Update. During the 10 minute wait, reboot your computer. After rebooting and waiting for the key to be updated, test if you get an error message with
git ls-remote ssh://repouser@repo2.git.sourceforge.net/gitroot/repo2/repo2
If not, everything is ready. Follow the steps under the menu Preferences > Remote Repository. Second screen, choose the top option, Bible Repository. Choose all the defaults. You will be forced to clone the remote repository. (Did you make the backup above?!) Once that process completes, you will be sharing via the repository again. You can always check that changes are being written by logging into your sourceforge account, and check out the What's Happening page (visible when you click on your name at the upper right).
Visit the web page for Bibledit-Desktop at bibleditdesktop.org