@galadrim/galadmin

Galadmin

Galadmin is a tool made by Galadrim that let you setup a pretty back-office in minutes. It works with any MySQL database.

Quick start

npm install @galadrim/galadmin

Integration in a NestJS app

Put this piece of code in your src/main.ts file:

import galadmin from '@galadrim/galadmin';
import { Config } from '@galadrim/galadmin/dist/types/config';

const adminConfig: Config = { ... }

app.getHttpAdapter().use('/admin', galadmin(adminConfig));

If you are using Prisma ORM, add the following code to your schema.prisma. Galadmin will create a table in your database, and Prisma won't be able to perform migrations correctly if we don't specify it.

With PostgreSQL

model galadmin_sessions {
  sid    String   @id @db.VarChar(128)
  sess   Json
  expire DateTime
}

With MySQL

model galadmin_sessions {
  session_id String  @id @db.VarChar(128)
  expires    Int     @db.UnsignedInt
  data       String? @db.MediumText
}

Integration in an Express app

const galadmin = require("@galadrim/galadmin").default;

app.use("/admin", galadmin(adminConfig));

What is adminConfig?

adminConfig is the object that contains all the configuration information about your back-office. Its properties are listed below.

Minimal example

const adminConfig = {
  name: "Mon projet",
  sessionSecret: "chapeaumelon",
  auth: {
    username: "user",
    password: "password",
  },
  postgresql: {
    host: "abc.example.com",
    user: "root",
    password: "password",
    database: "monprojet",
  },
  // mysql: {
  //   host: "abc.example.com",
  //   user: "root",
  //   password: "password",
  //   database: "monprojet",
  // },
  views: [
    {
      type: "table",
      label: "Fruits",
      tableName: "fruits",
      columns: [
        {
          label: "Nom",
          name: "fruitName",
        },
        {
          label: "Acidité",
          name: "acidity",
        },
      ],
    },
  ],
};

Configuration

const adminConfig = {
  /** Nom du projet (OBLIGATOIRE) */
  name: "Mon projet",

  /** Chaîne de caractères aléatoires qui permet de chiffrer les cookies de session (OBLIGATOIRE) */
  sessionSecret: "chapeaumelon",

  /** Identifiants permettant d'accéder au back-office (OBLIGATOIRE) */
  auth: {
    /** Nom d'utilisateur */
    username: "user",

    /** Password */
    password: "password",
  },

  /** Identifiants de connexion à la base de données (OBLIGATOIRE) */
  postgresql: {
    host: "abc.example.com",
    user: "root",
    password: "password",
    database: "monprojet",
  },
  // mysql: {
  //   host: "abc.example.com",
  //   user: "root",
  //   password: "password",
  //   database: "monprojet",
  // },

  /** Clé API Google Maps pour les champs adresses et l'affichage de cartes */
  googleMapsKey: "______",

  /** Désactiver la sélection multiple dans les vues de type table */
  hideMultiselect: true,

  /** Cache l'inscription Made with love by Galadrim */
  hideBranding: true,

  views: [
    {
      /** Vue de type "table" */
      type: "table",

      /** Nom affiché de la vue */
      label: string,

      /** Icône FontAwesome de la vue dans le menu. user affiche l'icône fa-user. */
      icon: "user",

      /** Nom de la table MySQL */
      tableName: "users",

      /** Nombre de résultats par page */
      limit: 100,

      /**
       * Ces champs permettent de personnaliser la requête MySQL qui gère l'affichage de la table.
       * Ils sont tous optionnels.
       *
       * SELECT {selectExpression} FROM {tableName} {join} WHERE {filters} GROUP BY {groupBy} ORDER BY {orderBy} {desc ? "DESC" : ""}
       */
      selectExpression: "*, MAX(age) AS maxAge",
      join: "JOIN activities ON users.activity_id = activities.id",
      groupBy: "activity_id",
      orderBy: "maxAge",
      isDesc: true,
      filters: "age < 50",

      /** Lorsque notClickable est à true, les résultats ne sont pas cliquables. (default: false) */
      notClickable: true,

      /** Rendre possible de créer des enregistrements (default: false) */
      canCreate: true,

      /** Groupe nominal "un nouvel élément" */
      aNewSingular: "un nouvel utilisateur",

      /** Rendre possible de supprimer des enregistrements (default: true) */
      canDelete: true,

      /** Rendre possible de modifier des enregistrements (default: true) */
      canEdit: true,

      /** URL appelée en POST lors de la création d'un nouvel élément, avec l'ID de l'élément créé */
      createCallback: "https://myapi.com/createCallback",

      editCallback: "https://myapi.com/editCallback",
      deleteCallback: "https://myapi.com/deleteCallback",

      columns: [
        {
          /** Nom affiché de la colonne (OBLIGATOIRE) */
          label: "Poids",

          /** Nom de la colonne dans la table MySQL */
          name: "weight",

          /** Formatter la valeur avant de l'afficher */
          formatValue: (user) => `${user.weight} kg`,

          /** Masquer la colonne dans la liste des résultats et ne l'afficher que dans le détail (default: false) */
          hideInTable: true,
        },
      ],
      subviews: [],
      recordViewPanels: [],
    },
  ],
};

File upload on S3

Different column types exists, one of them is the FileColumn, allowing the upload of a file onto AWS S3. A basic configuration would be as follow:

...
  columns: [{
    label: 'Image',
    name: 'imageUrl',
    dataType: 'file',
    s3Config: {
      host: process.env.AWS_S3_HOST,
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_KEY,
      bucket: process.env.AWS_S3_PODCAST_BUCKET_NAME,
      /** Optional, only needed when your bucket isn't public and you need to generate a signed URL */
      signedUrlNeeded: true,
      /** Optional, only needed when your bucket isn't public and you need to generate a signed URL */
      region: 'eu-west-3',
    },
  }]

File upload on Google Cloud Platform (GCP)

You can also use the FileColumn to upload files to Google Cloud Storage. To use GCP instead of AWS S3, configure the gcpConfig as follows:

...
  columns: [{
    label: 'Image',
    name: 'imageUrl',
    dataType: 'file',
    gcpConfig: {
      host: process.env.GCP_STORAGE_HOST,
      bucket: process.env.GCP_BUCKET_NAME,
    },
  }]

You also need to set up the service account credentials in your .env file:

GOOGLE_APPLICATION_CREDENTIALS=service-account-file.json

Make sure the service account JSON file is in your project directory and has the necessary permissions to write to your Google Cloud Storage bucket.

File upload on a remote server (via SFTP)

It is possible to use a FileColumn to allow upload to a remote server via SFTP. A basic configuration would be as follow:

...
  columns: [{
    label: 'Image',
    name: 'imageUrl',
    dataType: 'file',
    publicPath: '/home/ubuntu/project/public',
    subdirectory: 'img',
    sftpConfig: {
      host: process.env.SFTP_HOST,
      user: process.env.SFTP_USER,
      password: process.env.SFTP_PASSWORD,
    },
  }]

Local Setup

... nodemon index.js in your-project tsc --watch in galadmin npm run start in galadmin/src/front