Setting up NarraFirma

 


NarraFirma is a web application. Because it is a web application, it has two parts:

  1. Server software that stores data and handles requests (like “send me the story that matches this identifier”). To use NarraFirma, you must install its server software on a computer.
  2. Client software that provides an interface where users can do things (like type in stories). The client portion of NarraFirma works in a web browser (such as Chrome, Safari, FireFox, Opera, Edge, or Explorer). It lives in the Javascript code that is embedded in the HTML pages your browser requests and receives from the internet. (You can see this Javascript code using your browser’s development tools.)

You can install the server portion of NarraFirma locally (on your own computer) or on an internet-connected computer (usually at an internet service provider).

  • If you install your NarraFirma server locally, nobody else will be able to access it. You can share your screen as you use NarraFirma, but no one else will be able to type things into NarraFirma’s pages or tell stories using a NarraFirma survey. This may be exactly what you want if you are doing a small or testing project. Plus, it’s very easy to set up.

(Actually, you can install a NarraFirma server on your local computer and make it available to the internet. But it’s complicated and risky, so most people choose to pay for a hosted service instead.)

  • If you install your NarraFirma server on an internet-connected computer (usually on a hosted service), other people will be able to interact with NarraFirma using their own browsers. You will create accounts for each of your collaborators, and they will enter their user ids and passwords to connect to the server. Anonymous visitors who take your web-based surveys will also connect to your NarraFirma server (the survey part only) using their browsers.

The NarraFirma server software depends on, and requires, either WordPress or Node.js.

Choosing a Platform   (top)

Why install NarraFirma with WordPress?

  • It’s easy. A few clicks and you’re done. The same goes for upgrades. (You can even set up automatic upgrades.)
  • You plan to run small projects, so you don’t care that much about speed. (NarraFirma runs more slowly on WordPress.)
  • You aren’t big on technical wizardry, and you need a simple option. (That’s fine! That’s why we made NarraFirma run on WordPress, because we know that not everybody wants to tinker with the software they use.)
  • You already have a WordPress site, so it’s easy to throw another plugin into the mix. (Makes sense.)

Why install NarraFirma with Node.js?

  • You want to set up big, ambitious projects, and you want NarraFirma to run fast. (It runs faster on Node.js.)
  • You don’t like WordPress. You think it’s buggy and insecure.
  • You have plenty of technical knowledge, and you like following cryptic command-line instructions. (Or you have help from somebody else who does.)
  • You don’t just want to use NarraFirma; you want to look inside it. Maybe you want to find out how it works. Maybe you want to make some local changes, say to its CSS styles, so it looks the way you want it to look. You might even want to contribute a bug fix or two at some point. (That’s fine! That’s why we made NarraFirma run on Node.js, because we also like to tinker with the software we use, when we can.)

Whichever option you like best, here is how you can do it. (For Node.js, scroll down the page.)

Installing NarraFirma with WordPress   (top)

How to Install WordPress on Your Local Computer

The easiest way to install WordPress locally is to use a Bitnami WordPress stack. Bitnami provides “application stacks” to quickly and easily install WordPress on Windows, Linux, or the Mac.

Another option is to install MAMP, the “one-click-solution for setting up your personal webserver.” After you have installed MAMP, install WordPress on top of it.

You can also install VirtualBox, then create a Linux image, and/or install MySQL, PHP, Apache and WordPress under a Linux virtual machine. There are many well-written tutorials for installing WordPress under Linux. You can also get pre-configured Virtual Box images for WordPress.

You can also install MySQL, PHP, Apache and WordPress from scratch. If you have not done this before, we suggest getting some help. You will need to go through 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). Once that is all set up, you can unzip WordPress (in the right place and with the right file permissions) and configure it to use a MySQL database (which you create for the WordPress install). Then you are ready to install the NarraFirma plugin.

How to Install WordPress on an Internet Hosting Service

If you want to have someone else set up and manage WordPress for you, search the internet for “one-click WordPress site hosting.” You will find many services that provide managed WordPress hosting for a small monthly fee.

