Menu Developer Moovweb University

Develop Locally: moov_config.json

This section covers everything you need to know about configuring your project in the moov_config.json file. The file follows standard JSON syntax, as seen below:

{
  "moovweb_project_format_version": "1.0.0",
  "host_map": [
    "$.example.com => www.example.com"
  ],
  "new parameter name": "new parameter value" // example syntax
}

Host Maps

Host mapping is used to make sure all the requests and responses of a project point to the right place. The host_map parameter lets you choose what hostnames your project will map and determines how HTTP requests/responses and cookie domains will be rewritten.

This is how the Moovweb SDK server uses the host_map parameter:

  • Going from the Moovweb SDK server to an upstream server, an incoming request “http://m.example.com/foo” is rewritten to an upstream request “http://www.example.com/foo”.
  • Coming from the upstream server to the Moovweb SDK server, the upstream response “http://www.example.com/foo” is rewritten to the outgoing response “http://m.example.com/foo”.

Note that same mapping is used in both directions.

Specifying a Host Map

In a rehosted project with subdomains, the symbol “$” is used to specify a host_map for the project:

"host_map": [
  "$.example.com => www.example.com",
  "$.dup.example.com => www.example.com",
  "$.search.example.com => search.example.com"
]

The “$” represents the host variable. During local development, you can set the host variable with the -host-var flag when you start moov server. By default, it is set to mlocal. When your project is deployed to the Control Center, you may submit a request to change the value of the host variable in your project.

Parameter Evaluation

The host mapping parameter evaluation follows these rules:

  • Evaluation is done in order, starting at the top of the host_map array.
  • It looks for a string match, not a regex or pattern match.
  • Every rule is listed out into “http://” and “https://” using the host variable.

For example, if we have the rule $.example.com => www.example.com and the host variable is m, the list of mappings that will be checked and rewritten by the transformation server is:

"host_map": [
  "http://m.example.com" => "http://www.example.com",
  "https://m.example.com" => "https://www.example.com"
]

It’s important to note that once there is a match during the evaluation process, the engine will stop evaluation of any other rules that are below the matching string.

Managing host mappings via console.moovweb.com

The host_map section in your moov_config.json allows you to map domains while testing your project locally. The moov deploy command adds any new host mappings from the moov_config.json file to your project settings in the cloud. moov deploy does not overwrite or remove any host mappings from the cloud. To remove a host mapping from the cloud, go to the click the Project Settings button in the console. At the bottom of the Domains tab you will see your mappings and a button to remove them.


Layers

Layers are used to define variations on the project, for presentation to different modes.

"host_map": [
  "$.example.com => example.com"
],
"layers": ["mobile", "tablet", "mobile/beta", "tablet/beta"]

If you are going to present different versions of your site to different audiences, you can define separate layers for each of those presentations, and then deploy the layers to specific sites they were designed to support.

The mappings allow you to maintain complete separation between the layers in your project and the sites where they are displayed, so you can develop and manage them independently.

Layers are also used to specify deployment options like JavaScript and CSS minification.

You specify what layer you want mapped to which site when you deploy to that site. For more information on how layers work, visit our Layers documentation page.


Task Runner

The Task Runner is a build automation process to automate common tasks. This allows the developer to focus on writing code and not have to worry about rebuilding, refreshing or packaging the project. By default, we use the Task Runner to recompute css files, lint and concatenate javascript files, and even reload assets in an open web browser asyncronously as they change.

The default template includes specific scripts to execute using Node.js. These can be found in the ./tasks folder.

The “taskrunner” key requires Moovweb SDK version 6.2 or greater.

There are three Task Runner event hooks: when a project starts (on_project_start_command), when a request hits the moov server (on_request_command), and when the moov deploy command is executed (on_deploy_command).

NOTE: All of the Task Runner fields must be defined for your project to start. If you do not have a task to run, replace the task file with an empty file, but leave the Task Runner command in the moov_config.json file.

By default, the taskrunner fields are defined for you like so:

"taskrunner": {
  "on_project_start_command": "node ./tasks/start",
  "on_request_command": "node ./tasks/request",
  "on_deploy_command": "node ./tasks/deploy"
},

