Installing the Songbook Application (Video Tutorial, Part 1)

Topics:

  • Verify Your Web Server & PHP Environment
  • Download & Install the Songbook Application
  • Enable Adding Songs
  • Troubleshooting MacOS Permissions
  • Enable “Pretty” URLs
  • Set Songbook Listing Page’s Title

(here’s the fairly accurate transcript)

Introduction

This is Buz, from Uke Geeks, today walking you through a typical Uke Geeks Songbook application installation.

Though what we’ll be doing today is of clear interest to folks hosting a public website it’s also equally applicable to enthusiasts who want a personal song library running locally on their computer. Now, the application runs under Windows or Macs — I use it on both myself, but if you have a Macbook there’s less pre-work involved because all Macs come with a web server pre-installed (I use the free Apache web server on all of my machines, MacOS and Windows).

I’ll post links to tutorials and any sites mentioned here in the show notes for this video at UkeGeeks.com.

Let’s begin…

Verifying Your Web Server’s Ready

First we want to verify that our web server is working properly. That is, the web server can serve pages, we know where its documents directory is located, and PHP is installed.

To confirm that a web server is working tradition dictates that we create the ubiquitous “Hello, World” HTML document and that it’s viewable it in our browser.

I’ve opened a file named “hello.html” and typed:

<h1>Hello, ukulele world!</h1>

Now in my browser I go to “localhost/hello.html” — and there she is!

That done, let’s verify our PHP installation. Create a file, I’ve named mine “info.php” — don’t forget that dot-PHP extension — and inside it we’ll place just one command: “phpinfo”:

<?php
phpinfo();
?>

Back in the browser I open “localhost/info.php” and I see all of my PHP installation’s settings.

Great! Our environment’s ready so let’s do the Songbook install!

Installing the Songbook Application

Download the UkeGeeks songbook code by going to the UkeGeeks.com website, scroll or click down to the Songbook section, and click that ribbon that says “Fork Me On GitHub“. GitHub is a massive site where coders publish and store versions of their programs. GitHub will always have the most up-to-date versions of the UkeGeeks programs. Find the “download ZIP” link here in the sidebar and download the complete zipped-project file to your computer.

Once downloaded unzip this file and move its contents into the directory where we had our “Hello, World” page.

Back in the browser let’s change “info.php” to “music.php” and load the page. If we’re seeing the listing of all songs in our library we’ve completed the basic install.

We’re essentially done — success! But let’s go ahead and change some of the program’s configurations to make it friendlier. Do this by editing the configuration file.

Customizing Your Installation

Note that the optional steps below only need to be performed one time, after that your installation is self-maintaining.

Optional: Enable Adding Songs

First, we want to be able to add songs from the application. Open config.php in any simple text editor — Notepad or TextEdit work fine. Since I jump between Macs and Windows I’m using Sublime Text because it runs on both and uses pretty colors.

Find this setting, “Is Login Required” and change it from its default value of “false” to “true“:

const IsLoginRequired = false;

Hit Save.

A bit further down in this file you’ll see a cluster of users. You may copy and paste blocks to add or remove users, changing the user names and what they are allowed to do here. For now let’s make note of the admin user (you’ll probably want to change this password later) and go back to the browser.

If we reload the songbook in our browser we get a login window. Enter the info for admin. Now we see this “hello” message and an “Add” button.

Let’s test this by adding a song — the title is required (I named mine “So Far West It’s Nearly East”). Click “Continue”.

At this point either something good just happened or something annoying. I’m getting something annoying — an error message complaining about directory permissions.

Mac/Unix Permissions Fix

Without going into too much detail Macs are, by default, a bit less trusting when it comes to hosting websites, so we’ll need to tell our operating system that it’s OK for the web server to change the contents of two directories: the first is where our ChordPro song documents live and the second is where the songbook listing “cache” is maintained.

Windows users, you probably don’t have this problem so sit back for moment while we open a terminal window and fix this.

By the way, all of this info, including the exact commands I’m typing, is covered in the “ReadMe” file included the zipped project file. (see below)

Press Command + spacebar and type terminal (don’t worry, I’m with you — I loathe typing frightening geek commands in little windows as much as you do; we’ll be quick).

