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.
Add the Administration UI to your project
Section titled “Add the Administration UI to your project”This is how you add the Administration UI to your LightNet project:
-
Add the Integration: Add the LightNet Administration UI integration (
@lightnet/decap-admin
) using Astro’s add command. From your project folder execute:Terminal window npm run astro add @lightnet/decap-adminConfirm the questions with
y
to install required dependencies and add the integration to yourastro.config.mjs
file. -
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.
Run the Administration UI
Section titled “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
Section titled “Accessing your Local File System”Run your Administration UI on your local computer using npm scripts.
- In your Terminal execute this command from your project folder.
This starts the LightNet development server.
Terminal window npm run dev - Open a new Terminal at the same location and execute:
This starts an application that enables Decap CMS to access your file system.
Terminal window npx decap-server - Navigate your browser to localhost:4321/admin. You should see the Administration UI showing a list of media items.
Accessing a Git Host
Section titled “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.
Connect to GitLab
Section titled “Connect to GitLab”To connect your Administration UI to a GitLab repository, follow these steps.
- 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.
- Open group settings: On GitLab.com navigate to
Groups
and select the group that hosts the repository. Open theSettings
of this group. - Add new Application: Open the
Application
settings and start toAdd a new Application
. - 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.
- Save Application ID: Save the new Application. GitLab presents you with an Application ID. Copy and store this ID for later usage.
- Open project configuration: Go back to your text editor with the project folder and open
astro.config.mjs
. - Adjust decapAdmin integration: Add the
backend
config for your repositoryMake sure to setastro.config.mjs // ...export default defineConfig({integrations: [// ...lightnetDecapAdmin({languages: languages,backend: {name: "gitlab",repo: "<Group>/<Repository Name>",appId: "<Application ID>",},})]});repo
with the GitLab path of your repository. Set theappId
to the Application ID you have copied in step 5. - 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.
Reference
Section titled “Reference”You can pass the following options to the lightnetDecapAdmin
integration inside 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
Section titled “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.
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
Section titled “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
Section titled “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
Section titled “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.
backend: "gitlab"
Section titled “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"
Section titled “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.