Special Note: 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:
- Shut down your NarraFirma server process.
- 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.)
- Run the “npm run build” command in the NarraFirma directory to compile the Typescript files.
- 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):
- Shut down your NarraFirma server process.
- Make a copy of your entire NarraFirma folder.
- Download the new zipped version of NarraFirma to a different folder. Unzip it.
- Copy the server-data folder from your old NarraFirma installation into the new version folder.
- Copy the file server/superuserinformation.json to the same folder in your new installation.
- Rename your old NarraFirma folder (to “NarraFirmaOld” or something). Rename your new NarraFirma folder to whatever you called it before.
- Restart your NarraFirma server.
Installing NarraFirma with WordPress
To run NarraFirma using an existing WordPress installation:
- Download the NarraFirma 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).
- 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.
- 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 NarraFirma with Node.js
To run NarraFirma with an existing Node.js installation:
- Download the entire NarraFirma source file (narrafirma.zip) from the NarraFirma GitHub releases page.
- Unzip the narrafirma.zip file.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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 quickly 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
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).
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.