Setting up NarraFirma

NarraFirma is a web application that requires either WordPress or Node.js to run.

Installing NarraFirma as a WordPress Plugin

The easiest way to install NarraFirma with WordPress is to find it in the WordPress plugin directory and follow the directions there.

If you want to manually install the plugin:

  1. Download the NarraFirma plugin zip file from the NarraFirma GitHub releases page. The file will have a name like (where the Xs are numbers). 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.

After you have installed the plugin, 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.)

Installing NarraFirma 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 “npm run build” from the command line in the directory where you unzipped the NarraFirma files. This will use the tsconfig.json to compile the “*.ts” files. (If you get an error like “npm not found” you need to install Node.js or npm. If you get an error like “tsc not recognized” you need to install typescript using the commmand “npm install typescript -g”.) You will need to rerun “npm run build” after any changes to the TypeScript files (including after a git pull).
  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.

Upgrading an existing NarraFirma installation

If you are using the WordPress version of NarraFirma, click the Upgrade link in your Plugins list.

If you are using the node.js version of NarraFirma with source code you checked out from GitHub:

  1. Shut down your NarraFirma server process.
  2. Use the git checkout command (git checkout vX.X.X, where X.X.X is the release number you want) to pull down the latest tagged release (which you can find on the NarraFirma GitHub site under the Releases tab). (Or just do a git pull to get the very latest code.)
  3. Run the “npm run build” command in the NarraFirma directory to compile the Typescript files.
  4. Restart your NarraFirma server.

If you are using the node.js version of NarraFirma from a downloaded zip file (i.e., you didn’t check out the source code from GitHub):

  1. Shut down your NarraFirma server process.
  2. Make a copy of your entire NarraFirma folder.
  3. Download the new zipped version of NarraFirma to a different folder. Unzip it.
  4. Copy the server-data folder from your old NarraFirma installation into the new version folder.
  5. Copy the file server/superuserinformation.json to the same folder in your new installation.
  6. Rename your old NarraFirma folder (to “NarraFirmaOld” or something). Rename your new NarraFirma folder to whatever you called it before.
  7. Restart your NarraFirma server.

Options for installing WordPress or Node.js

Below are several options for getting a sandbox running (locally or on the web) in which to install NarraFirma.

Using Bitnami to install WordPress locally

The easiest option is to install NarraFirma on top of a Bitnami WordPress stack. 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.

Using MAMP to install WordPress locally

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.

Using VirtualBox to install WordPress locally

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 WordPress locally by hand

If you want to install MySQL etc. on a PC or Mac from scratch (without Bitnami, MAMP, or VirtualBox), 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.

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. 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

Another option is to get a cheap throwaway web hosting account somewhere such as at Digital Ocean. 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.