Configuration

Everything a panel is given goes through one struct:

app, err := steward.New(steward.Config{
    DB:        db,
    SecretKey: key,
})

Only DB and SecretKey are required. Every other field has a default that makes a panel work, so this page is a reference rather than a checklist.

Where the values come from

Nothing here is read from the environment by Steward. Config is an ordinary struct built by your code, which is what lets the values come from anywhere — environment variables, a .env file, a secrets manager, a config file, or a mixture. The framework never reaches for os.Getenv on your behalf.

A generated project starts with environment variables, because they need no dependency:

func Build() (*steward.Panel, error) {
    db, err := gorm.Open(mysql.Open(env("DB_DSN", "")), &gorm.Config{})
    if err != nil {
        return nil, fmt.Errorf("opening database: %w", err)
    }
    return steward.New(steward.Config{
        DB:        db,
        SecretKey: []byte(os.Getenv("STEWARD_SECRET")),
        Dev:       os.Getenv("STEWARD_DEV") != "",
    })
}

A .env file

Steward bundles no loader, so pick one — godotenv is the usual choice — and load before building:

_ = godotenv.Load()            // no file in production is not an error
app, err := Build()

Loading a file only sets environment variables, so the code above does not change. Keep .env out of version control and out of the image.

A secrets manager

Build returns an error, so it is a fine place to fetch. Whatever the store — AWS Secrets Manager, Vault, Google Secret Manager — the shape is the same:

func Build(ctx context.Context) (*steward.Panel, error) {
    dsn, err := secrets.Get(ctx, "prod/panel/db")
    if err != nil {
        return nil, fmt.Errorf("reading the database secret: %w", err)
    }
    key, err := secrets.Get(ctx, "prod/panel/session-key")
    if err != nil {
        return nil, fmt.Errorf("reading the session key: %w", err)
    }

    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        return nil, err
    }
    return steward.New(steward.Config{DB: db, SecretKey: []byte(key)})
}

Two things to know before wiring one up:

• Secrets are read once, at boot. Rotating one in the store does not reach a running process; restart it. That is usually what you want for a panel — the alternative is a credential that changes underneath an open session.
• Rotating SecretKey signs everyone out. It is what sessions, CSRF tokens and remember cookies are signed with, so treat it as a planned action rather than routine hygiene.

Required

Dev permits a fixed development key; production must supply a real one. Generate it once and keep it out of the source:

openssl rand -base64 48

Appearance and mounting

Mounting at the root

With no Prefix, the panel is the site: the dashboard is /, a grid is /posts, and anything unmatched is the panel’s own 404 page. That is the default because a panel is usually its own binary, where a prefix buys nothing.

Give it one when the panel shares an origin with something else:

steward.Config{Prefix: "/app"}   // the dashboard moves to /app/

Either way, mount it as a handler and let it own its paths:

mux := http.NewServeMux()
mux.Handle("/api/", myAPI)   // more specific patterns still win
mux.Handle("/", app)

Build links with c.URL("posts") rather than writing the path out, and the prefix stops being something you have to remember.

Storage

Data

Authentication

// "suspended", "not yet activated", "outside permitted hours"
LoginCheck: func(ctx context.Context, u *steward.User) error {
    if suspended(u.ID) {
        return errors.New("This account is suspended.")
    }
    return nil
},

API tokens

Tokens inherit their user’s roles, permissions and policies. Scope an API client by giving it its own account with a restricted role — not the administrator’s.

Integrations

Development

Settings: values that change at runtime

Config is fixed when the process starts. For values someone should be able to change without a deploy — a notice on the login page, a contact address, whether registrations are open — there is a slug→value store with a page of its own under Admin → Settings.

notice, err := app.Setting(ctx, "login-notice")
if err != nil {
    return err
}

if err := app.SetSetting(ctx, "login-notice", "Maintenance on Sunday."); err != nil {
    return err
}

Reads are cached for ten minutes and the form invalidates that entry on save, so a change made in the panel takes effect at once. An absent slug reads as "" rather than an error, which keeps a caller from having to distinguish “not set” from “set to nothing” — but also means a typo in a slug is silent, and so is a setting nobody reads. The page will happily store contct-email; only your code decides that it matters.

Checking it at boot

Verify reports what New and Build could not: a field path that does not resolve, an icon that is not in the sprite, a badge colour outside the set, a disk no Disks entry names, a validation rule that does not exist.

if err := app.Build(); err != nil {
    return err
}
if err := app.Verify(); err != nil {
    return err   // in development; log it in production if you prefer
}

It is worth calling in a test, so a panel that cannot be configured correctly fails the build rather than the first page that renders it.