Configuration

Landmark Options

Setting Options

The options for LandmarkJS cover a range of behaviours, from how the express app is configured to enabling features and authentication options for integrated services.

There are three ways to set options:

• Passing a { key: 'value' } configuration Object to the landmark.init(options) method
• Calling landmark.set('key', 'value')
• Setting environment variables in process.env. Only some options support this (noted below).

If you want to keep secret keys and configuration out of your codebase (especially important for open source projects, or projects where not all developers should have access to production config settings) the dotenv module makes this very easy to manage.

Project Options

The following options control the branding and navigation of the LandmarkJS application in the Admin UI:

landmark.set('nav', {
    'users': 'users',
    'content': ['posts', 'post-categories']
});

Web Server Options

The following options control the configuration of your web server and the express app:

var swig = require('swig');
landmark.set('view engine', 'swig');
landmark.set('custom engine', swig.renderFile);

HTTPS Web Server Options

There are two ways to implement HTTPS for your LandmarkJS application: either use a web server (e.g. NGINX) or PAAS (e.g. Heroku) that handles it for you, or set the following options to use the https server provided by node.js.

Database and User Auth Options

The following options control your database configuration and user models / authentication:

"sessionStore": {
  "db": {
    "name": "myDb",
    "servers": [
      { "host": "192.168.1.100", "port": 28001 },
      { "host": "192.168.1.100", "port": 28002 },
      { "host": "192.168.1.101", "port": 27017 }
    ]
  }
}

"sessionStore": {
  "host": "", // Redis server hostname
  "port": "", // Redis server port
  "ttl": "", // Redis session TTL in seconds
  "db": "", // Database index to use
  "pass": "", // Password for Redis authentication
  "prefix": "", // Key prefix defaulting to "sess:"
  "url": "", // e.g. redis://user:pass@host:port/db
}

For more information about setting up and using database models with Landmark, see the database guide.

Services

Google Analytics

Landmark has support for Google Analytics tracking in the Admin UI. To enable tracking, set the following configuration options:

Note if you only want to include Google Analytics tracking in the front-end of your project, you should use different variable names from those above.

Google Maps

Landmark's Location field type supports integration with the Google Maps API to auto-improve values (including discovering latitude and longitude) via the Places Autocomplete API.

To enable these features, obtain an API Key from Google and enable the Google Maps v3 and Google Places APIs for it, then set the following options:

landmark.set('google api key', 'your-browser-key');
landmark.set('google server api key', 'your-server-key');
landmark.set('default region', 'au'); // optional, will limit autocomplete results to Australia

Note that the use of the Places Geocoding API is subject to a query limit of 2,500 geolocation requests per day, except with an enterprise license.

The Places Geocoding API may only be used in conjunction with a Google map; geocoding results without displaying them on a map is prohibited. Please make sure your Landmark app complies with the Google Maps API License.

Amazon S3

LandmarkJS supports Amazon S3 for file upload and hosting, with the S3File field type.

To use the S3File field in your app, sign up for an account, create an S3 bucket, and get your key and secret.

Then set the s3 config option to an object containing your configuration (see example below).

Alternatively, set the S3_BUCKET, S3_KEY and S3_SECRET environment variables.

landmark.set('s3 config', { bucket: 'my-bucket', key: 'my-key', secret: 'my-secret' });

Windows Azure Storage

LandmarkJS supports Windows Azure Storage for file upload and hosting, with the AzureFile field type.

To use the AzureFile field in your app, sign up for an account, enter into Azure Management Portal. Create a storage account with new(button), data services, storage. In storage account page get the access (account name, key (valid primary or secondary key)) with the button "manage access key".

Then set the azurefile config option to an object containing your configuration (see example below).

Alternatively, set the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY environment variables.

Note that the account property should be set to your storage account, not your user account.

landmark.set('azurefile config', { account: 'my storage account', key: 'secret api key' });

Cloudinary

Cloudinary is an image upload / resizing / hosting service that makes it easy to implement image management in your LandmarkJS app using the CloudinaryImage and CloudinaryImages field types.

To use the Cloudinary Image fields in your app, sign up for an account (Cloudinary offers a free tier with up to 500MB storage, 50,000 images and 1GB data transfer) and get your cloud name, api key and api secret.

Then set the cloudinary config option to

• an object containing your configuration (see example below), or
• the environment variable string Cloudinary gives you (e.g. cloudinary://api_key:api_secret@cloud_name)

This option will default to the CLOUDINARY_URL environment variable if it is set.

When images are uploaded to Cloudinary via the Admin UI or field methods, they will have some tags automatically set on them. To prefix these tags with a custom string, set the cloudinary prefix option.

The built-in tags that are automatically set include:

• {list.path}_{field.path}
• {list.path}_{field.path}_{item.id}
• {prefix} (if set)
• dev (if the env option is not set to production)

landmark.set('cloudinary config', { cloud_name: 'my-cloud', api_key: 'abc', api_secret: '123' });
// or
landmark.set('cloudinary config', 'cloudinary://api_key:api_secret@cloud_name' );
 
// optional, will prefix all built-in tags with 'landmark_'
landmark.set('cloudinary prefix', 'landmark-serve');

Embed.ly

Embed.ly is a service that will parse a url (e.g. Youtube embed link) and return a whole lot of useful information, like the provider name, summary metadata, width and height of videos, as well as a clean link to use for embedding media in your views. They offer a free plan for up to 5,000 urls per month.

The Embedly field type is an easy way to integrate their API with your LandmarkJS app.

To configure LandmarkJS to support the Embed.ly API, simply sign up for an account, get your api key, and set the embedly api key option.

This option will default to the EMBEDLY_API_KEY environment variable if it is set.

landmark.set('embedly api key', 'your-key');

Mandrill

Mandrill is a scalable and affordable email infrastructure service that allows you to send emails easily. They offer a free plan for up to 12,000 emails per month.

To configure LandmarkJS to support the Mandrill API, simply sign up for an account, get your api key, and set both the mandrill api key and mandrill username options.

These options will default to the MANDRILL_API_KEY & MANDRILL_USERNAME environment variable's if set.

landmark.set('mandrill api key', 'your-key');
landmark.set('mandrill username', 'your-username');

Application Updates

Landmark includes an updates framework, which you can enable by setting the auto update option to true.

Updates provide an easy way to seed your database, transition data when your models change, or run transformation scripts against your database.

Update files should be named using a semantic version followed by an optional key, like 0.0.1-init.js. The version numbers are used to order the update scripts correctly, while the keys are a nice way to identify what each update does.

Each update file should export a single function, which should accept a single argument - the next(err) callback, to be called when the update is complete.

All the update files will be executed (each one waits for the previous update to complete) before the web server is started.

If the next callback is receives an error it will be reported to the console, and application initialisation will halt.

You can temporarily disable updates from running in development by setting a __defer__ property on the exported function to true. Any subsequent updates will be skipped, but the application will be started.

Updates are only run once, and each completed update is logged in an app_updates collection in your database.

var landmark = require('landmark-serve'),
    User = landmark.list('User');
 
exports = module.exports = function(done) {
    new User.model({
        name: { first: 'Admin', last: 'User' },
        password: 'admin',
        isAdmin: true
    }).save(done);
};

Disabling the Admin UI

You can disable the Admin UI by setting the headless option to true.

This will allow you to use landmark.start() or landmark.routes(app) without Landmark creating route bindings for the Admin UI routes under /landmark.