At the Scholars’ Lab, we’re big big advocates of Open Source. All of our projects are available freely and openly on Github, and we’re always more than happy to accept pull requests. We’d like to be able to empower everyone to contribute to our projects as much as they’re able to and comfortable with.
Unfortunately, one of our flagship projects, Neatline, isn’t easy to contribute to. There are a number of reasons for this, but one is that the development environment is not trivial to get set up. In order to address this and make it easier for others to contribute, we’ve developed an Ansible playbook that takes a not-quite-stock Mac and sets up an instance of Omeka with the Neatline plugin available, as well as all the tools necessary for working on Neatline.
Ansible is a system for setting up and configuring systems. It’s often used to set up multiple servers—for instance, a database server and a static web server, both working with a dynamic web applications deployed on several computers. If you’re familiar with Chef or Puppet, Ansible solves the same problems. In this case, we’ll use it to configure our local development workstation.
We’ve published these playbooks on Github in the
neatline.dev repository, on the
mac-ansible branch. You can get this by cloning it to your local machine. (Since this is for getting started developing Neatline, I assume that you’re already comfortable with git. If not, there are lots of great tutorials.)
$ git clone --branch mac-ansible https://github.com/erochest/neatline.dev.git
In creating this, I’ve aimed for starting from a stock Mac. And I missed pretty badly. However, the necessary prerequisites are minimal. You’ll just need to have these things installed.
Once those two are on your machine, you can install the other two dependencies. These are available through Homebrew. So open Terminal and type these lines:
$ brew install python $ brew install ansible
That’s all. You should be ready to go.
This project includes a number settings that you can change to customize your installation. Those are found in the file
playbook.yaml. The relevant section is labelled
vars, and it allows you to set information about the Omeka database (
omeka_db_name), which version of Omeka you wish to use (
omeka_version), where you wish to install it (
omeka_dir), and where you want to point your browser to (
dev_hostname) as you’re working on the site. The defaults are:
vars: db_user: root db_password: omeka_db_user: omeka omeka_db_password: omeka omeka_db_name: omeka dev_hostname: omeka-neatline.dev omeka_dir: "/omeka/neatlinedev" omeka_version: stable-2.1 debug: true neatline_repo: firstname.lastname@example.org:scholarslab/Neatline.git php_version: 55
Change these to reflect what you’d like your personal Omeka/Neatline installation to look like.
One option that I’ll call out in particular is
neatline_repo. This is the git repository that you’ll be working with. If you’re using github to host your project, you can fork the primary Neatline repository (from the URL given above). And when you’ve completed your work, if you’d like to contribute back, you can send us a pull request through the Github site.
Finally, we’re ready to actually create the system. This is quite easy. In the Terminal, from the
neatline.dev directory, run the
$ cd neatline.dev $ ./neatline-dev
After your computer whirs away for a while, you’ll get your prompt back. When that happens, you should be able to point your browser to http://omeka-neatline.dev (in the example above). There you’ll see the Omeka installation form.
What Just Happened?
The Ansible playbook does a number of tasks.
It sets MySQL to start automatically when you log in, and it creates the Omeka MySQL user and database.
It configures Apache to work with PHP and to find your Omeka directory.
It downloads and configures Omeka and turns on debugging.
It clones Neatline into Omeka’s
It initializes git flow for working in Neatline and leaves you on the
After all that, it really needs a break.
You probably do too.
Unfortunately, that’s only the first step that we need to take to make the Neatline code-base approachable. Some more things that we have planned include:
Documentation on all the moving parts.
Documentation on the overall architecture of Neatline.
Documentation on the code. What’s where? If you wish to change something, where would you find it?
As we get those parts in place, we’ll keep you posted.