Skip to content

Configuration Guide

Applies to: All subscriptions

Purpose

Let an administrator find any setting, change it deliberately, and predict the consequence — including the blast radius of a wrong value. A setting nobody understands is a setting nobody dares to change, which is how systems end up frozen in a configuration that no longer fits the business.

Audience

System administrators. Integration developers, for the ingest and write-back settings.

Prerequisites

  • Installation Guide complete
  • Access to the application host for host-level settings, and an administrator account for in-product settings

Steps

Where configuration lives

Complifly configuration sits in three distinct places, with different change procedures. Knowing which layer a setting belongs to is the first step in changing it safely.

Layer Holds Changed by Takes effect
Host environment file Infrastructure and credentials: database, provider, mail, identity, worker tuning Editing the file on the application host On restart
Database configuration Per-GSTIN feature flags, document routing, print settings, policies Administrators in the application On the next request, and within 60 seconds at the latest
Build-time front-end configuration API URL, identity client identifiers Rebuilding and republishing the front end On rebuild, not restart

The most common configuration mistake is changing a host environment setting and expecting it to apply without a restart. The second most common is changing a front-end setting and expecting a restart to be enough — it needs a rebuild.

The pages

Page Covers
Environment Variables Every host-level setting, grouped by subsystem
Domains and URLs The hostname model and why downloads are a separate origin
Feature Flags Per-GSTIN module and automation switches
GSP Configuration Assigning, credentialing and testing a government provider
Email and Notifications Mail transport and who receives what
Document Type Routing Which document types produce an IRN, an e-Way Bill, or both
Print Configuration Templates, branding and the signed QR code

Rules that apply to every setting

Change one thing at a time, and record it. A configuration change with no record is indistinguishable from a defect the next time something misbehaves.

Never hardcode a hostname anywhere. Every URL the product emits — email links, in-product citations, printed references — resolves from configuration, not from a literal string in code. Hardcoding one produces links that work in one environment and silently point at the wrong place in another. See Domains and URLs for exactly which setting controls which link today.

Treat the environment file as a credential store. It holds database and provider credentials. Restrict its permissions, exclude it from source control, and rotate what is in it on a schedule someone owns.

Non-production must never hold production provider credentials. A test document sent with production credentials reaches NIC, consumes a real document number permanently, and cannot be undone. Make the separation structural.

Validation

After any configuration change:

Check Method
The change took effect Observe the specific behaviour it should alter — not merely that the service restarted
The right layer was changed Host settings need a restart; front-end settings need a rebuild; in-product settings need only a moment for the cache
Nothing else changed Run a short document flow after any change to shared infrastructure
It is recorded Change log updated with what, when, why and by whom
It is reflected in every environment that needs it A fix applied only in production is a fix that disappears at the next deployment from a lower environment

Troubleshooting

Symptom Cause Action
A setting changed but nothing happened Host settings require a restart Restart the API, and the worker if the setting affects background work
A front-end setting change had no effect Front-end settings are compiled in Rebuild and republish. See Front-end Deployment
A per-GSTIN setting appears not to apply Brief cache, or set against the wrong GSTIN Wait a minute, then confirm the setting is against the correct registration
Links in emails or PDFs point at the wrong environment A hostname hardcoded somewhere, or domain configuration not set per environment Set the domain configuration per environment. See Domains and URLs
A test document reached the government Non-production environment holding production credentials Treat as an incident. The number is permanently consumed
Configuration lost after a deployment The environment file was overwritten or not preserved Keep it outside the deployed tree, or restore it as part of the deployment procedure
Two environments behave differently with identical code Configuration drift Compare settings between environments; drift accumulates silently and surfaces at the worst time