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

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ł 'rysiek' Woźniak's avatar
Michał 'rysiek' Woźniak committed
12

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

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

Michał 'rysiek' Woźniak's avatar
bugfix  
Michał 'rysiek' 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ł 'rysiek' Woźniak's avatar
Michał 'rysiek' 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.

45 46
No temporary files are created when in `tree` mode.

Michał 'rysiek' Woźniak's avatar
bugfix  
Michał 'rysiek' 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

49 50 51

### Assumptions:

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

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

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

61 62
## FAQ

63
 - **Why Bash? (Python|Ruby|Rust|OCaml|COBOL|FORTRAN) would have been so much (harder|better|faster|stronger)?**  
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.