A story telling application for museums with an accompanying CMS.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
blog
config
data-api
hooks
iiif
image-tiler
local-tiler
mia-micro-obj-search
mia-micro-obj
scripts
.gitignore
.prettierignore
.prettierrc.json
.travis.yml
README.md
package.json
yarn.lock

README.md

Lume

Welcome to Lume, a digital storytelling platform by the Minneapolis Institute of Art.

If you are interested in contributing to Lume or running your own instance with further configuration, head over to the Wiki for more detail information about Lume.

Table of Contents

Running Lume

Local Quickstart

If you're interested in contributing to Lume (or you just want to try it out on your own machine), you can follow these directions to get the application running on your local machine.

Lume is a feature-rich, full stack application that utilizes a number of different services and can be configured in a number of different ways. In this quickstart, we are going to launch Lume in local mode.

Disclaimer: These directions are for Mac users. Because Lume is largely a Node application, some of its dependencies don't play well with Microsoft operating systems.

  1. Clone the repository

Open up your terminal, navigate to the directory where you like to keep your coding projects, clone the repository, and the navigate into the lume directory.

# /<your-code-directory>
git clone https://github.com/artsmia/lume.git
cd lume
  1. Configure your local host file

The default .env.TEMPLATE uses custom subdomain. To configure this you'll need to open up a terminal.

#this is assuming you have a mac and your hosts file is in etc
#we are gong to edit the hosts file using vim –– you can use a different text editor if you like
sudo vim /etc/hosts
#you will likely be prompted for your password

Your hosts file should look something like this:

#
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1       localhost

To configure your hosts file, you just need to add the following on to the end:

127.0.0.1       dev.lume.space
127.0.0.1       dev.cms.lume.space
127.0.0.1       dev.api.lume.space

Vim tips:

  • press i to switch to insert mode
  • navigate with arrow keys to where you want to edit
  • when you're finished, escape will get you out of insert mode
  • the command :wq will save and close your vim session
  1. Install dependencies and start up the application(s)

Because Lume is actually made up of a number of different services, you'll need to open up three different terminal windows.

In the first terminal:

# /lume
# navigate into app
cd app

# install dependencies
yarn install

# start up the server
yarn start:local

In the second terminal:

# /lume
# navigate into data-api
cd data-api

# install dependencies
yarn install

# start up the server
yarn start:local

In the third terminal:

# /lume
# navigate into local-tiler
cd local-tiler

# install dependencies
yarn install

# start up the server
yarn start
  1. Try the site!

Great! Now if everything worked, you should be able to visit http://dev.lume.space:3333 to see Lume running locally.

Configuration

Deploying with Now

Overview

The Lume repository is actually composed of a number of smaller applications and microservices.

app

The app directory contains the codebase for the front end UI for Lume's CMS and storytelling application. It is written in es6+ Javascript and compiled using babel.

Production is deployed using Now.

The application has been configured for unit tests –– and several have been written, however, more development is needed in this area.

apollo

The frontend uses a client-side store powered by apollo to fetch data for the components and to maintain local state.

Each root level page component has been wrapped with a higher order component (HOC) that's defined in app/apollo/index.js. This HOC is responsible for ensuring that the root page components have access to the apollo client when rendered on the server and that server state is then passed along to those components on the client.

Most of the lower level components in the application then use the queries and mutations defined in the queries and mutations directories to define their own data needs.

auth

Authorization is handled by Auth0 and passport–– though this can be disabled by running the application in local mode.

The class defined in /app/auth/index.js manages authentication during the getInitialProps lifecycle method on root page level components where necessary.

components

All of Lume's components have been built with React. They are typically housed in a directory with the name of the component. The actual component file usually lives in a file fitting the <ComponentName>.component.js convention.

The index.jsfile typically uses HOC to wrap the directory's component in a number of HOC which provide the component with the data it needs.

cms

These are the components that make up most of the CMS side of the application.

contents

...Except for the Content components. Each of the directories in the contents directory define both the editor and display components for the apps different content types.

lume

These are the components that make up most of the storytelling side of the application.

mia-ui

Most of the lowest level presentational components are drawn from a shared library of home grown React components –– though many components will also define their own styled components at the end of the file.

They have been styled with styled-components and grid-styled and are loosely styled to match Mia's own style guide.

shared

These are components that are being shared between the CMS and the Storytelling application.

pages

The pages directory contains React components that have been wrapped in the apollo WithData HOC and make use of next's getInitialProps lifecycle method. Their paths are referenced in the router and as the pathname variable given to next/link components.

router

The Lume app uses both client and serverside routing thanks to next and express.

static

The static directory contains some assorted assets that are referenced by the app.

config

The config directory is where you should keep any environment variables you'll need to run Lume locally. The .gitignore file is set to ignore any .env files so that you can keep any secrets out of source control. The .env.TEMPLATE file gives an example of the configuration information that's being used through out the application.

Environment variables for other environments are defined with those environments. For instance, in production, the data-api and app have their environment variables saved using now's secret api and are referenced in their respective now.json files.

data-api

image-tiler

local-tiler

mia-micro-obj

mia-micro-obj-search

scripts

.travis.yml