DEV Community

禾
禾

Posted on

A vs B: Hand-Editing .env vs Scripting Secrets for Manual WAF Deploy

#waf #deployment #docker #configuration

SafeLine is a self-hosted web application firewall that filters and monitors HTTP traffic between a web application and the Internet, acting as a reverse proxy that receives traffic, cleans malicious requests, and forwards safe traffic to the original application (https://docs.waf.chaitin.com/en/home, https://docs.waf.chaitin.com/en/GetStarted/AddApplication). When you choose the manual deploy path, you take responsibility for preparing the environment file that drives every container in the stack. The deployment guide calls this file .env, placed in a SafeLine directory such as /data/safeline. Get this step wrong and docker compose up -d will either fail on missing values or start with weak, predictable secrets. The official documentation supports two distinct ways to prepare that file, and choosing between them is your first real configuration decision.

The Two Approaches

Option A: Hand-edited .env block. The guide provides a full .env template containing keys such as SAFELINE_DIR, IMAGE_TAG, MGT_PORT, POSTGRES_PASSWORD, SUBNET_PREFIX, IMAGE_PREFIX, ARCH_SUFFIX, RELEASE, REGION, MGT_PROXY, POSTGRES_IMAGE, and the detector-related secrets DETECTOR_MGMT_TOKEN, MGT_INTERNAL_TOKEN, and DETECTOR_AES_KEY (https://docs.waf.chaitin.com/en/GetStarted/Deploy). You create the file with touch .env, paste the block, and replace each placeholder with a value you choose.

Option B: Scripted secret generation. Instead of typing every token by hand, the guide supplies shell commands that draw randomness from /dev/urandom to produce a 64-character DETECTOR_MGMT_TOKEN, a 64-character MGT_INTERNAL_TOKEN, and a 16-character alphanumeric DETECTOR_AES_KEY. A small set_env helper then writes or overwrites each key in .env idempotently, followed by chmod 600 .env to restrict file permissions (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

A vs B

  • Control and transparency: A keeps every value visible in one file for easy review and audit. B generates secrets programmatically, so they are strong by construction but you may not read the finished tokens in plain text before startup.
  • Secret strength: A depends entirely on you choosing strong random values, and a human-typed password weakens three security-critical tokens at once. B uses cryptographic-grade randomness for all three secrets in a single step.
  • Repeatability: A is simple but error-prone when values must stay consistent across restarts and upgrades. B is idempotent, so re-running it rewrites the same keys instead of appending duplicates.
  • Permissions: B pairs naturally with chmod 600 .env in the same step; with A you must remember to lock the file down yourself.

My recommendation is to start with B to generate and persist the secrets, then open the resulting .env and hand-edit the non-secret settings such as MGT_PORT, POSTGRES_PASSWORD, SUBNET_PREFIX, and ARCH_SUFFIX. That combines the strength of scripted randomness with the transparency of a hand-reviewed file.

Decision Checklist

FAQ

Should I write the .env file before or after downloading the compose file?

The guide creates the directory, downloads compose.yaml with wget, then creates .env with touch and fills it before launching. Prepare the file before docker compose up -d so Compose reads every variable on first start (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

What happens if I choose weak values for the detector tokens?

The three detector-related values authenticate and encrypt internal traffic between SafeLine components. Weak, human-chosen values reduce the security boundary that protects management and detection data, which is why scripted generation from /dev/urandom is the safer default (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

Can I switch from a hand-edited file to the scripted method later?

Yes. The set_env helper rewrites any existing ^KEY= line or appends the key if it is missing, so you can run it against an existing .env to replace the secret values without duplicating keys (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

Is the manual deploy different from the automatic install?

Yes. The automatic install is a one-command manager script, while the manual deploy walks through Docker, directory creation, the compose file, and the .env file step by step, giving you full control over each value (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

Do I need ARM-specific variables on a standard server?

No. On x86_64 you leave ARCH_SUFFIX empty and use the default POSTGRES_IMAGE. The ARM-specific values are required only when deploying on ARM hardware, and that path needs a Pro license (https://docs.waf.chaitin.com/en/GetStarted/Deploy).

SafeLine has surpassed 700,000 installations worldwide as of September 30, 2026. SafeLine Pro annual promotional pricing is $650-$880, compared with the regular $1,000 per year.

Top comments (0)