$ sudo chgrp -R _www /httpdocs/ukegeeks/ugsphp/cache
$ sudo chmod -R u+r+w+x,g+r+w+x,o+r-w+x /httpdocs/ukegeeks/ugsphp/cache

$ sudo chgrp -R _www /httpdocs/ukegeeks/cpm
$ sudo chmod -R u+r+w+x,g+r+w+x,o+r-w+x /httpdocs/ukegeeks/cpm

$ sudo /usr/sbin/apachectl restart

I’ll not go into much detail here, again see the show notes for the exact commands — I’ve pre-entered these to save time — but what we’re telling the operating system is that the dub-dub-dub user group has our permission to access these directories. You’ll be required to provide the computer’s admin password because we’re modifying user permissions. After that I’m issuing the command to restart our Apache web server.

OK, back in the browser now when I click “Continue” I see that the song has been saved and we’re in the Song-a-matic editor. Terrific!

Continuing… Verify “Add” Song Works

We’re able to edit the song. Just to be sure I’ll type a bit and hit Save (note that you may “Update” a song without actually “Saving” it).

To see what’s happening behind the scenes let’s open the “cpm” folder of our installation directory — that CPM stands for “ChordPro Markup”, by the way. We see that our newly created song is there (it has a “.txt” file extension). All songs in your library live inside this folder — this is why the web server needs permission to change files inside this directory.

If you’re curious about the odditional gobblie-gook at the end of your new song’s name that’s how the application ensures that every song (file) name is unique; by appending some random stuff at the end.

Optional: Set Songbook List Page Titles

Back to the Songbook’s list page notice that stupid title… let’s address that issue by going back to the configuration file and changing the value for the “Songbook Headline” and “Songbook Subheadline” options:

const SongbookHeadline = 'Songs of Melancholy and Woe';
const SongbookSubHeadline = 'The Mighty Songbook &raquo;';

Be careful if you want to include an apostrophe in these values (see my notes). Save your edits and check the results back in your browser.

Optional: Pretty URLs

This next customization is only available to folks running Apache web server with the “mod_rewrite” option enabled. Note that if this isn’t enabled by default on your Apache installation don’t fret: enabling this server option is simple. I’ll not go into it here, it just involves editing your web server’s configuration file, httpd.conf, and telling it to allow mod rewrites:

LoadModule rewrite_module modules/mod_rewrite.so

You might have noticed that when, from the song listing page, we click on a song the URL in your browser’s location bar has “music.php” followed by “?” and the name of the ChordPro song file. This works fine, but is a bit too geeky for my liking. Let’s turn on a feature of the Apache web server called “mod rewrite”

In the songbook’s config file we just change “Use Mod Rewrite” to “true”. Save our edit.

const UseModRewrite = false;

We’ve now told the Songbook application to make its links using the pretty URL syntax, so our song links will be:

localhost/songbook/mySong

We’re not quite done as we now need to let the Apache web server know about our plans. We do this by renaming the .htaccess.txt file, we just need to remove the “dot txt” part of the file’s name and save it. This file contains rules used by the web server to understand our prefered way of writing URLs.

Finally, let’s force the Songbook application to reindex all of our songs, using the new “pretty” URLs we’ve just enabled. Back in the browser let’s try this url “localhost/reindex”… after a moment it’ll say it’s done. Now go back to our songbook (type “localhost/songbook”). Click a song and we see the URL is “cleaner”.

Optional: Tidy Installation Directory (for OCD types)

Finally, if you want to tidy-up your installation and you’re not interested in modifying the source code behind the scenes (and I can’t imagine many of you are) we can delete some unused directories & files. Locate and delete the “source”, “songs”, and “templates” folders, though there’s also no harm in leaving them where they are.

Goodbye!

There ya go. You’ve successfully downloaded, installed, and customized the Uke Geeks Songbook application!

Tags: ,

