Deploy and operate ¶

Cicadel is an experimental implementation. Passing its tests is not a claim of independent security review or production adoption.

Ask your agent ¶

text

Read https://cicadel.fauzaanu.com/en/dev/howto/operations/index.md.
Prepare this application for [deployment target]. Build its executable and
embedded assets, validate production configuration, and plan migrations and backups.
Keep secrets out of source. Run checks and verify readiness before reporting success.

Configuration and deployment ¶

Settings precedence is typed defaults, project assignments, then environment overrides. Supported environment keys: DATABASE_URL, CICADEL_ADDRESS, CICADEL_DEBUG, CICADEL_ALLOWED_HOSTS (comma-separated exact hosts without ports), and CICADEL_SECURE_COOKIES. Request and pool limits also accept CICADEL_MAX_BODY_BYTES, CICADEL_MAX_OPEN_CONNS, and CICADEL_MAX_IDLE_CONNS as decimal integers. CICADEL_READ_TIMEOUT, CICADEL_WRITE_TIMEOUT, CICADEL_IDLE_TIMEOUT, CICADEL_SHUTDOWN_TIMEOUT, and CICADEL_CONN_MAX_LIFETIME accept Go durations such as 15s or 30m. Invalid values fail validation without printing their contents. settings.LoadWith supports isolated test overrides and copies the allowed-host slice. Production requires debug off, allowed hosts, and secure cookies. Debug does not expose exception details to clients.

Default HTTP limits: 1 MiB body, 15-second header/read timeout, 30-second write timeout, 60-second idle timeout, 10-second shutdown deadline. Database pool: 10 open, 5 idle, 30-minute connection lifetime. Tune these explicitly for workload and database capacity. Handlers must honor request cancellation; the shutdown deadline closes remaining HTTP connections. The application owner closes its database after serving stops.

From your application directory:

export CICADEL_DEBUG=false
export CICADEL_SECURE_COOKIES=true
export CICADEL_ALLOWED_HOSTS=app.example.com
go tool cicadel ui build
go build -trimpath -o bin/server .
bin/server check --deploy --json
# When this application has database migrations:
bin/server migrate
bin/server runserver

Supply DATABASE_URL through your deployment’s secret configuration. Templates and migrations are embedded. Run migrations as a separate deployment step. The example Dockerfile builds a non-root executable image. Set its configuration through your deployment’s secret management, and terminate TLS at a reverse proxy. The framework does not trust Forwarded or X-Forwarded-*. Keep the original allowed Host and configure the proxy’s own header sanitization. Enable HSTS at the HTTPS edge after verifying the domain’s HTTPS behavior.

The articles example uses its sessions table; the accounts starter uses the package-owned accounts_browser_sessions table from migration 002. Sessions are shared across instances, rotate at login, expire after 12 hours or 30 minutes idle, and are invalidated at logout. The accounts browser bridge checks revocation and account availability on each request. Custom user stores must implement their own revocation policy; a session ID alone is not an object permission policy.

Run manage.go check --deploy --json for structured deployment diagnostics. See the foundation guide for custom checks, command flags/statuses and the development rebuild/restart workflow.

Migration safety ¶

Each app retains its version history table, with checksums in the shared migration ledger. Recorded version dependencies determine ordering; the canonical runner uses a shared PostgreSQL advisory lock. Use a direct/session-pooled database connection for migration commands, not transaction-mode PgBouncer. A failed transactional migration rolls back its schema/data changes and does not become applied. Nontransactional migrations can leave partial changes: inspect them and write an explicit repair; never blindly rerun destructive statements.

Take and test database backups before destructive migrations. Prefer expand/backfill/contract changes compatible with the old and new app versions. Goose down migrations may be destructive. Management commands use the checksum-aware runner and provide explicit target rollback with reviewed history and data-loss acknowledgement. Restore a tested backup or apply a reviewed forward repair when necessary. Migration history is not a backup. The shared migration lock serializes execution; separate migrations do not make an entire deployment atomic.

Application security responsibilities ¶

Use parameterized GORM values. SQL fragments, ordering, table names, and raw queries are not made safe by passing arbitrary user strings into them. Select columns explicitly for JSON responses; never serialize password hashes or entire user models.

Apply middleware in this order: session LoadAndSave, CSRF, application authorization. Session-based unsafe requests require csrf_token form fields or X-CSRF-Token headers, including JSON writes. Session pages are Cache-Control: no-store. Authentication rotates the session and CSRF token. Secure cookies require HTTPS except in explicit local development. Add gateway/application rate limits to login and other expensive endpoints before exposing them publicly.

Every object mutation requires a current permission check; the articles example restricts changes by author ID both before rendering and in the SQL update condition. The low-level security.RequireLogin only checks session presence. Accounts-backed routes use browser.RequireLogin with browser.Middleware, which resolves current account availability and revocation. The package supplies reset/change and revocation; verified recovery destinations, invitation policy and MFA integration remain application choices.

The body limit also applies to forms. Multipart handlers must explicitly parse bounded input, remove temporary files, validate content, and use the storage API rather than user-supplied paths. HTML templates escape ordinary strings. Trusted template types bypass escaping and belong only around developer-controlled content. Redirect helpers accept local absolute paths only.

Check before deploying ¶

go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go run manage.go check --deploy --json
go build -trimpath -o bin/server .

Run database integration tests against a disposable PostgreSQL database. Keep secrets in your deployment configuration.

Structured logging configuration ¶

observability.NewLogger(observability.Logging{Output: os.Stderr, Format: "json"}) constructs a standard slog.Logger. Choose text for local development, pass a slog.LevelVar for runtime level changes, and use AddSource for caller locations. Credential attributes are redacted by key before optional ReplaceAttr processing. Use observability.Logger(ctx, logger) for request correlation and pass the same logger to request middleware. Free-form messages and errors must never contain credentials; key redaction cannot sanitize arbitrary message text.

SMTP delivery ¶

mail.Sender{Transport: mail.SMTP{Address: "smtp.example.com:587"}} provides SMTP delivery with mandatory STARTTLS, certificate verification, context cancellation and a default 30-second deadline. Supply credentials through secret configuration. Plain text and HTML bodies are encoded as MIME alternatives when both are present. Delivery errors propagate to the caller; retries must account for uncertain delivery after an SMTP connection failure. The application owns verified recovery destinations. SMTP is not invoked by constructing a sender.

The full supported configuration and output lifecycle are documented in logging, email and authentication. Use those guides for named handlers, error alerts, attachment/envelope behavior, batch counts and generated-starter configuration.