Administration User Interface

LightNet enables you to manage your content using JSON files. This is great for developers, but might be challenging for non-technical users. That’s why LightNet provides an Administration User Interface (Administration UI) to manage your content with a graphical user interface. The interface allows you to create, update, and delete media items and media collections. To implement the interface, LightNet uses a tool called Decap CMS.

All changes made in Administration UI are either written to the local file system or to a git host.

Experimental

The Administration UI is an experimental feature.

It enables the content administration for most scenarios. Some scenarios require manual changes on the JSON files (for example changing the identifier of a media item is not yet supported by the Administration UI). Implementing a better Administration UI is on our roadmap.

Add the Administration UI to your project

This is how you add the Administration UI to your LightNet project:

Note

Eventually the Administration UI is already installed by your template (e.g. Sk8 Ministries includes it). Nevertheless you can follow this guide from the beginning.

1. Add the Integration: Add the LightNet Administration UI integration (@lightnet/decap-admin) using Astro’s add command. From your project folder execute:

   npm run astro add @lightnet/decap-admin

   Confirm the questions with y to install required dependencies and add the integration to your astro.config.mjs file.

2. Adjust Configuration: Add your configuration to Astro’s astro.config.mjs file. This is a minimal example:

   astro.config.mjs

   import lightnetDecapAdmin from "@lightnet/decap-admin"
   import { defineConfig } from "astro/config"
   import lightnet from "lightnet"
   
   const languages = [{
     code: "en",
     label: "English",
     isDefaultSiteLanguage: true
   }];
   
   export default defineConfig({
     integrations: [
       lightnet({
           languages: languages,
           //...
       }),
       lightnetDecapAdmin({
           languages: languages,
       })
     ]
   });

   This adds a shared languages configuration to both the LightNet and the Administration UI integration. The Administration UI uses the languages configuration to fill the language selection dropdowns for media items.

Caution

We recommend setting the path option of the Administration UI integration, to hide it from attackers. Choose a random string with at least 16 characters.

Run the Administration UI

The Administration UI can write its changes to your local file system or to a git host (GitLab or GitHub).

Accessing your Local File System

Run your Administration UI on your local computer using npm scripts.

1. In your Terminal execute this command from your project folder.

   npm run dev

   This starts the LightNet development server.
2. Open a new Terminal at the same location and execute:

   npx decap-server

   This starts an application that enables Decap CMS to access your file system.
3. Navigate your browser to localhost:4321/admin. You should see the Administration UI showing a list of media items.

Accessing a Git Host

The Administration UI also supports online editing of a site’s content. This is implemented by connecting it to a git host like GitLab or GitHub. From the online Administration UI all changes will be applied using git commits over the git host’s web API. Authentication also is handled by the git host. You can use the git host to manage permissions.

This architecture brings several advantages:

• No need to deploy and maintain a running server backend API.
• Security is handled by the git host (with support for 2-Factor-Authentication).
• Git history enables rollbacks and gives overview what has changed.
• Git repositories can be free of charge.

LightNet supports GitHub and GitLab as git hosts. We highly recommend using GitLab as it supports Authentication from the user’s browser.

Note

If you need to use GitHub as your git host, please notice: GitHub repositories only support server side authentication. This means you will need to configure a backend that forwards the authentication request. See the Decap CMS instructions on how to connect GitHub repositories.

Connect to GitLab

To connect your Administration UI to a GitLab repository, follow these steps.

1. Host repository on GitLab: Make sure your LightNet site is hosted on GitLab. If this is not the case, check the guide on hosting on how to setup a GitLab repository for your project.
2. Open group settings: On GitLab.com navigate to Groups and select the group that hosts the repository. Open the Settings of this group.
3. Add new Application: Open the Application settings and start to Add a new Application.
4. Configure Application: In the Add new Application dialog:
   • Name: Choose a name for the Application e.g. your website name. This is used to name the new application on the GitLab interface. It has no further effect.
   • Redirect URI: Give the final address of your LightNet site followed by your admin path (the default is /admin/) e.g. https://your-library.com/admin/. ⚠️ Don’t forget the trailing slash! ⚠️
   • Confidential: Unselect this option.
   • Scopes: Select the api scope.
5. Save Application ID: Save the new Application. GitLab presents you with an Application ID. Copy and store this ID for later usage.
6. Open project configuration: Go back to your text editor with the project folder and open astro.config.mjs.
7. Adjust decapAdmin integration: Add the backend config for your repository

   astro.config.mjs

   // ...
   export default defineConfig({
     integrations: [
       // ...
       lightnetDecapAdmin({
           languages: languages,
           backend: {
               name: "gitlab",
               repo: "<Group>/<Repository Name>",
               appId: "<Application ID>",
           },
       })
     ]
   });

   Make sure to set repo with the GitLab path of your repository. Set the appId to the Application ID you have copied in step 5.
8. Use the Administration UI: After hosting your site online, open your website on /admin. Press the Login Button and allow LightNet to access your GitLab account. You now can edit your media items online 🎉. If another person needs access to the Administration UI, add their account to the GitLab group.

Note

Even when you have configured a GitLab backend, your local development server always connects to a local decap server (started by npx decap-server).

Reference

You can pass the following options to the lightnetDecapAdmin integration inside astro.config.mjs:

astro.config.mjs

import lightnet from "lightnet";
import lightnetDecapAdmin from "@lightnet/decap-admin";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
    lightnet({...})
    lightnetDecapAdmin({
      /* add config here */
    }),
  ],
});

languages

type: array
example: [{ code: "en", label: "English", isDefaultSiteLanguage: true }]
required: true

The content languages of the site. Use the same languages as in the lightnet integration. We recommend creating a shared variable that is used for both integrations. See the global configuration reference for more information on the languages structure.

path

type: string
example: "admin"
required: false
default: "admin"

The path on which the Administration UI is available on your site. Change this path for obfuscation of your git host connection.

imagesFolder

type: string
example: "images"
required: false
default: "images"

The name of the cover images folder next to your media item files. Change this if you want to use a different name for the images folder. For example if your images are stored inside a folder src/content/media/covers, you can set this to "covers".

maxFileSize

type: number
example: 15
required: false
default: 25

The maximum file size in megabytes allowed to be uploaded. Default is 25 MB, this aligns with Cloudflare’s maximum file size.

backend

type: object
example: { name: "gitlab", repo: "your-org/your-site", appId: "12345abcd" }
required: false

This configures the git host that your Administration UI is connected to. Currently we support GitLab and GitHub backends. The configuration directly maps (replacing camelCase with snake_case) to the Decap CMS GitHub or GitLab backend configuration.

Caution

We highly recommend using the GitLab backend for LightNet sites.

backend: "gitlab"

GitLab backend configuration has these options:

• name: "gitlab" (required) selecting GitLab as backend.
• repo: string (required) the GitLab repository path of your site.
• appId: string Application ID from the site’s GitLab settings.
• branch: string the branch that is used for the Administration UI. Default is "main".
• authType: "pkce" the authentication type to use. Default and only supported option is "pkce".

backend: "github"

GitHub backend configuration has this options:

• name: "github" (required) selecting GitHub as backend.
• repo: string (required) the GitHub repository path of your site.
• branch: string the branch that is used for the Administration UI. Default is "main".
• baseUrl: string the URL of your service doing the authentication request.

Note

GitHub does not support the PKCE authentication type. This means that you need an authentication server to handle the authentication request. This is why we recommend using the GitLab backend for LightNet sites.

See the Decap CMS documentation for more information on how to create an authentication server for GitHub.