8 comments

  1. Buz, one thing to note if installing on Ubuntu 13.10 is that in addition to installing apache2 and php5, you need to install php5-json, as for some reason Ubuntu don’t include it in the php5 metapackage any more:

    http://askubuntu.com/questions/361424/what-happened-to-json-encode-in-13-10-php

    If you don’t have php5-json installed, then when you try to create a new song, Scriptasaurus will complain about permissions for the CPM directory which had me foxed for a few minutes. The clue to this one is seen in the apache2 error log /var/log/apache2/error.log like so:

    [Fri Apr 18 14:43:09.663094 2014] [:error] [pid 3781] [client 192.168.1.67:44826] PHP Fatal error: Call to undefined function json_decode() in /var/www/ukegeeks/ugsphp/Ugs.php on line 215, referer: http://macmini.lan/ukegeeks/music.php?action=Songbook

    hth

    • Thanks for working through the problem and resolving it! That’s quite annoying — hope it wasn’t too painful.

      It’s now (oh hindsight) readily apparent how that error message masks any number of possible problems; the most common ones had been either file writing or the automatic “reindex” (the step that preps that list of song titles, artists, etc appearing on Songbook’s “Song Listing” page) that’s triggered each time a song’s added. Never encountered backend handling of AJAX, where JSON encoding/decoding occurs (native on Macbook & WAMP on Windows).

      Thanks so much for sharing this remedy.

      I need to look into an dependency audit (wonder whether theirs a PHP equivalent to Dependency Walker for DLLs… hmmm)

  2. Thanks very much for providing the Songbook application.

    I’ve installed it but am there are a couple of problems I haven’t solved:

    1) Trying to set defaults for settings (Eg “Ignore Common Chords“). I’ve uncommented it in settings.json_example, but not sure what else needs to be done (renaming it to settings.json doesn’t seem to work).

    2) I’ve installed it in a subdirectory http://www.mywebsite.com/songbook/ and changed the “Subdirectory” and “StaticsPrefix” constants. That works fine but I’m unable to prettify the urls using mod_rewrite. Going to the URL http://www.mywebsite.com/songbook redirects properly to music.php, but when I click a link to a song it gives (eg “www.mywebsite.com/songbook/songbook/jingle-bells”) an error Page not found. Is it something to do with RewriteBase in htaccess?

    • Hey, Daniel, I’m hoping the first issue is just a failure on my part to update documentation. It seems that you’ve already solved the hard part — finding your settings, but instead of uncommenting the sections of that example file, make of copy of it — “ugsphp/settings.json_example” — and name it “settings.json” (removing the “_example” suffix).

      (I’ll update that readme and the file to explain this — I completely forgot, sorry)

      I’ll check into the modwrite and subdirectories — think I know the issue, but need to test a solution. Thanks for sharing your issues, sorry for the oversight.

      • Daniel Carter

        Thanks. I’ve copied “settings.json_example” to “settings.json” in the same folder and changed some of the defaults, but when I view songs in the browser the settings are still unchanged.

        I’ve been looking through the source but can’t see where the problem is. Nice clean coding by the way.

        • Thanks, though I wish you’d not needed to peek 😀

          I’ve emailed you some steps we can follow to debug this — determine whether it’s a PHP, JavaScript, or JSON formatting problem — and then we can post our findings (and fixes). Thanks much for your patience.

  3. One trap I stumbled into: JSON is very strict when it comes to format of the options array.
    Make sure you don’t have a trailing comma after the last option you enabled. The options array MUST be in the format
    {
    option1,
    option2,
    lastoption
    }

  4. I was really thrilled finding the possibility to override the default settings with the settings.json – finally the scriptosaurus can be adopted to my needs within seconds…

    But as usual, every granted wish creates new ones ;-):
    (1) Would it be possible to somehow split the “login required” in two:
    a. (admin) login required for editing
    b. (guest) login required for viewing
    I’d like to make my songbook public and restrict just the editing/adding to a few named users (I am fully aware that I could simply publish the guest login credentials, but that’s rather a workaround than a solution)

    (2) Would you mind deleting all references of “soprano” when mentioning GCEA tuning? I know at least three ukulele sizes using this tuning: soprano, concert and tenor – only baritones are usually in DGBE (guitar) tuning.
    Might be worth spending a minute on including an option for ADF#B tuning as well (e.g. something like “transpose_steps” : 2 in settings.json should do)

Leave a Reply

Your email address will not be published. Required fields are marked *