Sandboxes
From Koha Wiki
Contents |
Sandboxes
The sandbox system has been developed with the goal to lower the barrier for librarian to test patches and improvements of Koha.
It's based on a simple mechanism that will let anyone ask for a Koha setup, with an uptodate Koha, a given patch applied and a sample database.
BibLibre provides 10 servers with Koha setup. The code of this sub-project will be released under GPL, with documentation, to have anyone being able to setup sandboxes.
The mechanism
Step 1
The 1st step is to define the parameters for the sandbox. Head to the sandbox creation page page (see "Available sandoxes" below for full URLs)
You'll see a welcome header (Welcome to the Koha sandbox tester) and, just below informations about the existing setup for the sandbox. For example: The current setup on this sandbox is = Sandbox setup by unknown with database -1 and bug 7376 on Wed Feb 1 10:46:16 2012 If the setup is a few minuts old, it's probably wise to use another sandbox, to avoid a conflict with another tester. Otherwise, you can continue with this sandbox.
You will have to fill some informations:
- bugzilla number: the bug you want to test
- your email address: this field is not mandatory, but you're highly encouraged to provide it, for 2 reasons: you'll be emailed once the sandbox is ready. Depending on your configuration, this can require a few minuts. Information about the creation of this sandbox will be available to anyone connecting. So, if you're working on a given sandbox, someone else will see it, and could catch you on IRC or drop you a mail. This is the only mechanism that will avoid 2 users using the same sandbox at the same time !
- a translation you would like to install. By default, you'll get fr-FR, you can choose another one, or remove anything, you'll have only english available
- the database you want to setup. There are some options that are described below
- The anti-spam: this is a fairly basic anti-spam entry. Just enter Koha in this input, and hitting <OK> will work. Otherwise, <OK> will do nothing. This is to prevend form-bot-autosubmitter to break the server.
When you submit the form, a small file will be written on the server, requesting the setup to be made. Every minut, a script check if there is something to do. If there is a sandbox to setup, the script will install the requested configuration, and send you an email once it's done.
Step 2
If you have provided an email, look at your mailbox. You'll receive a mail when the sandbox is ready to be used. Depending on the database you've requested, the mail will arrive more (less than one minute) or less (up to 5 minutes) quickly. If you haven't provided an email (bad idea), just wait a moment and go to step 3.
Step 3
You can now log-in to Koha staff interface. Depending on the database you've choosen, the login/password will differ.
When you log-in, you'll see, on the left, the result of your request.
- If something went wrong with automatically applying the patch, it will be written. In this case, forget the sandboxes to test it: just head to bugzilla, and enter a comment to say "i tried to test this patch with sandbox system, it does not work, here is the result <paste what's written>"
- If everything went well, you can test the patch, and, if you validate the patch, then add a message on bugzilla and change the status to "signed-off". (note that you can't upload a signed-off patch automatically for instance. This feature could be added soon, but it does not exist yet)
Step 4
Once you've tested a patch and want to test another one... just go to step 1 again, and repeat.
Databases
All the important dates in Koha are moved to "today" when you install a sandbox. For example, a check-out that is late since "yesterday" will still be due for "yesterday" if you choose the database again next week. If you want to add another database for tests, just drop me a mail (Paul Poulain, current RM, paul.poulain at biblibre.com) with the database, i'll add it quickly.
no change (-1)
This is the fastest option. If you're testing patches one after the other, you probably can choose this option (except for the first loop, of course). It won't update the database. So a biblio you've just entered, or a debarred patron, will be kept as you've set. If you choose this option, you won't do a zebra reindexing, that can be quite long for some sample databases
no database (run webinstaller) (0)
as described, you won't get any database. This is probably an option you'll use rarely, but it can sometimes be useful. And for testing installer, this is a must-have !
marc21 tiny dataset (1)
default config, login with test/test, superlibrarian, 1 biblio with 10 items (barcode 1 to 10)
UNIMARC public library (2)
Public library with 19k biblio, a lot of members, circulation history, holds. Acquisition not used in real situation, so only sample datas (log-in with test/test)
Note that when you setup this database, your mail will contain 3 errors that you can ignore:
DBD::mysql::db do failed: Table 'pending_offline_operations' already exists at installer/data/mysql/updatedatabase.pl line 4723. DBD::mysql::db do failed: Unknown table 'bibliocoverimage' at installer/data/mysql/updatedatabase.pl line 4897. DBD::mysql::db do failed: Table 'biblioimages' already exists at installer/data/mysql/updatedatabase.pl line 4898.
Tips and tricks
testing with "master"
"master" is the technical name for the uptodate version of Koha (not the last release, but what will be released on the next release. Most bugs you'll have to test will say something like: "this feature is not working in master before applying this patch, it's working well after applying the patch". You may/will want to compare the differences. The sandbox system can help you: just ask for "master" instead of entering a bugzilla number.
A workflow could be:
- go to sandbox.pl page, and ask for "master", with database you want
- log-in when you've received the mail, and test the behaviour is wrong
- go to sandbox.pl page, ask for NNNN (the bug you want to test), with database= -1 (no change)
- log-in again when you've received the mail, and test the behaviour is now correct
Hint: you can even use 2 sandboxes in parallel, one running master, one running the bug you want to test. each on his own Firefox tab. It's very handy and efficient
Available Sandboxes
BibLibre
BibLibre provide 10 sandboxes:
IMPORTANT WARNING
sandboxes 1 to 4 have a UNIMARC configuration for zebra. sandboxes 5 to 10 have a MARC21 configuration for zebra.
So, if you want to test a patch where you'll need zebra, choose wisely ! if you ask a MARC21 database on a UNIMARC zebra, everything will be OK, except zebra, that won't give you any result.
