——

Dashboard Setup

By default, Factor includes a CMS-like post management system and dashboard. These features allow extension developers to create CMS oriented tools that are dynamic, consistent, and easy to manage.

Overview

To use the dashboard all you need is a MongoDB connection string, which gives us the datastore needed to save data, do auth, etc.

From there, different plugins may require different config information. E.g. AWS credentials. But ultimately the system is super simple to work with and extend. Let's discuss things in more detail below...

The DB Connection

The only thing that is required to get the dashboard running is a MongoDB/Mongoose compatible DB connection string. If you are not familiar with this, all you need to do is sign up for a service like Mongo Atlas and they will walk you through the steps needed.

Once you have it, just add the string to your .env file under the variable DB_CONNECTION.

# .env - DB Connection (Mongo Connection String)
DB_CONNECTION="mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test"

To make it easier, you can also run yarn factor setup which includes a simple utility for adding this string along with any other configuration your app/plugins may need. More on that below.

Users: Auth and Roles

Token Setup

Json Web Tokens (JWTs) are a standard, simple and effective way of managing authentication for your users with Factor.

All that is needed to make JWTs work is a "token secret" used for encoding them on your server. To add it:

# .env - Token Secret: Treat like a password, can be whatever you want
TOKEN_SECRET="SOME-LONG-STRING-WHATEVER"

User Roles

Factor includes a basic user role system controlled via your factor-config.json file. To add your first admin users, you'll need to add them to this file directly (or using factor setup CLI command described below).

// factor-config.json
{
  "config": {
    "roles": {
      "[email protected]": "admin",
      "[email protected]": "moderator",
      "[email protected]": "author"
    }
  }
}

Note: User account's email addresses must be successfully verified in order for admin privileges to be applied.

Accessing Your Dashboard

With DB and auth setup, all you need to do is visit localhost:3000/dashboard and you should be asked to "login" or "signup." Just hit "signup" and cteate an account and you should be able to see your dashboard.

At first, the dashboard will be bare-bones. This is because you likely haven't been made an admin and you haven't installed any plugins. So as a first step, run yarn factor setup and add your email as an admin. (This writes info to your factor-config).

Inside the dashboard, on your 'account' page, you'll find a button to send yourself a verification email. If you haven't set up transactional email yet, then the output of this email will be logged to your console. Visit the link that was sent to verify your email.

Once you've added yourself as admin and verified your email address, you should be able to see the admin options as well as basic user level options in your dashboard.

Factor Dashboard
Factor Dashboard

Essential Services

There are some services needed to power even the most basic apps:

Transactional Email

Basic email is needed for notifications and critical account tools like 'forgot password.' For this reason, Factor includes a simple email system that is powered by the standard SMTP.

To set up, just add the following to your .env file (or run factor setup)

# .env - SMTP connection info
SMTP_USERNAME="YOURUSERNAME"
SMTP_PASSWORD="---YOURPASSWORD---"
SMTP_HOST="your.host.com"

Note: We recommend AWS SES for SMTP email

Image Storage

By default, Factor uses your DB for image storage, this is not ideal for performance reasons. The good news is that adding an image storage plugin is easy. These plugins process and store images then return a URL to save in the DB, all done behind the scenes without any work on your part (after adding your API keys).

S3 Plugin

While it is possible to use any image storage service to store your images, Fiction has created a simple plugin that uses AWS S3 for storage.

To install Fiction's S3 image storage plugin:

$ yarn add @factor/plugin-storage-s3

Required S3 Configuration

# .env / AWS config info
AWS_ACCESS_KEY="YOURKEY"
AWS_ACCESS_KEY_SECRET="YOURSECRET"
AWS_S3_BUCKET="your-bucket-name"

The Setup CLI

Factor setup reduces guesswork needed to configure your app.

To run it, enter the following:

$ yarn factor setup

From here you'll be provided with a listing of needed configuration, as well as tools for adding or changing existing configuration options.

Factor Setup
Factor Setup