project_start_command specifies commands to run when your project is started in the Developer Dashboard. By default, the Gulp default task will be run under project_start_command and continue to run until the project stops. The default Gulp task monitors your project for changes then recompiles your project and refreshes your browser.

per_request_command is called each time a request is made to the local server. The default task displays the following in the logs:

TaskRunner STDOUT: =========================New Request=========================

on_deploy_command is called each time your project is deployed to the cloud. The default task rebuilds your project before deploying.

As the command is used on Windows machines, the best practice is to call a node program (like npm, browserify, or gulp) and put platform specific commands inside there.

You can use other scripting languages or runtime environments such as, ruby or python, to execute taskrunner scripts.

In development, if any of the tasks in the task runner throws an error, the project will stop and you will see the details of the error.

The taskrunner can be used by Tritium projects that include the above “taskrunner” json structure in their moov_config.json file, but it requires version 6.2 of the SDK.


Cookies are also rewritten automatically using the host mapping. For more, see the Project Configuration documentation for details.


Manually Editing Your Hosts

Starting from SDK version 4.5+, moov server now runs with the flag --auto-hosts=true by default. This lets the server automatically make changes to your local hosts file so that you are able to hit the mlocal hostnames in your browser. If you are working on a project that has a lot of subdomains, we recommend using this default behavior. If you need to turn it off, you can run the server with --auto-hosts=false.

If you need to manually edit your hosts file for any reason (such as to add additional domains), here’s how you can do this on different OSes for the domain mlocal.example.com:

Instructions for Editing Hosts File

For Linux/Mac users, open the hosts file using sudo:

sudo vim /etc/hosts

(This opens the file using vim. You can also open it in a text editor of your choice — for example, replace vim with mate to open in TextMate.)

For Windows users, go to Start and find the Notepad application. Right-click on the application and select “Run as administrator”.

Open the following file:

C:\Windows\system32\drivers\etc\hosts

Once you have opened the hosts file, you can add the following line:

127.0.0.1 mlocal.example.com

This line tells your computer to try to connect to the IP address 127.0.0.1 when you type in the hostname “mlocal.example.com”. You can add as many different hostnames and IP addresses as you need. This is actually the same process that the moov server uses, but it is completely automated!


SSL Whitelist

This parameter may be needed if your upstream domains are using HTTPS but the certificate is invalid. If the Moovweb SDK server detects that the certificate has problems, you will see an error message along the lines of:

Failed to establish a connection with upstream (certificate is valid for www.example.com, not qa.example.com)

To allow the Moovweb SDK server to bypass these certificate errors and accept the connection from the upstream server, you can use the ssl_whitelist parameter.

This parameter takes a list of upstream domains:

"ssl_whitelist": [
  "qa.example.com",
  "test.example.com"
]

WARNING: Do not add domains which handle actual secure transactions to this whitelist. You should remove these when you go to production.


Static Paths

Static paths is an exciting new feature that is available in SDK version 4.5.73 or higher. To use this, you must also configure your Mixer.lock file to use the mixer core-rewriter 2.1.109 or higher.

You can create new HTML pages under your assets folder and map new paths with the static_paths parameter and this syntax:

"static_paths": {
  "/example/path": "index.html"
}

When a request is made for “/example/path”, the Moovweb SDK server will retrieve index.html from the local assets folder and serve the content from there. No upstream request is made. This method is great for making pages that only make sense on mobile sites and is a perfect example of responsive content delivery!


User Agent

The user_agent parameter allows you to configure a fixed User-Agent header that will be sent with all upstream requests.

"user_agent": "Mozilla/5.0 (X11; U; Linux x86_64; en-US) AppleWebKit/533.4 (KHTML, like Gecko) Chrome/5.0.375.86 Safari/533.4"

HTTP Version

By default, the Moovweb SDK server sends upstream requests using HTTP 1.0, but the http11 parameter allows you to specify that upstream requests should use HTTP 1.1.

"http11": true

Basic Authentication

You can add basic authentication so that only people with the username and password can see your project website. You must use the mixer simple-mobile (1.0.224) or higher in your project. To configure basic authentication, add the credentials parameter like this:

"credentials": {
  "user": "username",
  "password": "LetMeIn"
}

Once you do this, a popup will appear when you try and access the website.

NOTE: Currently the password field only supports plaintext.