If you want to install and maintain WordPress yourself, search the internet for “self-managed web hosting.” Then look for tutorials on “how to set up a WordPress site on a self-managed web server.”

For security, we strongly suggest using WordPress with a SSL certificate.

How to Install NarraFirma on top of WordPress

Once you have installed WordPress (locally or on a web server), you can simply find NarraFirma in the WordPress plugin directory and follow the directions there to install it.

However, if you want to manually install the NarraFirma plugin, download the plugin zip file from the NarraFirma GitHub releases page. The file will have a name like narrafirma-wordpress-plugin-vX.X.X.zip (where the Xs are numbers). Don’t download the entire source code file (narrafirma.zip). Then go to your WordPress site (in your browser). Choose the Plugins tab on the Dashboard menu. Click Add New, then Upload Plugin. Choose the zip file you downloaded. Click Install. Then click Activate Plugin.

After you have installed the NarraFirma plugin, you should see a new NarraFirma menu item in the Dashboard menu. It should look like this:

Click on the word NarraFirma. Now you should see the NarraFirma options page, which should look something like this. (The version number might be different.)

NFWPOptionsPage

Click Create New Project. Specify which WordPress users and/or roles should have read and/or write permissions for the project. Then click Save changes to save the new project.

Now click Start NarraFirma. The application will open in a new browser tab. Choose the project you just created. You should see the NarraFirma home page. It looks like this. There are buttons for each phase of participatory narrative inquiry: Planning, Collection, and so on.

NFhomepage

Click Planning to start working on your new project.

How to Upgrade your NarraFirma WordPress Plugin

Simply click the Upgrade link in your Plugins list.

Installing NarraFirma with Node.js   (top)

How to Install Node.js on Your Local Computer

Installing Node.js locally may be easier than installing WordPress, because you don’t have to install MySQL or configure Apache. To do this, download and install Node.js, then follow the instructions below for installing and setting up NarraFirma using Node.js.

How to Install Node.js on an Internet Hosting Service

Use a secure shell terminal session or an ssh client program to access your hosted web server. Upload and install Node.js on your server, then follow the instructions below for installing and setting up NarraFirma using Node.js.

How to Install NarraFirma on top of Node.js

To install NarraFirma with an existing Node.js installation,

1. Download the latest NarraFirma source file (narrafirma.zip – not the WordPress plugin) from the NarraFirma GitHub releases page.

2. Unzip the narrafirma.zip 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 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 each time you make changes to the TypeScript files, including after a git pull.

4. Set the superuser password using NarraFirma’s command-line tool (admin.js). On a command line, type node admin.js. Within that command-line tool, use the update-superuser command.

Another option is to download and use this Docker file (our thanks to Melissa Anderson for creating and posting it). Remember to update the NarraFirma version number in the Docker file to the most recently released version number. You can find the version number on the NarraFirma blog or on the GitHub releases page.

After you have installed NarraFirma, start the NarraFirma server. Go to the server directory, find the file readme_server.txt, and read the directions there to start the server. Then connect to the server (at localhost:8080) using your web browser.

Next, log in to NarraFirma as superuser and create a project using the NarraFirma site administration tool. Create other users (including a non-admin user id for yourself) and give them permissions in your project. After that, you can log out as superuser and log back in as a different user (to whom you gave permission for the project).

Choose the project you created. The NarraFirma home page should open. It looks like this. There are buttons for each phase of participatory narrative inquiry: Planning, Collection, and so on.

NFhomepage

Note that NarraFirma looks the same under Node.js and WordPress (and yes, this is the same screen shot as the one above). There are some differences in the project configuration interface under Node.js (which runs as a separate application) but otherwise the two versions of NarraFirma are identical.

How to Upgrade your NarraFirma Node.js Application

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.

Any questions?

If you are having problems installing or setting up NarraFirma, you can create a new issue on the NarraFirma GitHub issues page, or you can send an email to cfkurtz@cfkurtz.com. We are happy to help.