Autonnel v0.1.0
Get started

Configuration

Environment variables and plugin configuration for an autonnel install.

Autonnel reads two kinds of configuration at runtime:

  1. Environment variables — DATABASE_URL and a handful of operational settings, read from the process environment or a .env file.
  2. Admin UI settings — everything else (S3 credentials, payment providers, email, ecommerce, LLM, ads, branding, domains). These are stored in the database and edited from Settings.

For a typical install you set DATABASE_URL once, start the server, and configure the rest through the admin UI.

Environment variables

Env holds only operational settings: the database URL, the admin hostname, two production secrets, and a few optional knobs. Everything else has been moved to the admin UI.

# Required — Postgres connection string
DATABASE_URL="postgresql://user:password@host:5432/db"

# Hostname the admin UI is served on (defaults to "localhost" for local dev).
# Set this to your real admin hostname in production. Comma-separated list;
# entries may use '*' as a single-label wildcard ("*.example.com").
ADMIN_DOMAIN="admin.example.com"

# Required in production (any NODE_ENV other than development/test) —
# signs session/checkout cookies. Generate: openssl rand -hex 32
AUTH_SESSION_SECRET="..."

# Required in production — encrypts provider credentials (payment/email/
# ecommerce) at rest in the database. Generate: openssl rand -base64 32
CREDENTIALS_ENCRYPTION_KEY="..."

# Optional — shared secret protecting the HTTP cron endpoints
CRON_KEY="..."

# Optional — log level: debug | info | warn | error (default: info)
LOG_LEVEL=info

# Optional — storefront fallback currency (default: USD)
DEFAULT_CURRENCY=USD

# Optional — Redis cache for Node deployments. Falls back to in-memory when
# unset; Cloudflare Workers deployments use KV instead.
REDIS_URL="redis://..."

DATABASE_URL is the only variable required to boot locally. In production (any NODE_ENV other than development/test) AUTH_SESSION_SECRET and CREDENTIALS_ENCRYPTION_KEY become mandatory — the server fails fast rather than signing cookies with a known fallback or persisting provider secrets in plaintext. Generate each once and keep them stable: rotating AUTH_SESSION_SECRET logs everyone out, and rotating CREDENTIALS_ENCRYPTION_KEY makes previously stored provider credentials unreadable.

Variables that previously had to be set as env vars — LLM keys, OAuth credentials, Google Maps key, S3 credentials, payment provider keys, email transport credentials, ecommerce adapter credentials — are now managed through Settings and stored in the database.

Plugin configuration

Plugins are the supported extension point for autonnel. They add auth providers, OAuth ad flows, and additional admin UI slots. Pass plugin instances through the plugins option in astro.config.mjs:

import autonnel from 'autonnel';
import { oauth2Plugin } from '@autonnel/plugin-oauth2';
import { adsPlugin } from '@autonnel/plugin-ads';
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    autonnel({
      plugins: [
        oauth2Plugin({
          clientId: process.env.OAUTH_CLIENT_ID,
          clientSecret: process.env.OAUTH_CLIENT_SECRET,
          issuerUrl: process.env.OAUTH_ISSUER_URL,
        }),
        adsPlugin({
          facebook: {
            appId: process.env.FB_APP_ID,
            appSecret: process.env.FB_APP_SECRET,
          },
        }),
      ],
    }),
  ],
});

For full plugin option references, see the individual package READMEs:

  • @autonnel/plugin-oauth2 — OAuth / OIDC login, replaces the default username/password screen
  • @autonnel/plugin-ads — OAuth ad platform connections and Google Ads (token-mode ad postbacks are built into the core and do not require this plugin)

Plugins are compile-time. Adding, removing, or reconfiguring a plugin in astro.config.mjs requires a server restart; they are not hot-reloaded.

Storage is required

Before autonnel can upload media (page imports, AI image generation, manual asset uploads), you must configure Settings → Storage with S3-compatible credentials. Until configured, the admin shows a banner and any upload attempt throws StorageNotConfiguredError.

Caveats

  • Do not edit database rows directly to change settings. The admin UI applies validation and encryption where needed (e.g. credential fields). Direct DB edits bypass that.
  • The static CDN domain is not an env var. It is configured in Settings → Domains via the primary domain field.