Using YAMLURL and YAMLPATH

Suppose you create a gramex.yaml like this:

url:
  app-home:
    pattern: / # The home page
    handler: ...

This works fine locally. But when you deploy it on a server under /app, it won’t work. That’s because you’ve mapped the URL /, not /app/.

Since you don’t know beforehand which directory you’ll be deploying the app, it’s best to use pattern: /$YAMLURL/ instead. $YAMLURL the relative URL to the current gramex.yaml location. In your local machine, this becomes /. On the server, this becomes /app/.

You also need to use these when specifying redirection URLs. See this example:

url:
  auth/simple:
    pattern: /$YAMLURL/simple
    handler: SimpleAuth
    kwargs:
      credentials: { alpha: alpha }
      redirect: { url: /$YAMLURL/ } # Note the $YAMLURL here

Using /$YAMLURL/ redirects users back to this app’s home page, rather than the global home page.

Tips:

Using YAMLPATH

$YAMLPATH is very similar to $YAMLURL. It is the relative path to the current gramex.yaml location.

When using a FileHandler like this:

url:
  app-home:
    pattern: / # This is hard-coded
    handler: FileHandler
    kwargs:
      path: index.html # This is hard-coded

… the locations are specified relative to where Gramex is running. To make it relative to where the gramex.yaml file is, use:

url:
  app-home:
    pattern: /$YAMLURL/
    handler: FileHandler
    kwargs:
      path: $YAMLPATH/index.html # Path is relative to this directory

Tips: