Admin page

Admin page

From v1.42, Gramex ships with an admin page. To include it in your page, use:

import:
  admin/admin:
    path: $GRAMEXAPPS/admin2/gramex.yaml    # Note the "admin2" instead of "admin"
    YAMLURL: /$YAMLURL/admin/               # URL to show the admin page at

You can configure the admin page as follows:

import:
  admin/admin-kwargs:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-kwargs/        # URL to show the admin page at
    ADMIN_KWARGS:
      logo: https://gramener.com/uistatic/gramener.png  # Logo URL
      home: /$YAMLURL/                                  # URL that logo links to
      title: Admin  Page Options                        # Navbar title
      components: [info, users, shell]                  # Components to show
      theme: '?font-family-base=roboto'                 # UI component theme query
    ADMIN_AUTH:
      membership:
        email: [admin1@example.org, admin2@example.org]     # Only allow these users

The ADMIN_KWARGS section accepts the following parameters:

The ADMIN_AUTH section is the same as specifying the auth: authorization on all admin pages. For example:

    ADMIN_AUTH:
      login_url: /$YAMLURL/login/
      membership:
        email: [admin1@example.org, admin2@example.org]     # Only allow these users

… is the same as specifying this on every admin page:

    auth:
      login_url: /$YAMLURL/login/
      membership:
        email: [admin1@example.org, admin2@example.org]     # Only allow these users

Admin: User management

To manage users, add roles and other attributes, use the user component. To enable it:

  1. Ensure that users is in components: (e.g. components: [users, ...]) or you don’t specify any components.
  2. Add an authhandler: that has the name of a auth handler that is either a DBAuth or has a lookup section

For example:

import:
  admin/admin-user:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-user/
    ADMIN_KWARGS:
      authhandler: login        # Manages users via the url: key named "login"

url:
  login:                        # Here is the url: key named "login"
    pattern: ...
    handler: DBAuth             # This must either be DBAuth...
    kwargs:
      ...
      lookup:                   # ... or have a lookup: section
        ...

User management is available as a component. To embed it in your page, add a FormHandler table component:

<div class="users"></div>
<script>
  $('.users').formhandler({
    src: 'admin/users-data',    // Assuming the admin page is at admin/
    edit: true,                 // Allow editing users
    add: true                   // Allow adding users
  })
</script>

You can specify custom actions & formats using FormHandler table. See the admin page source code for examples of custom actions.

Admin: Schedule

The schedule component lets you see all scheduler tasks defined under the schedule: section, and run them.

The admin schedule component can be embdded in any page:

<div class="schedule"></div>
<script src="schedule.js"></script>
<script>
  $('.schedule').schedule({           // Embed the scheduler
    url: 'admin/schedule-data',       // Assuming the admin page is at admin/
    xsrf: '{{ handler.xsrf_token }}'  // Pass XSRF token. Requires FileHandler template
  })
</script>

Admin: Alerts

The alert component lets you see all alerts defined under the alert: section, and preview or run them.

The admin alert component can be embdded in any page:

<div class="schedule"></div>
<script src="schedule.js"></script>
<script>
  $('.schedule').schedule({           // Alerts use the same component as schedulers
    alert: true,                      // ... but with the alert: true option
    url: 'admin/alert-data',          // Assuming the admin page is at admin/
    xsrf: '{{ handler.xsrf_token }}'  // Pass XSRF token. Requires FileHandler template
  })
</script>

Admin: Shell

The shell adds a web-based Python shell that runs commands within the running Gramex instance. This is useful when debugging a live environment. To enable it, ensure that you specify:

In the shell, you can run these commands:

1 + 2                   # Evaluate Python expressions
import gramex           # All gramex libraries are available
handler.session         # WebsocketHandler instance is available as 'handler'

The web shell is available as a component. To embed it in your page, add:

<div class="webshell"></div>
<script src="admin/webshell.js"></script>
<script>
  $('.webshell').webshell({           // Embed the web shell here
    url: 'admin/webshell-data',       // Assuming the admin page is at admin/
    prompt: '>>> ',                   // Prompt to display at the start of each page
    welcome: [                        // Welcome message as a list of lines.
      'Welcome to the Gramex shell',
      '>>> '
    ]
  })
</script>

Admin: Info

The info page shows information about versions, paths and other details about Gramex and its dependencies.

To enable it, ensure that you specify:

This exposes JSON data at <admin-page>/info-data as a list of objects consistent with FormHandler.

[
    {"section":"git","key":"path","value":"D:\\bin\\git.EXE","error":null},
    {"section":"git","key":"version","value":"git version 2.15.1\n","error":""},{"section":"gramex","key":"memory usage","value":153411584,"error":""},
    ...
]

The information provided includes (in a <section>.<key> notation):

The result is stored in the value column. If the value is not available, the error is stored in the error column.

Admin: Config

WIP: Shows the Gramex configuration, and allows users to edit it.

Admin: Logs

WIP: Shows the Gramex logs.

Admin access control

TODO: explain how to restrict admin access

Admin page (old)

From v1.33, Gramex used a beta version of the admin page. This is deprecated.

To use it, add this to your gramex.yaml:

import:
  admin1:
    path: $GRAMEXAPPS/admin/gramex.yaml   # Source of the app
    YAMLURL: /$YAMLURL/admin1/       # Location to mount at
    ADMIN_LOOKUP:
      url: $YAMLPATH/lookup.xlsx          # DB / file with user information
      id: user                            # Column name that has the user ID

Use ADMIN_* variables to configure your app.

Sample use of role:

import:
  admin:
    path: $GRAMEXAPPS/admin/gramex.yaml
    YAMLURL: /$YAMLURL/admin/
    ADMIN_LOOKUP:
      url: $YAMLPATH/lookup.xlsx
      id: user                   # user column in Excel sheet has the user name
    ADMIN_USER: ['alpha']        # Always allow user `alpha`
    ADMIN_ROLE: ['admin']        # Also allow anyone with role as admin
    LOGIN_URL: /admin/           # URL to show login page for admin page
    LOGOUT_URL: /logout/         # URL to logout

By default, admin site can be accessed by any user when using 127.0.0.1.