- 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)
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.
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;
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 »';
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:
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.
There ya go. You’ve successfully downloaded, installed, and customized the Uke Geeks Songbook application!