Configuration

Cobblr is configured in two layers. Workspace settings live in the app, under Configuration. Instance settings are environment variables, set in your .env for a self-hosted install. This page covers both.

The Configuration area (in the app)

Configuration opens to five section cards, each listing its settings so you can click straight through:

Section	What you go there to do
Workspace	How this workspace reads: General (including simple mode), Presentation, Units, Templates, Backup & blueprints
Build	What it is made of: Modules, Bundles, Wires, Actions, Fields & forms, Apps
People	Who gets in and what they can do: Members & invites, Permissions, Member portal
Connections	Everything that talks to something outside the workspace: AI, Assistant, Integrations, Scan rules, Devices, Workspace links, Public surfaces, API tokens
System	Checking on it: Activity log, Background queue, Healthcheck, Scripting, OpenAPI

You only see what applies. A setting whose module is switched off is not listed, so no entry leads to a page that cannot work, and settings your role cannot use stay out of your way. Nothing hides behind an "advanced" toggle.

Finding a setting. The search bar matches on synonyms, so "roles" finds Permissions, "swagger" finds OpenAPI, and "octoprint" finds Devices. Inside a settings page, a breadcrumb leads back to the section you came from, and the sidebar lists every setting by section with your page highlighted. On a phone it becomes a Jump to picker.

Things you browse are not settings. Lists you look at, such as locations, files, tags, and saved views, live in the workspace nav rather than under Configuration. Your own profile lives under Your account: Configuration means the workspace, Your account means you.

Environment variables (instance)

The rest of this page is the instance layer: environment variables, set in your .env for a self-hosted install. Most have sensible defaults, and the ones below are the ones you actually reach for. See Self-hosting for the setup and the privacy controls.

Secrets (set these)

Var	What it is
POSTGRES_PASSWORD	Postgres password (match it in DATABASE_URL).
JWT_SECRET	Signs login sessions. Generate with openssl rand -hex 32.
TENANT_CREDS_ENCRYPTION_KEY	Encrypts stored per-workspace credentials. Any strong secret, 16+ characters (e.g. openssl rand -hex 32). Back it up, because losing it is unrecoverable.

Access

Var	Default	Effect
PUBLIC_SIGNUP_ENABLED	off in prod	Allow self-service account signup. Turn on to create your first account, then off.
SUPERADMIN_EMAILS	empty	Comma-separated operator emails that get the admin console.
CORS_ALLOWED_ORIGINS	reflect-any in dev	Allowed web origins in production.

HTTPS (self-host stack)

These configure the bundled TLS proxy in the self-host stack. Pick one TLS mode and set the name you open Cobblr at. Install walks through each mode. This is the variable reference.

Var	Default	Effect
COBBLR_SITE_ADDRESS	required	The name you open Cobblr at, no https://. Your own domain, or a cobblr.<your-tailnet>.ts.net name.
COMPOSE_PROFILES	caddy	The optional services to run, comma separated. caddy runs the bundled TLS proxy. Set it empty to run bare and front the stack with tailscale serve on the host instead. Add autoupdate for the nightly updater (below).
COBBLR_TLS_MODE	internal	Which proxy TLS variant to use: cloudflare, internal (offline CA), tsnet (the proxy joins your tailnet as its own node), or duckdns (retired, but it still works for setups that already run it).
TS_AUTHKEY	empty	tsnet mode only. Leave empty to approve the box in your browser from a one-time link the proxy logs on first start. Set a reusable auth key for a headless join.
COBBLR_ACME_EMAIL	empty	DNS-challenge modes. Optional contact for certificate-expiry notices. Blank is fine, but set it if you want a warning email when a renewal quietly fails.
DUCKDNS_TOKEN	empty	Legacy duckdns mode only.
CLOUDFLARE_API_TOKEN	empty	cloudflare mode: an API token scoped to edit DNS for your zone.

Updates (self-host)

