Setting up NarraFirma on your local computer

Installing with WordPress

To run NarraFirma using an existing WordPress installation:

  1. Download the NarraFirma plugin zip file from the NarraFirma GitHub releases page. The file will have a name like (though it might be slightly different). Don’t download the entire source code file (
  2. Go to your WordPress site (in your browser). Choose the Plugins tab on the Dashboard menu (on the left). Click Add New, then Upload Plugin. Choose the zip file you downloaded. Click Install. Then click Activate Plugin.
  3. Click on the new NarraFirma menu item in the Dashboard menu. Create a project in the NarraFirma plugin screen, and specify which WordPress users should have read and/or write permissions for the project. (Remember to click Save changes after you create the new project.)

Or you can install NarraFirma from the WordPress plugin directory. Just follow the directions there (then do step three above).

Installing with Node.js

To run NarraFirma with an existing Node.js installation:

  1. Download the entire NarraFirma source file ( from the NarraFirma GitHub releases page.
  2. Unzip the file
  3. Compile the TypeScript files. To do this, run tsc from the command line in the top level project directory. That will use the tsconfig.json to compile the “*.ts” files. You will need to rerun “tsc” after any changes to the TypeScript files (including after a git pull). The “tsc” TypeScript compiler can be installed using: “npm install -g typescript”.
  4. Go to the server directory in the unzipped files, and read the directions in the file readme_server.txt about how to start the server.
  5. Before you start the NarraFirma server for the first time, you will need to set the superuser password using a command-line tool. On a command line, type node admin.js. Within that command-line tool, use the update-superuser command.
  6. After you have set up the superuser password, start the NarraFirma server (using the directions in readme_server.txt), and connect to it using your web browser.
  7. Login to NarraFirma as superuser and create your first project using the NarraFirma administration tool. You can create other users and give them permissions in your project.
  8. After that, you can log out as superuser, log back in as a different user (whom you gave permission for the project), and start using NarraFirma.


Options for getting to the point of having WordPress or Node.js running locally

Below are several options for getting a sandbox running locally or on the web for trying out NarraFirma on your own. The first one (MAMP) may be the easiest if it works as expected, but the VirtualBox approach is the most sure, as far as being able to easily start again when things go wrong (but it is a bit more of a learning curve and probably requires more disk space).

The easiest option is to get a throwaway “one click WordPress” installer webhost somewhere like Dreamhost or Digital Ocean — but this option is not local to your machine, and it may require more abstract system administration knowledge to set up.

WordPress can be tricky to get going on a local machine running Mac or Windows because you will probably need to install MySQL. The two easiest options to do this quicky are with Bitnami or MAMP.

Installing WordPress using Bitnami

Bitnami provides “application stacks” to install WordPress on Windows, Linux, or the Mac. From the Bitnami site:

Bitnami native installers automate the setup of a Bitnami application stack on Windows, OS X or Linux. Each installer includes all of the software necessary to run out of the box (the stack). The process is simple; just download, click next-next-next and you are done! Bitnami stacks are completely self contained and will not interfere with other software on your system.

Installing WordPress using MAMP

This is another relatively easy option. You can install MAMP, the “one-click-solution for setting up your personal webserver,” then install WordPress on top of MAMP.

Installing WordPress by hand

If you want to install MySQL etc. on a PC or Mac from scratch (without MAMP), and you have not done this before, we suggest getting a local technology person to help you through the process of setting up MySQL on your Mac or PC. The process requires several steps of configuration, including setting passwords and setting up automatic starting on reboot. You also have to ensure that Apache is configured correctly if it is already installed (it may be already, but you may have to enable PHP at a minimum). Then you need to unzip WordPress in the right place and with the right file permissions, and configure it to use a MySQL database you create for the WordPress install. Then you are ready to install NarraFirma.

This option is not that hard if you do it systematically, but the issue is always (like driving around in a new city without a GPS) that if you accidentally take a wrong turn it can be hard to figure out where you are and what went wrong and how to get back to where you want to go before you end up unintentionally on some freeway out of town. :-) As an example, here is a related link on setting up WordPress for the Mac under Lion.

Installing WordPress in VirtualBox

Another option for local installation is to first install VirtualBox, then create a Linux image, and/or install MySQL, PHP, Apache and WordPress under a Linux virtual machine. While that may sound like more work, it can actually be easier and safer because everything is kept neatly compartmentalized in a separate VirtualBox disk image file.

There are many well-written tutorials for installing WordPress under Linux (where it usually runs for most people hosting it on web hosts). You can also get pre-configured Virtual Box images for WordPress which make things much easier. VirtualBox has a small learning curve, especially for configuring network access (where setting the right network options is probably the hardest part).

Installing Node.js

Another option for local testing of NarraFirma is to install Node.js. This may be easier than installing WordPress, because you don’t have to install MySQL or configure Apache. To do this, install Node.js. (Here are some good instructions for installing Node.js on a Mac.) Then follow the instructions above for installing and setting up NarraFirma with Node.js.

The interface for the NarraFirma application under Node.js is identical to the one under WordPress, but there are differences for the project configuration interface, which runs as a separate application.

Cheap web hosting

This is not exactly “local” hosting on a personal computer, but another option is getting a cheap throwaway web hosting account somewhere such as at Digital Ocean for $10 or so a month (a bargain for timesaving in testing) — maybe even less if you rent by the hour and you just run an instance for a few hours. Here are links for one-click WordPress install and one-click NodeJS install.

You can also get a year of free low-end hosting at Amazon if you sign up for Amazon’s AWS system (but that has its own learning curve). Here are instructions on installing WordPress on AWS and also a pre-made AMI with WordPress.

However, for both Digital Ocean and AWS, to be really secure, you would have to install a self-signed certificate for Apache to protect your WordPress password, and that is another learning curve. Using ssh is probably not an issue if you are just playing around for a few hours and don’t intend to keep the system around.

Another option is DreamHost shared hosting or similar for general testing.

If you already have a web host and a WordPress blog, it’s possible that you could just set up a second WordPress installation there for playing around (something separate from your main site). You could ask your web host for tips on how to do that securely, or if they could set up a second account for you to play around with. However, we do not suggest logging in to WordPress without some form of SSL, because it is a security risk.