Gramex 1.64 release notes

Gramex 1.64 makes deployment easier, with better support multiple apps per server, multiple logins per app, and secure and offline deployment.

Gramex IDE is in beta

You can access the IDE Beta at https://gramex.gramener.com/. The current version allows you to clone projects from Github and Gitlab, as well as create a repo from scratch.

Run multiple apps on a server

Running two Gramex instances on one server, e.g. at server.com/app1/ at port 8001 and server.com/app2/ at port 8002, is more robust.

When redirecting, Gramex needs the actual URL it’s deployed at (not localhost:8001). For example, when logging in or screen capturing.

Just add an X-Request-URI HTTP header in your proxy server to the actual URL. Gramex handles redirections automatically after that.

The configuration for nginx looks like this:

    proxy_set_header X-Request-URI $request_uri;

Log into multiple apps simultaneously

Two apps on one server may still need different login methods. E.g. app1/ uses Google Auth. app2/ uses Database Auth.

You can now define a different cookie for each app. Configure app1/ as follows:

app:
  session:
    cookie: app1-sid # Use 'app1-sid' cookie for this app instead of 'sid'

Multiple logins for the same app

A user may need to log in with multiple accounts. E.g. to share charts on multiple social media via Google, Facebook, Twitter, and Database Auth.

The documentation on multiple logins explains how to set this up, along with a demo

Deploy secrets securely

Passwords, access tokens, and other sensitive information needs to be protected. Gramex now supports a .secrets.yaml file where you can save these securely.

If you can edit files on the server (directly, or via CI), add an uncommitted .secrets.yaml file with your secrets, like this:

PASSWORD: your-secret-password
GOOGLE_AUTH_SECRET: your-secret-key
TWITTER_SECRET: your-secret-key
# ... etc

These variables are available in gramex.yaml as $PASSWORD, $GOOGLE_AUTH_SECRET, $TWITTER_SECRET, etc. For example:

url:
  login/google:
    pattern: /$YAMLURL/login/
    handler: GoogleAuth
    kwargs:
      key: add-your-key-directly # This is not a secret
      secret: $GOOGLE_AUTH_SECRET # This comes from .secrets.yaml

If you can’t edit files on the server, you can pick up encrypted secrets from a public URL in 3 steps.

1. Encrypt your secrets using this secret encryption tool
2. Store the encrypted secret anywhere publicly (e.g. at PasteBin or Github)
3. Add the URL and the encryption secret, in .secrets.yaml:

SECRET_URL: https://pastebin.com/raw/h75e4mWx
SECRET_KEY: SECRETKEY # Replace with your secret key

When Gramex loads, it loads SECRET_URL (ignoring comments beginning with #) and decrypts it using your SECRET_KEY.

Read more about deploying secrets

Offline installation

Offline installation is now a simple 2-step process:

1. Install Gramex using conda into a folder called gramex-offline
2. Copy the gramex-offline folder into the target system (which need not have an Internet connection)

Connect to more databases

Gramex FormHandler connections to 14 databases are now documented.

1. Amazon Redshift (new)
2. Apache Hive (new)
3. Apache Solr (new)
4. DB2 (new)
5. ElasticSearch (new)
6. Google BigQuery (new)
7. Google Sheets (new)
8. Microsoft SQL Server
9. MySQL
10. Oracle
11. PostgreSQL
12. SAP Hana (new)
13. SQLite
14. Teradata (new)

Client-side screen capture

CaptureHandler reloads a page to take a screenshot. This can be slow. To avoid this, you can use html2canvas and FileSaver.js, which are now part of the UI component library.

Trigger the download as follows:

html2canvas(document.querySelector(".chart")) // Pick the element to download
  .then((canvas) => {
    canvas.toBlob((blob) => {
      saveAs(blob, "chart.png"); // Pick your filename
    });
  });

Try the demo

Protect the entire app

To protect an entire app, i.e. add auth on all pages, use:

app:
  auth: true # All pages require login -- including CSS/images on login page!

Use with caution. This will be used as the default auth on every handler. The CSS/JS/images on your login page won’t appear unless you set auth: false on those URLs.

Tutorial on building an ML classifier

There’s a new tutorial on Creating an ML classifier application.

This is designed as a step-by-step 1.5 hour workshop for new Gramex users to introduce Gramex, show interactions, and teach them how to build a simple machine learning classifier.

Other changes

• The UI component bootstraptheme.css is now cached in the browser for a day – improving page load speed.
• The UI component moment.js is deprecated in favor of dayjs. Both will remain as part of Gramex, for backward compatibility.
• When using XSRF via AJAX, just add the header X-Requested-With: XMLHttpRequest to ignore the check. You don’t need to fetch an XSRF token from the server.
• CaptureHandler sometimes disconnects from Chrome after long usage. Now, it detects and automatically re-connects as required.
• Translation via Google Cloud now uses the new v3 API, and no longer fails.
• FileHandler now downloads Web Font files (e.g. .woff) instead of displaying them on screen.

What next

We promised two features in this release that are delayed. These will get pushed to November.

1. Extend PPTXHandler with custom charts
2. Add a 1-year roadmap for Gramex

In addition, the October 2020 release (1.65) will feature:

1. Python 3.8 support #300
2. ModelHandler support for TensorFlow, Keras and PyTorch models
3. Simplified FunctionHandler support #304
4. Notification for errors in alerts #292
5. Logviewer components that you can embed in any page to track usage #288

… and more.

How to install

See the Gramex installation and upgrade instructions

Note: Gramex 1.64 does not work with Python 3.8. We recommend Python 3.7.

Statistics

The Gramex code base has:

• 17,712 lines of Python (82 more than 1.63)
• 1,709 lines JavaScript (17 more than 1.63)
• 11,087 lines of test code (140 more than 1.63)
• 89% test coverage (same as 1.62)