Var	Default	Effect
COMPOSE_PROFILES	caddy	Add autoupdate (for example caddy,autoupdate) to run the updater, which checks for newer images every four hours and restarts only Cobblr's containers. Off unless listed. Updating has the details.
WATCHTOWER_SCHEDULE	0 0 */4 * * *	When the updater checks, as a six-field cron expression with seconds first. The default is every four hours, which needs no hour to be the right one in any particular timezone. 0 0 8 * * * pins it to 08:00 instead.
WATCHTOWER_TZ	UTC	The zone the schedule is read in. Only worth setting alongside a fixed hour, for example Europe/Berlin.
DOCKER_API_VERSION	1.41	The Docker API version the updater asks for. Works on Docker 20.10 and newer. Change it only for an older engine.

Data location (self-host)

Var	Default	Effect
COBBLR_DATA_ROOT	./data	Where every bind mount lives: Postgres, uploaded files, installed modules, and the proxy's TLS certs. Set it once to move all of them together, onto a data disk, a NAS mount, or an appdata root you already define (for example COBBLR_DATA_ROOT=${PATH_TO_APPDATA}/cobblr). Left unset, the mounts stay in ./data beside the compose file, so existing installs are unchanged until you set it and move the folder.

AI

Var	Default	Effect
COBBLR_AI_ENABLED	true	Master switch for built-in AI features. With no provider key nothing is called. Set false to guarantee no outbound AI.

Scanning

Barcode scanning contacts third-party product catalogs. Each provider is switchable and takes its own key. Full table in Self-hosting -> Privacy.

Var	Default	Effect
COBBLR_SCAN_EXTERNAL_LOOKUPS	on	Master switch. false means no third-party barcode calls.
COBBLR_SCAN_GOUPC_API_KEY	empty	Use go-upc's official API.
COBBLR_SCAN_UPCITEMDB_KEY	empty	Use your upcitemdb paid quota.
COBBLR_BIDB_URL	empty	Join the barcode network. Unset means that tier is inert.
COBBLR_BIDB_KEY	empty	Your per-install network key, from account.cobblr.xyz.

Backups

The stack's backup service dumps every database nightly into data/backups/daily/ and keeps a weekly copy on Sundays. See Backups and restore tests.

Var	Default	Effect
BACKUP_DAILY_RETENTION	30	Daily dumps kept before pruning.
BACKUP_WEEKLY_RETENTION	12	Weekly (Sunday) copies kept.
BACKUP_MIN_BYTES	10000	A dump smaller than this is treated as failed and discarded, so an empty file never counts as a good backup.

Marketplace

Var	Default	Effect
COBBLR_EXTENSIONS_URL	unset (instance serves its own catalog)	Point the marketplace at a different catalog index instead of the one your instance builds and serves itself.
COBBLR_ROOT_PUBKEY	empty	Public key used to verify signed extensions.

Housekeeping

Var	Default	Effect
ACTIVITY_LOG_RETENTION_DAYS	unset (keep forever)	Prune activity-log entries older than this many days. Left unset, nothing is ever removed.

Email (optional)

Magic-link and invite delivery. Pick a provider with COBBLR_AUTH_EMAIL_PROVIDER and set its keys (COBBLR_AUTH_SMTP_*, or a Mailgun / Resend / Postmark key). Unset means links are shown in the app instead of emailed. Setup walkthrough: Self-hosting -> Email.

Signup protection (optional)

For an instance whose signup page is reachable from the open internet. All of these are off by default, so nothing changes on a private install.

Var	Default	Effect
COBBLR_CAPTCHA_PROVIDER	unset	Set to turnstile to require a Cloudflare Turnstile captcha on signup. Pair with the two keys below.
COBBLR_CAPTCHA_SECRET	unset	The Turnstile secret key. It stays server-side.
COBBLR_CAPTCHA_SITE_KEY	unset	The Turnstile site key. It is public, delivered to the signup form at runtime, so no key is baked into the web image.
COBBLR_BLOCK_DISPOSABLE_EMAILS	unset	true rejects signups from known disposable-email providers.
COBBLR_REQUIRE_EMAIL_VERIFY	unset	true requires a verified email before login succeeds. Needs a working email provider (above).

These are the variables most instances set. The authoritative list is the .env.example that ships with the self-host stack: every variable the instance reads is declared there with a comment, and it cannot drift from the code the way a hand-kept table can.