README.md 2.85 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

Michał Woźniak's avatar
Michał Woźniak committed
13
14
15
16
 - `tree`:  
   generate a tree of includes and save it to `<output_file>`
   (or print to standard output if `<output_file>` not given)

Michał Woźniak's avatar
Michał Woźniak committed
17
18
 - `flatten`:  
   flatten an nginx config file by inlining all includes recursively,
Michał Woźniak's avatar
Michał Woźniak committed
19
   save to `<output_file>` (or to standard output if `<output_file>` not given)
20
        
Michał Woźniak's avatar
Michał Woźniak committed
21
22
23
 - `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
24
   output to `<output_directory>`
25

Michał Woźniak's avatar
Michał Woźniak committed
26
Important caveats:
27

Michał Woźniak's avatar
bugfix    
Michał Woźniak committed
28
29
 - `<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)
30

31
32
33
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
34
35
36
37

```
NGINX_CONF_FLATTEN_DEBUG='yes-please' nginx-conf-flatten flatten /etc/nginx.conf ./flat.conf
```
38
39
40
41
42
43
44

## 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
Michał Woźniak committed
45
46
No temporary files are created when in `tree` mode.

Michał Woźniak's avatar
bugfix    
Michał Woźniak committed
47
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).
48

Michał Woźniak's avatar
Michał Woźniak committed
49
50
51

### Assumptions:

Michał Woźniak's avatar
Michał Woźniak committed
52
 - The input config is a valid `nginx` config.
Michał Woźniak's avatar
Michał Woźniak committed
53

Michał Woźniak's avatar
Michał Woźniak committed
54
 - Include file paths do not contain spaces.  
Michał Woźniak's avatar
Michał Woźniak committed
55
56
   *(this seems compatible with how nginx handles includes)*

Michał Woźniak's avatar
Michał Woźniak committed
57
58
 - No files are included from above the base directory of the input `nginx`
   config file.
Michał Woźniak's avatar
Michał Woźniak committed
59
60
 

Michał Woźniak's avatar
Michał Woźniak committed
61
62
## FAQ

63
 - **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
64
65
   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.
 
66
67
68
 - **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.