Admin panel (orbit)

Nucleus has no built-in admin panel. The admin panel is orbit — a separate, pluggable Go module (github.com/jcsvwinston/orbit) that versions and ships independently of the framework.

This page shows how to add orbit to a Nucleus app, what it gives you, and which pieces remain framework concerns rather than orbit ones.

Why the extraction

The panel is a React and TypeScript single-page app. Bundling it into the framework binary forced every Nucleus application to carry its transitive dependencies, whether or not the app used the panel.

Extracting it keeps the core lightweight and lets the admin evolve on its own schedule, with its own release tags.

Integrating orbit into your app

orbit is a Nucleus extension module distributed as a separate Go module at github.com/jcsvwinston/orbit. Add it to your project with:

go get github.com/jcsvwinston/orbit@latest

Pin a concrete orbit tag for reproducible builds — the current release is listed in orbit's own documentation, which is kept in step with its tags. Since orbit v1.0.0 the public surfaces (the root module and the datasource contract) are frozen for the life of v1.x, enforced by a contract-freeze test in the orbit repo.

Mount it with the standard .Mount() call in main.go:

package main

import (
    "github.com/jcsvwinston/nucleus/pkg/nucleus"
    "github.com/jcsvwinston/orbit"
)

func main() {
    nucleus.New().
        FromConfigFile("nucleus.yml").
        Mount(orbit.Module(orbit.Config{Prefix: "/admin"})).
        Start()
}

orbit is not part of the github.com/jcsvwinston/nucleus module and versions independently. The cluster-telemetry subsystem ships as sibling modules (github.com/jcsvwinston/orbit/proto, github.com/jcsvwinston/orbit/agent, github.com/jcsvwinston/orbit/server); most applications only need the root orbit module for the admin panel.

What orbit provides

• Login page with light/dark theme support.
• Model browser — every registered model becomes a list view with search, filtering, ordering and pagination.
• CRUD UI with form generation from db: and validate: tags.
• Bulk actions with per-row error reporting.
• Import / export — CSV, JSON, SQL, with validation on import.
• Audit log — every CRUD operation is recorded.
• System pulse — Go runtime, DB pool, feature flags, jobs, outbox, cluster nodes.
• Health dashboard — DB / Redis / mail connectivity.
• Migration view — applied vs. pending, with diff hints.
• Job queue inspector — Asynq runtime details.
• File storage browser — works against the configured pkg/storage backend.
• Live traffic inspection — HTTP, SQL, sessions.
• Email stats and deployment info.

Configuration

All orbit configuration lives under modules.orbit.* in nucleus.yml. The admin_* family of config keys that existed in earlier releases has been removed from the framework core (the Configuration reference maps each old key to its replacement); consult orbit's own documentation for its configuration schema.

Authorization and RBAC

The Casbin RBAC enforcer is a core framework feature, not an orbit feature. Configure it with the rbac_policy_file key:

rbac_policy_file: ./rbac_policy.csv

The legacy admin_rbac_policy_file alias was removed in v0.12.0, so rbac_policy_file is now the only key. Renaming it in your configuration is the entire migration.

The enforcer is available to all application code (including orbit) through the Runtime.Authorizer() accessor.

Registering models

Model registration is a core framework concern. Register a model with the application's model registry so that orbit (and other tools) can discover it:

a.Models.Register(&Article{})

App.RegisterModel is the stable method on pkg/app.App.

Multi-tenancy

When multitenant.enabled: true is set, orbit respects the tenant context provided by the framework's request-scope resolver.

Effective-config inspection

The GET /_/config HTTP endpoint that previously shipped with the admin subsystem has been removed from the framework core. Use nucleus config print --effective from the CLI for effective merged configuration inspection:

nucleus config print --effective --config nucleus.yml

See CLI overview → Effective config for the full flag reference.