docs: clarify byte-preserving behavior of config:set --encoded

The canonical encode pipeline `echo "value" | base64` silently appends `\n` to the value, which round-trips through base64 and ends up stored in the env. Document that decoded values are stored byte-for-byte, recommend `printf '%s'` or `echo -n` for short inline values, and show `cat | base64 -w 0` for files. Adds a bats test asserting all four encoding patterns produce the expected stored bytes.

Closes #8647.

docs/configuration/environment-variables.md

@@ -42,6 +42,19 @@ Dokku can also read base64 encoded values. That's the easiest way to set a value
 dokku config:set --encoded node-js-app KEY="$(base64 -w 0 ~/.ssh/id_rsa)"
 ```
 
+Decoded values are stored byte-for-byte exactly as they were encoded. Be aware that `echo "value" | base64` appends a trailing `\n` before encoding because `echo` always adds a newline, and that newline becomes part of the stored value. This is rarely what you want for short inline values - use `printf '%s'` or `echo -n` instead:
+
+```shell
+dokku config:set --encoded node-js-app KEY="$(printf '%s' "myvalue" | base64 -w 0)"
+dokku config:set --encoded node-js-app KEY="$(echo -n "myvalue" | base64 -w 0)"
+```
+
+For multi-line values from a file (such as an SSH private key), `cat` and `base64 -w 0` preserve the file contents exactly:
+
+```shell
+dokku config:set --encoded node-js-app KEY="$(cat ~/.ssh/id_rsa | base64 -w 0)"
+```
+
 When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the `--no-restart` flag:
 
 ```shell

tests/unit/config.bats

@@ -399,6 +399,57 @@ teardown() {
   assert_output "hello world"
 }
 
+@test "(config) config:set --encoded preserves decoded bytes" {
+  local encoded_echo encoded_printf encoded_echo_n encoded_cat tmpfile
+  encoded_echo="$(echo "myvalue" | base64 -w 0)"
+  encoded_printf="$(printf '%s' "myvalue" | base64 -w 0)"
+  encoded_echo_n="$(echo -n "myvalue" | base64 -w 0)"
+  tmpfile="$(mktemp)"
+  printf 'filecontent' > "$tmpfile"
+  encoded_cat="$(cat "$tmpfile" | base64 -w 0)"
+  rm -f "$tmpfile"
+
+  run /bin/bash -c "dokku config:set --encoded --no-restart $TEST_APP test_echo=$encoded_echo"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku config:get $TEST_APP test_echo | wc -c"
+  echo "output: $output"
+  echo "status: $status"
+  assert_output "9"
+
+  run /bin/bash -c "dokku config:set --encoded --no-restart $TEST_APP test_printf=$encoded_printf"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku config:get $TEST_APP test_printf | wc -c"
+  echo "output: $output"
+  echo "status: $status"
+  assert_output "8"
+
+  run /bin/bash -c "dokku config:set --encoded --no-restart $TEST_APP test_echo_n=$encoded_echo_n"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku config:get $TEST_APP test_echo_n | wc -c"
+  echo "output: $output"
+  echo "status: $status"
+  assert_output "8"
+
+  run /bin/bash -c "dokku config:set --encoded --no-restart $TEST_APP test_cat=$encoded_cat"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku config:get $TEST_APP test_cat | wc -c"
+  echo "output: $output"
+  echo "status: $status"
+  assert_output "12"
+}
+
 @test "(config) config:clear" {
   run ssh "dokku@$DOKKU_DOMAIN" config:set $TEST_APP test_var=true test_var2=\"hello world\" test_var3=\"with\\nnewline\"
   echo "output: $output"