Autonnel v1.7.0

Configuration

Autonnel configuration reference: the few env vars it reads (DATABASE_URL, ADMIN_DOMAIN, production secrets), plugins in astro.config.mjs, white label.


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, domains and their branding). 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 — Node only. Unless NODE_ENV is development/test, the server runs
# scheduled tasks every 5 minutes by itself; "off" disables that, "on" forces
# it in development.
AUTONNEL_SCHEDULER=off

# 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 routes, storefront hooks and additional admin UI slots. Pass plugin instances through the plugins option in astro.config.mjs:

import autonnel from 'autonnel';
import { cloakingPlugin } from '@autonnel/plugin-cloaking';
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    autonnel({
      plugins: [
        cloakingPlugin(),
      ],
    }),
  ],
});

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

  • @autonnel/plugin-cloaking: rule-based traffic cloaking per page, with a Cloaking menu in the admin sidebar

Ad platform OAuth (Facebook, Google Ads, TikTok), ad account discovery, and ad spend/click reporting are all built into the core under Settings → Ads. They are not a plugin and never require an astro.config.mjs change; see Ads overview.

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

The plugin list passed to plugins is only visible to the build. For plugin hooks, settings panels, background jobs and scheduled tasks to work in the production server, also point pluginsModule at a module that exports the same list as createPlugins(); the server re-registers from it at startup:

// src/plugins.ts
export function createPlugins() {
  return [cloakingPlugin()];
}

// astro.config.mjs
autonnel({
  plugins: createPlugins(),
  pluginsModule: new URL('./src/plugins.ts', import.meta.url),
});

White label

Set whiteLabel: true to remove Autonnel branding from the admin console: the sidebar logo and name, the Autonnel breadcrumb root, the Resources links (Documentation, Changelog), the footer credit, and the · Autonnel suffix in page titles. It is a build-time option, so changing it needs a rebuild.

autonnel({
  whiteLabel: true,
});

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 → Storage (static domain), and each domain can override it under its Storage tab.