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.
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.
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 lumeThe 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 passwordYour 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 localhostTo 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.spaceVim tips:
:wq will save and close your vim sessionBecause 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:localIn the second terminal:
# /lume
# navigate into data-api
cd data-api
# install dependencies
yarn install
# start up the server
yarn start:localIn the third terminal:
# /lume
# navigate into local-tiler
cd local-tiler
# install dependencies
yarn install
# start up the server
yarn startGreat! Now if everything worked, you should be able to visit http://dev.lume.space:3333 to see Lume running locally.
The Lume repository is actually composed of a number of smaller applications and microservices.
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.
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.
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.
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.
These are the components that make up most of the CMS side of the application.
...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.
These are the components that make up most of the storytelling side of the application.
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.
These are components that are being shared between the CMS and the Storytelling application.
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.
The Lume app uses both client and serverside routing thanks to next and express.
The static directory contains some assorted assets that are referenced by the app.
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.