Open Source

Tutorial: Put your bookmarks online with SemanticScuttle

Marco Fioretti shows you a feature-rich open source program that allows you to store and organize online bookmarks.

Online bookmarks are wonderful: they are immediately available no matter which computer you are using, and you can share them with your friends. Delicious and similar third party services, however, aren't enough for me. Cloud computing is wonderful... as long as it's in your cloud. I want something that I can host wherever I want, without fears that someday the provider may abuse my data, adopt unacceptable terms of service or simply go out of business.

The Open Source Software most similar to Delicious is Scuttle, but it hasn't seen a release in one year and lacks both the semantic capabilities of SemanticScuttle and the full-text bookmark indexing Bookie. Therefore, here is the first of a two-part tutorial on SemanticScuttle (but I also plan to try Bookie later on!). This post describes in all details how to install and start using this tool. Next week, I'll cover advanced configuration and use.

Why SemanticScuttle?

SemanticScuttle runs on any Web server where a database and PHP5 with filter functions are available. It can use as backend any of MySQL, Firebird, MS SQL, SQLite, Oracle and PostGreSQL. The version covered here is 0.98.3, released in August 2011. You can see what it looks like in the online demo.

Figure A

Click to enlarge.

The features that I like are:

  • nested tags ("science>biology") and tags synonyms ("courage=bravery")
  • bookmarks can be public, private or only visible to members of a watchlist
  • bookmark descriptions support markup for attributes like author, address or ISBN
  • in addition to its public description, each bookmark can have a private note, only visible to you and your contacts
  • you can import bookmarks from Del.icio.us or from your browser backups, and export them in HTML, XML file (for Del.icio.us) or CSV format
  • more cool stuff I'll cover next week

Installation

The first thing to do to install SemanticScuttle is to download the software and unzip it into a folder accessible to your Web server. Then you'll have to:

  • create and configure a database (we'll go with MySQL here)
  • modify as needed the PHP configuration file
  • (if necessary) point the Web server to the SemanticScuttle folder
  • log in to configure your account and your browser

Now I'll show you step by step how to proceed, including a few necessary details not really documented elsewhere.

Creation of the MySQL database

In order to create a MySQL user and database reserved for SemanticScuttle, type at the MySQL administrator prompt the following commands (or perform the equivalent actions in any other MySQL interface):

  mysql> CREATE USER 'scuttle_usr'@'localhost' IDENTIFIED BY 'the_password';
  mysql> CREATE DATABASE scuttle;
  mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON scuttle.* TO 'scuttle_usr'@'localhost' IDENTIFIED BY 'the_password';
  mysql> FLUSH PRIVILEGES;
  mysql> EXIT

Once the database is ready, you must fill it with the tables that SemanticScuttle needs to work. At a command prompt, type:

mysql -uscuttle_usr -p scuttle < DIR/data/tables.sql

Replace DIR with the base directory in which you have installed SemanticScuttle. On my server, DIR would be /var/www/html/SemanticScuttle-0.98.3.

Modify the PHP configuration file

The SemanticScuttle distribution provides two templates in the "data" subfolder, called config.default.php and config.php.dist. The first one is a sort of reference guide, with sample values for many variables. The second one contains only the variables that most people will need: copy it to config.php, in the same folder, then open it with any text editor and set at least these variables to proper values for your server:

  $dbtype = 'mysql'
  $dbuser = 'scuttle_usr'
  $dbpass = 'the_password34no'
  $dbname = 'scuttle'
  $dbhost = 'localhost'
  $root = "http://myserver.com/bookmarks/"``
  $adminemail = 'me@myserver.com'

The first five variables define which kind of database is available and the credentials to access it. Beware of $dbhost! Its SemanticScuttle default value for a local database is '127.0.0.1'. While technically correct, on my server (SemanticScuttle 0.98.3, MySQL server 5.1.52, PHP 5.3.2) this generated a "lost MySQL connection" error until I set $dbhost to 'localhost' as suggested here.

The default value of $root is null. This makes SemanticScuttle autodetect where it was installed and prepend that location to all its internal URLs, both in HTTP and HTTPS mode. You must, instead, replace null with the complete URL of the initial page (with a trailing slash!) if that includes a subfolder as in the example above.

If you cannot use a whole database only for this service, you must also set $tableprefix to the prefix that identifies your SemanticScuttle tables! I'll discuss other variables next week.

Reconfigure the web server

If you want SemanticScuttle to have its own subdomain, you must set up DNS accordingly (ask how to do it to your hosting provider) and tell your web server which local folder corresponds to that URL. In Apache, this would mean defining a virtual host with these settings (see above what DIR means):

  DocumentRoot DIR/www
  ServerName mybookmarks.myserver.com

Once that is done, restart the web server, go to your brand new SemanticScuttle home page, register and...

Configure your SemanticScuttle account

To begin using SemanticScuttle, click on Profile to set up your profile. Then go to Add A Bookmark and import your existing bookmarks. Both tasks are quite simple. The only problem with the import function, which otherwise works well, is that it won't accept bookmark files over 1MB. To handle future bookmarks, add to your browser the pop-up bookmarklet as explained in the "Add a Bookmark" page. Ignore the other bookmarklet, that annoyingly replaces the page you're viewing with the SemanticScuttle form. This is enough to get you started with this great tool: next week, I'll show you how to proceed from there.

A word about warnings

During the initial configuration, I got a couple of warnings because the current version of SemanticScuttle uses the strtotime() and eregi_replace() PHP functions. This didn't create any real problems, and I've already informed the developers, so it may be fixed soon.

About

Marco Fioretti is a freelance writer and teacher whose work focuses on the impact of open digital technologies on education, ethics, civil rights, and environmental issues.

2 comments
mfioretti
mfioretti

let me know at mfioretti @ nexaima.net, and I'll mention it with a link in part 2 of the tutorial! Marco

Editor's Picks