Project Configuration

This section covers everything you need to know about configuring your project.

Outline


config.json

The config.json file is used to configure project options. Like the extension suggests, this file follows the JSON syntax for setting project options. To enable any of the configuration options below, just add them according to the JSON syntax:

{
  "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:

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:

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.

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.

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.

Cookies are also rewritten automatically using the host mapping. Please see the Cookies section 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!

Compass

Compass is an open-source CSS Authoring Framework that was used in earlier versions of the Moovweb SDK. It is no longer recommended for newer Moovweb projects, but for legacy projects that require Compass, the compass parameter is available.

"compass": true

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.

back to top


Mixer.lock

Mixers are Moovweb-provided libraries that enable different kinds of functionality, such as JSON handling, jQuery helpers, etc.

The Mixer.lock file specifies which libraries your project is using. This determines what functions are available for use in your Tritium scripts.

You can learn more in our writeup on Mixers. For a complete specification of each function in relation to its mixer, please visit the Tritium API.

back to top


Environment Variables

The Moovweb SDK server automatically sets several environment variables in each project. These variables are typically HTTP headers and config parameters. You can use these variables in your Tritium scripts.

The most frequently used are the $path and $status. The $path variable is often used in a mappings.ts file to specify transformation based on the page URL.

All the environment variables available are listed in the final-env.json file. This file can be found in the {Moovweb Project Path}/tmp/messages/{Folder ID} directory. To use one of these environment variables in Tritium, you need to add a dollar sign before it: “$variable”.

Example Environment Variables

Here’s an example of a final-env.json file. It is structured so that the variable name is on the left (before the colon) and the value is on the right, like so: "variable": "value".

{
  "0": "https://www.dropbox.com",
  "1": "https://www.dropbox.com",
  "2": "SAMEORIGIN",
  "3": "HTTP/1.0",
  "Content-Type-Charset": "UTF-8",
  "__catch_all__": ".moovapp.com",
  "accept_encoding": "gzip,deflate",
  "asset_host": "http://localhost:3003/",
  "body": "true",
  "body_length": "1195",
  "cache_control": "no-cache",
  "canonical_found": "false",
  "charset_determined": "UTF-8",
  "connection": "close",
  "content_type": "text/html; charset=utf-8",
  "cookie": "gvc=Mjg1NjE0NTk0MjAxMDUyNjY4MTc1NjYyMDE3OTAxNjU0NDk4NTc2",
  "date": "Fri, 07 Sep 2012 01:57:35 GMT",
  "device_stylesheet": "main",
  "found_conn": "true",
  "header_hh": "Host: ",
  "host": "mlocal.dropbox.com",
  "host_hh": "https://mlocal.dropbox.com",
  "key": "x_frame_options",
  "location": "https://www.dropbox.com/",
  "method": "GET",
  "path": "/",
  "pragma": "no-cache",
  "rewriter_url": "false",
  "secure": "false",
  "server": "nginx/1.0.14",
  "set_cookie": "flash=; Domain=dropbox.com; expires=Fri, 07-Sep-2012 01:57:35 GMT; Path=/; httponly",
  "slash_path": "/",
  "source_host": "www.dropbox.com",
  "status": "302",
  "use_global_replace_vars": "true",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/534.54.16 (KHTML, like Gecko) Version/5.0.5 Safari/533.21.1",
  "value": "SAMEORIGIN",
  "x_frame_options": "SAMEORIGIN"
}

back to top


HTTP Headers

You have limited ability to modify HTTP response headers. This is achieved with the export() function, which works like this:

export(export_variable, value)

Content-Type

The Content-Type variable can affect only the type and subtype (e.g., “text/html”) of the content and not the parameters (e.g., “charset=ISO-8859-4”). The Content-Type header must already exist.

export("Content-Type", "text/html")

Cache-Time

This is the only export variable that doesn’t correspond exactly to an HTTP response header. That’s because it sets multiple HTTP response headers.

The Cache-Time export variable sets the amount of time the page should be cached for. This should only be used when the transformed page has been made more cache-able than the original page.

It works by removing all caching headers (Cache-Control, Pragma, Expires), and then adding back in a Cache-Control header. The time is specified in seconds as in the Cache-Control max-age parameter.

export("Cache-Time", "1200")

The above example indicates that the page should be cached for 20 minutes (1200 seconds). It would set a Cache-Control header like this:

Cache-Control: public, max-age=1200

Location

Use this export variable to change a response into a redirect, or to modify the location of a response that is already a redirect.

export("Location", "/pants/underwear")

Setting this export variable will automatically change the status code from a 200 to a 302. However it won’t change the status code if it is something other than a 200 (like a 404 or 500).

Content-Type-Charset

Not used often. The Content-Type-Charset changes the parameters (e.g., charset=ISO-8859-4) of the Content-Type header. The Content-Type header must already exist.

export("Content-Type-Charset", $encoding)

The $encoding variable specifies the name of the encoding that the Moovweb SDK server detected for the text of this particular response.

Note that handling encoding is very tricky. Be careful with this functionality.

back to top


Cookies

Rewriting Cookies

The host_map is also used to rewrite the Set-Cookie header of HTTP responses issued by the upstream server. Cookie rewriting works as follows:

  1. Cookie domains are set from right-to-left according to the host_map.

    Take this host_map for example:

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

The right-hand side of the host_map will match the first occurrence of “www.example.com” and set the default cookie domain to “.example.com” using the left-hand side matching rule.

  1. The rewritten cookie domain uses the least restrictive domain between the two domains listed in the matching host_map rule.

    Here’s a cookie issued by the upstream server:

    Set-Cookie: flash=; Domain=www.example.com; expires=Fri, 07-Sep-2012 01:57:35 GMT; Path=/; httponly
    

    Notice the currently specified upstream cookie domain: “www.example.com”. The matching host_map rule yields the rewritten cookie domain: “.example.com”. So the cookie domain is rewritten to “.example.com” because that is the least restrictive between the two.

    So, in this case, the rewritten cookie looks like:

    Set-Cookie: flash=; Domain=.example.com; expires=Fri, 07-Sep-2012 01:57:35 GMT; Path=/; httponly
    

What if the two domains aren’t comparable?

For example, the upstream cookie domain is “bad.example.com”, but the host_map rule yields “good.example.com”.

"host_map": [
  "$.good.example.com => bad.example.com"
]

Because there is no least restrictive domain between “bad.example.com” and “good.example.com”, the Moovweb SDK will rewrite the cookie domain following the host_map rule. The resulting cookie domain will be “$.good.example.com”, where “$” is the host variable.

By default, the upstream hostname will be used as the domain for all cookies when unspecified.

However, if you’d like a different domain to be used, you can set the $cookie_domain_missing_replacement variable and that will automatically replace the unspecified domain.

If the initial page request is under a catchall domain (for example “.moovapp.com”), we append “.moovapp.com” to the end of the chosen cookie domain.

Adding Cookies

If you need to add a cookie to the page (rather than manipulate a current cookie), there is the add_cookie() function. The add_cookie() function take the following forms, which give you fine control over how a cookie is added.

  1. add_cookie(%raw)
  2. add_cookie(%name, %value)
  3. add_cookie(%name, %value, %domain)
  4. add_cookie(%name, %value, %domain, %path)
  5. add_cookie(%name, %value, %domain, %path, %expire, %secure, %httponly)

Options 2 and 3 are the most commonly used forms. %name is the name of the cookie, %value is the information to be stored, and %domain is the domain (treat the domain as if it were from an upstream response — the added cookie will be subject to rewriting). For example:

add_cookie("favoritedog", "joe", "www.example.com")

The above will set a cookie favoritedog with the value joe and the upstream domain would be “www.example.com” (but the domain would be rewritten according to the host mapping).

Option 1 gives a user full control over the cookie. You simply pass the entire “raw” text of the cookie to the function.

Read more about the usage of secure and httponly on Wikipedia.

back to top


Advanced Configurations

Users on the Moovweb Enterprise Edition have the ability to enable various advanced configuration options.

The following are Enterprise-only features. Although you can test it locally, these features will be disabled in the Cloud unless appropriately authorized.

Advanced Header Manipulation
Learn about total control over transforming both incoming and outgoing HTTP Headers.

Editing and Deleting Cookies
Gain total control over editing and deleting the cookies in a Moovweb project.

Strict Cookie Rewrite Mode
Prevent cookie sharing between the origin and transformed site by using strict cookie rewrite mode.

back to top