Online storytelling system
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Esteban Manchado Velázquez 94cffb5997 Update/fix installation instructions and Dockerfile 3 months ago
app Show player notes on the character sheet 3 months ago
config Support full UTF-8 2 years ago
docs Add some development notes 3 months ago
html Drop unused CSS classes and ids 1 year ago
mail-templates Fix claim email text 2 weeks ago
migrations Implement custom styles for narrations 1 year ago
public Fix header styling issue in chapters 4 weeks ago
robohydra Add simple RoboHydra development proxy 4 years ago
src Fix claim email text 2 weeks ago
tests Use proper quotes in emails 10 months ago
ux Strike through one of the UX recommendations (implemented) 3 years ago
.babelrc First commit 4 years ago
.dockerignore Add Docker configuration files 3 years ago
.gitignore Add Docker configuration files 3 years ago
.jshintrc First commit 4 years ago
Dockerfile Update/fix installation instructions and Dockerfile 2 weeks ago
LICENSE Add license (simplified BSD) 4 years ago Update/fix installation instructions and Dockerfile 2 weeks ago
brunch-config.js Upgrade to Elm 0.19 2 years ago
docker-compose.yaml Add Docker configuration files 3 years ago
elm.json Upgrade to Elm 0.19.1 (no code changes) 1 year ago
npm-shrinkwrap.json Upgrade some dependencies (security) 1 month ago
package.json Upgrade some dependencies (security) 1 month ago
update-db-migrate-conf.js Drop need to create database.json by hand 4 years ago


NARROWS is an online storytelling system. The name stands for NARRation On Web System. The easiest way to explain it is to imagine an online Choose Your Own Adventure book with the following differences:

  1. Instead of having a single reader, there are as many readers as protagonists in the story (it could be one, but also four or five).
  2. Instead of having to choose between two or three preset choices after each "chapter", readers can write in a textbox whatever their characters do.
  3. Instead of the narrator writing the whole story with all possible branches upfront, then give it to the readers; the narrator writes only one chapter at a time and waits for the readers to submit the "actions" for their characters. Based on those actions, the narrator writes the next chapter.

You can also think of it as a way of running ruleless, diceless RPGs online (which is indeed the reason why I wrote it in the first place).


NARROWS is a web application with a backend. As such, it needs a server connected to the internet to be used. To install you need to run the following steps:

  1. Clone the code somewhere.
  2. Make sure you have Node.js (at least version 10) and NPM (at least version 4).
  3. Run npm install (note that you cannot use yarn!)
  4. Install Elm 0.19.1
  5. Run npm run build
  6. Install MySQL, create a new user and an empty MySQL database. Make sure the new user has all privileges to that database.
  7. Copy config/default.js to config/local-production.js and modify any values you need.
  8. Run NODE_ENV=production npm run dbmigrate
  9. Run NODE_ENV=production node build/index.js

If all this works you will have to find a way to keep the server running, eg. supervisor.

Updating the code

Every time you update the code you will have to install any new dependencies with:

npm install

And run any new migrations with the following command. Note that you might need to pass the NODE_ENV variable as in the installation instructions above:

npm run dbmigrate

Then you will have to recompile the frontend and backend code with:

npm run build

Running the tests

To be able to run the tests you need to create two test databases: the main one, and the "user storage" one. For the first one you have the settings in config/test.js. The second one is the same, except for the database name, which is narrows-userstore-test.

Once you have the two databases created and the test user created and have given access to them, you can run the tests by typing:

npm t


This repo includes a Dockerfile for building a deployable image. It also contains a docker-compose.yaml suitable for quickly getting a local copy running. The Dockerfile and compose file have been used (with modification) to host a production version of the app.

To get going with docker-compose:

docker-compose create && docker-compose up -d

If you want to host it publicly and setup e-mail, add the appropriate Docker environment variables from below:

  • PORT: port to listen to.
  • PUBLIC_ADDRESS: used to generate URLs in e-mails.
  • DB_HOST: MySQL hostname/IP.
  • DB_USER: MySQL username.
  • DB_PASSWORD: MySQL password.
  • DB_NAME: database name.
  • FROM_EMAIL: e-mail address to send from. e.g. "Narrows" <>.
  • NODEMAILER: a nodemailer URI configuration string, e.g. smtps://

Note: NODEMAILER URI strings need to URI escape special characters within username/password. For example, usernames often contain @, and AWS SES passwords often contain /.



  • Speaker/mute icons made by Madebyoliver, from Flaticon. They are licensed under Creative Commons BY 3.0.
  • Trash icon by Freepik, from Flaticon. Licensed under Creative Commons BY 3.0.
  • Add/plus icon, message icon, user icon, info icon and edit icon by Lucy G, from Flaticon. Licensed under Creative Commons BY 3.0.
  • RSS icon by Dave Gandy from Flaticon. Licensed under Creative Commons BY 3.0.
  • Vintage divider by Web Design Hot. Licensed under Creative Commons BY 3.0.


  • Tess Gadwa (tessgadwa): UX help and recommendations.
  • James Sapara (interlock): Docker setup.