Configuration and environment variables

3. Configuration model

3.1 Precedence and the config file

At startup, before clap parses arguments, rustiz loads a dotenv-style file:

1. --config <path>
2. RUSTIZ_CONFIG=<path>
3. ~/.rustiz/config.env (or %USERPROFILE%\.rustiz\config.env)

A file named explicitly by --config or RUSTIZ_CONFIG that does not exist is a fatal error. A missing default file is fine. rustiz init should be pointed at a directory with --dir, not at a not-yet-existing --config file, because the config file is loaded before the command runs.

The file is loaded before clap parses the command line, so PORT, HOST, DATABASE_URL and RUSTIZ_API_KEY written there are visible to the CLI as normal environment variables.

Variables already present in the real environment are not overwritten by the file. An exported variable wins even when it is empty; an empty value is then treated as unset by the application. To change a setting permanently, edit the file; to override it for one run, export it.

The parser accepts:

• KEY=value, optional export KEY=value
• # comments, blank lines
• single quotes (literal), double quotes (\n, \r, \t, \\, \", \')
• bare values, with an inline comment starting at whitespace + #
• duplicate keys: the last one wins
• a UTF-8 BOM at the start

On Unix, rustiz warns at every start if config.env is readable by group or others. Keep it 0600; it contains JWT_SECRET and the organization API key.

3.2 JWT_SECRET

JWT_SECRET is required by serve, worker and mcp; the process exits with JWT_SECRET must be set otherwise. rustiz init generates 64 random alphanumeric characters (about 380 bits).

It is not a session-signing key in this port. It is the passphrase for the AES-256-CBC (OpenSSL EVP_BytesToKey/MD5, byte-compatible with Postiz) layer that encrypts:

• customFields credential JSON (stored in Integration.customInstanceDetails)
• per-instance OAuth client information (customInstanceDetails) for externalUrl/custom-instance providers
• the pending client_info of an externalUrl OAuth state row

It does not encrypt provider access tokens in this port: the Integration.token / Integration.refreshToken columns are plain text in the SQLite file. That includes OAuth access/refresh tokens and some API keys (for example a Moltbook agent key or a Telegram chat id). Protect the database file itself (file permissions, disk encryption, encrypted backups) and treat a copy of it as a credential dump.

Changing or losing JWT_SECRET makes the encrypted custom-credential channels unreadable (Bluesky, WordPress, Lemmy, Listmonk, Medium, Dev.to, Hashnode, Nostr, Mastodon custom instances, etc.), and those channels must be reconnected. OAuth channels keep working because their tokens are not encrypted with this secret, but reconnecting them is the cleanest response to a suspected secret compromise. There is no supported rotation procedure short of reconnecting every affected channel.

3.3 Database URL

SQLite URLs use the sqlx form:

sqlite:///absolute/path/rustiz.db   # absolute (three slashes)
sqlite://relative/rustiz.db         # relative to the process CWD
sqlite::memory:                     # tests only

rustiz init percent-encodes %, ? and # in the path. The database runs in WAL mode, synchronous=NORMAL, foreign keys on, busy timeout 10s, and up to 8 pooled connections. Migrations run automatically on every connection open; rustiz migrate is a convenience that opens the database, migrates and exits.

Because WAL mode writes rustiz.db-wal and rustiz.db-shm, a naive copy of only rustiz.db while the server runs can lose recent transactions. Use sqlite3 ... ".backup ..." or stop the process (§8.3).

4. Complete environment variable reference

This section covers variables read by the core, server, engine and CLI outside individual social providers. Provider credentials (X_API_KEY, FACEBOOK_APP_ID, …) are listed in the master provider table and on each provider page.

4.1 Core

4.2 CLI, MCP and config discovery

With RUSTIZ_URL, the CLI only has the remote REST API. A channels connect OAuth flow cannot watch the server’s callback or detect the new channel; it prints the login URL and returns. Use local database mode with a loopback HTTP FRONTEND_URL if you want the CLI to wait for the login.

4.3 Storage

STORAGE_PROVIDER selects the backend: local (default), cloudflare (Cloudflare R2) or s3 (any S3-compatible store, including MinIO). An invalid value is a fatal error for the upload route and object-storage features.

Local

Cloudflare R2

S3 and S3-compatible stores

Aliases are checked in the order shown; AWS_* wins over S3_* when both are set.

Path-style requests are used (with_virtual_hosted_style_request(false)), which is what MinIO expects. The bucket (or a CDN in front of it) must serve objects publicly; the app does not generate signed URLs.

4.4 Email

Email is optional: with EMAIL_PROVIDER unset or unknown, nothing is sent and the process logs no email provider configured. Notification rows are still written to the database. To actually deliver, you also need both EMAIL_FROM_ADDRESS and EMAIL_FROM_NAME; a missing sender identity or an address without @ is skipped silently (a log line is emitted).

Resend

SMTP / nodemailer

Amazon SES

EMAIL_PROVIDER=ses uses SES’s SMTP interface, not the SES API. If either SES_SMTP_HOST or SES_SMTP_USER is set, the SMTP aliases are used; otherwise the host is derived from the region and credentials fall back to the SES access key pair.

4.5 Short links

Short-link replacement is opt-in per post (shortLink: true). The first configured provider wins in this exact order: Dub → Short.io → Kutt → LinkDrip. With none configured, links are left untouched.

Notes:

• Short.io’s domain is hard-coded as short.io; it has no domain env.
• Short.io statistics use a hard-coded https://statistics.short.io/... host; the link listing reads up to 10 pages of 150 links.
• LinkDrip expansion returns an empty string and its click count is always "0"; only creation is implemented.
• Dub sends the organization id as tenantId.

4.6 HTTP limits and proxies

The limiter is a fixed one-hour window held in process memory. Counts are not shared between replicas and reset on restart. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are sent on allowed responses; a blocked response is 429 with Retry-After. MCP gets a JSON-RPC error body; REST gets {"statusCode":429,"message":"ThrottlerException: Too Many Requests"}.

OAuth credential endpoints have fixed per-IP limits that cannot be changed:

4.7 MCP

subscriptions/listen reads the database, not an in-process bus, so it also sees changes made by a separate rustiz worker. Quick changes between polls collapse into the last one; deletions are not reported.

4.8 Worker, background jobs and media processing

4.9 Upload validation and compatibility

4.10 Provider credentials

Every OAuth/API credential is documented per provider. The shared groups that catch people out:

• Facebook Page + Instagram (Facebook Business) use FACEBOOK_APP_ID / FACEBOOK_APP_SECRET, one Meta app.
• LinkedIn + LinkedIn Page use LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET, one app and one scope set.
• Google My Business accepts GOOGLE_GMB_CLIENT_ID / GOOGLE_GMB_CLIENT_SECRET; a missing GMB id falls back to YOUTUBE_CLIENT_ID, and a missing GMB secret to YOUTUBE_CLIENT_SECRET.

See Documentation overview.