nginx
2015-06-30
Parent:68478c1bddde
nginx/README.md
Make nginx kubernetes-ready. We had to update to use a ubuntu-based image to build nginx into, because (and I kid you not) alpine linux straight-up ignores your resolv.conf file, meaning any attempt to use it with kubernetes DNS is doomed to fail. Who thought this was a good idea? So we're using a bloated image instead. Oh well. We also are running a wrapper script instead of nginx directly, so we can inject the JWT_SECRET environment variable based on a kubernetes secret file. We define the secret file (using a placeholder secret, obvs) so that future-Paddy can remember what the hell it looks like, when he inevitably loses the file and needs to sin up a new cluster. Or whatever. Finally, we updated the token expiration error message to be in an errors array, as God (and our API conventions) intended.
| paddy@0 | 1 # OpenResty Docker image |
| paddy@0 | 2 |
| paddy@0 | 3 This is a fork of https://github.com/ficusio/openresty's alpine flavour. |
| paddy@0 | 4 |
| paddy@0 | 5 ### Paths & config |
| paddy@0 | 6 |
| paddy@0 | 7 NginX is configured with `/opt/secondbit/nginx` [prefix path](http://nginx.org/en/docs/configure.html), which means that, by default, it loads configuration from `/opt/secondbit/nginx/conf/nginx.conf` file. The default HTML root path is `/opt/secondbit/nginx/html/`. |
| paddy@0 | 8 |
| paddy@0 | 9 OpenResty bundle includes several useful Lua modules located in `/opt/secondbit/lualib/` directory. This directory is already present in Lua package path, so you don't need to specify it in NginX `lua_package_path` directive. |
| paddy@0 | 10 |
| paddy@0 | 11 The Lua NginX module is built with LuaJIT 2.1, which is also available as stand-alone `lua` binary. |
| paddy@0 | 12 |
| paddy@0 | 13 ### `ONBUILD` hook |
| paddy@0 | 14 |
| paddy@0 | 15 This image uses [`ONBUILD` hook](https://docs.docker.com/reference/builder/#onbuild) that automatically copies all files and subdirectories from the `nginx/` directory located at the root of Docker build context (i.e. next to your `Dockerfile`) into `/opt/secondbit/nginx/`. The minimal configuration needed to get NginX running is the following: |
| paddy@0 | 16 |
| paddy@0 | 17 ``` |
| paddy@0 | 18 project_root/ |
| paddy@0 | 19 ├ nginx/ # all subdirs/files will be copied to /opt/secondbit/nginx/ |
| paddy@0 | 20 | └ conf/ |
| paddy@0 | 21 | └ nginx.conf # your NginX configuration file |
| paddy@0 | 22 └ Dockerfile |
| paddy@0 | 23 ``` |
| paddy@0 | 24 |
| paddy@0 | 25 Dockerfile: |
| paddy@0 | 26 |
| paddy@0 | 27 ``` |
| paddy@0 | 28 FROM secondbit/nginx:latest |
| paddy@0 | 29 EXPOSE 8080 |
| paddy@0 | 30 ``` |
| paddy@0 | 31 |
| paddy@0 | 32 ### Command-line parameters |
| paddy@0 | 33 |
| paddy@0 | 34 NginX is launched with the `nginx -g 'daemon off; error\_log /dev/stderr info; access\_log /dev/stdout;'` command. This means that you should not specify the `daemon` directive in your `nginx.conf` file, because it will lead to NginX config check error (duplicate directive). |
| paddy@0 | 35 |
| paddy@0 | 36 No-daemon mode is needed to allow host OS' service manager, like `systemd`, or [Docker itself](https://docs.docker.com/reference/commandline/cli/#restart-policies) to detect that NginX has exited and restart the container. Otherwise in-container service manager would be required. |
| paddy@0 | 37 |
| paddy@0 | 38 Error log and access log are redirected to `stderr` and `stdout` respectively to simplify debugging and log collection with tools like [progrium/logspout](https://github.com/progrium/logspout). |
| paddy@0 | 39 |
| paddy@0 | 40 If you wish to run it with different command-line options, you can add `CMD` directive to your Dockerfile. It will override the command provided in this image. Another option is to pass a command to `docker run` directly: |
| paddy@0 | 41 |
| paddy@0 | 42 ```text |
| paddy@0 | 43 $ docker run --rm -it --name test secondbit/nginx bash |
| paddy@0 | 44 root@06823698db68:/opt/secondbit/nginx $ ls -l |
| paddy@0 | 45 total 12 |
| paddy@0 | 46 drwxr-xr-x 2 root root 4096 Feb 1 14:48 conf |
| paddy@0 | 47 drwxr-xr-x 2 root root 4096 Feb 1 14:48 html |
| paddy@0 | 48 drwxr-xr-x 2 root root 4096 Feb 1 14:48 sbin |
| paddy@0 | 49 ``` |
| paddy@0 | 50 |
| paddy@0 | 51 ### Usage during development |
| paddy@0 | 52 |
| paddy@0 | 53 To avoid rebuilding your Docker image after each modification of Lua code or NginX config, you can add a simple script that mounts config/content directories to appropriate locations and starts NginX: |
| paddy@0 | 54 |
| paddy@0 | 55 ```bash |
| paddy@0 | 56 #!/usr/bin/env bash |
| paddy@0 | 57 |
| paddy@0 | 58 exec docker run --rm -it \ |
| paddy@0 | 59 --name my-app-dev \ |
| paddy@0 | 60 -v "$(pwd)/nginx/conf":/opt/secondbit/nginx/conf \ |
| paddy@0 | 61 -v "$(pwd)/nginx/lualib":/opt/secondbit/nginx/lualib \ |
| paddy@0 | 62 -p 8080:8080 \ |
| paddy@0 | 63 secondbit/nginx:latest "$@" |
| paddy@0 | 64 |
| paddy@0 | 65 # you may add more -v options to mount another directories, e.g. nginx/html/ |
| paddy@0 | 66 |
| paddy@0 | 67 # do not do -v "$(pwd)/nginx":/opt/secondbit/nginx because it will hide |
| paddy@0 | 68 # the NginX binary located at /opt/secondbit/nginx/sbin/nginx |
| paddy@0 | 69 ``` |
| paddy@0 | 70 |
| paddy@0 | 71 Place it next to your `Dockerfile`, make executable and use during development. You may also want to temporarily disable [Lua code cache](https://github.com/openresty/lua-nginx-module#lua_code_cache) to allow testing code modifications without re-starting NginX. |