Ulabase

Get started

The root user

Every service has a root user with the widest permission of the service. How to set its password, when to use the Admin JWT, and why your app signs in with its own users.

Every service comes with a user called root. Root starts with the widest permission of the service: it reads and writes any collection, and changes users, permissions and settings. It is a permission like the others, so you can change it. When you create the service, the console generates a strong password for root, sets it on the service and lets you copy it once.

You use root to set up and look after the service, from a terminal or a script. This page says how to set and reset its password, when the Admin JWT is the better choice, and why your app signs in with its own users.

The password

The password is generated in your browser and sent only to your service. It never goes through the payment, and we do not store it.

If root has no password yet, the service’s Home says so at the top: Your root user has no password yet. This happens when the page after the creation did not open, for example when you closed the tab during the payment. Click Generate root password, then Copy root password.

To change it, on the service’s Home, in the Basic Auth box, type a new password of at least 8 characters and click Reset password.

The service’s Home

The console does not keep the password, so it cannot show it later. If you know it and want the console to use it in this session, type it and click Use it: it stays in the browser tab and is never sent to the server.

Reset password changes the password on the service. Anything that used the old one stops working until you update it.

The Admin JWT

Next to Basic Auth is the Admin JWT: a token with administrator rights that lasts 15 minutes. Use it for a quick test from a terminal, without typing the password:

curl -i https://c0ffee.ulabase.app/todos \
  -H "Authorization: Bearer <admin-jwt>"

When it expires, click Refresh for a new one. See Tokens for what this token can reach.

What root is for

Use root to set the service up: create collections, users and permissions from a terminal or with ulabase, and check things by hand.

Your app never uses root. It signs in as one of the service’s own users, each with the roles and permissions you grant. You need a user, created through sign-up or on the Users page, and a permission on the Permissions page. The console’s API Tutorial does this in its last two steps.

How root gets its powers

root holds the root role, and the service is created with the permission rootCanDoEverything, which grants that role every path of the service:

{
  "_id": "rootCanDoEverything",
  "roles": ["root"],
  "predicate": "path-prefix('/')",
  "priority": 0,
  "mongo": {
    "allowManagementRequests": true,
    "allowWriteMode": true,
    "allowFilter": true,
    "allowBulkPatch": true,
    "allowBulkDelete": true
  }
}

You see it on the Permissions page, and you can change it like any other permission, for example to narrow it. Do not delete it: without it, nobody can administer the service.

Do it from the command line

ulabase does not need the root password. It signs in to the service with an Admin JWT, the token of the box above, which it asks for itself.

If you want the password of root in your pipeline’s secrets, set it with a step:

import { defineSetup, step, fromEnv, resolveEnvRefs } from '@ulabase/cli';

export default defineSetup('Root', [
  step('root password is the one in ROOT_PASSWORD', {
    async check({ service }) {
      // try to sign in as root with the password in ROOT_PASSWORD: if it works, the password is already set
      const basic = Buffer.from(`root:${process.env.ROOT_PASSWORD}`).toString('base64');
      const res = await fetch(`${await service.url()}/users/root`, {
        headers: { Authorization: `Basic ${basic}` },
      });
      return res.ok;
    },
    apply: ({ service }) =>
      // set the new password; resolveEnvRefs() replaces fromEnv('ROOT_PASSWORD') with the value of that variable
      service.fetch('/users/root', {
        method: 'PATCH',
        body: JSON.stringify(resolveEnvRefs({ password: fromEnv('ROOT_PASSWORD') })),
      }),
  }),
]);

The check signs in as root with the password from the environment, so a second run changes nothing. The step changes only the password, as Reset password does.