README.md 2.39 KB
Newer Older
Michał "rysiek" Woźniak's avatar
Michał "rysiek" Woźniak committed
1
2
# nginx-config-tools

Michał Woźniak's avatar
Michał Woźniak committed
3
4
Tools for working with `nginx.conf`.

5
6
7
## Usage

```
8
9
10
11
nginx-conf-flatten <mode> <input_file> <output_file|output_directory>
```

Modes are:
Michał Woźniak's avatar
Michał Woźniak committed
12
13
14

 - `flatten`:  
   flatten an nginx config file by inlining all includes recursively,
15
   save to `<output_file>` (or to standard output if <output_file> not given)
16
        
Michał Woźniak's avatar
Michał Woźniak committed
17
18
19
 - `clean-directory`:  
   generate a cleaned nginx config directory, containing only the files that
   are included from the input file, or files included from those, and so on;
Michał Woźniak's avatar
bugfix    
Michał Woźniak committed
20
   output to `<output_directory>`
21
22
23

Imporant caveats:

Michał Woźniak's avatar
bugfix    
Michał Woźniak committed
24
25
 - `<input_file>` *must* exist (if it doesn't the script will exit with an error)
 - `<output_file>`/`<output_directory>` *must not* exist (if it does, the script will exit with an error)
26

27
28
29
Debug output (a lot of it!) can be enabled by setting the `NGINX_CONF_FLATTEN_DEBUG` environment variable to any non-empty string before running `nginx-conf-flatten`. If enabled, it is printed to `stderr`.

For example:
Michał Woźniak's avatar
Michał Woźniak committed
30
31
32
33

```
NGINX_CONF_FLATTEN_DEBUG='yes-please' nginx-conf-flatten flatten /etc/nginx.conf ./flat.conf
```
34
35
36
37
38
39
40

## Operation

The script creates a temporary directory (`/tmp/nginx-conf-flatten.????`) and works in there.

Once output is ready (either in the form of a single flattened `nginx` config file if mode was `flatten`, or a directory structure if it was `clean-directory`), it is moved to the correct location and the temporary directory is removed.

Michał Woźniak's avatar
bugfix    
Michał Woźniak committed
41
The `flatten` mode makes an honest attempt at keeping indentation sane. This means looking at an `include` line, and indenting the text included from the relevant files by whatever indent was there in the `include` line. This seems to work reasonably well, but if you want the config to be linted and nicely formatted, use a linter and [a formatter](https://github.com/1connect/nginx-config-formatter).
42

Michał Woźniak's avatar
Michał Woźniak committed
43
44
## FAQ

45
 - **Why Bash? (Python|Ruby|Rust|OCaml|COBOL|FORTRAN) would have been so much (harder|better|faster|stronger)?**  
Michał Woźniak's avatar
Michał Woźniak committed
46
47
   Mainly because of compatibility. I expect this tool to be useful in weird server/docker deployments where ability to install dependencies is limited. Bash is available by default in a lot of such environments.
 
48
49
50
 - **This is slow!**  
   And this is not a question!  
   Seriously though, yes, for large `nginx` configs with deeply nested includes it will take several seconds for the script to finish. There are surely ways to optimize this, and yes, if it was written in C it would be faster.