update README

This commit is contained in:
Luna 2024-02-16 17:56:06 -03:00
parent 84ff7bd1b6
commit 2c1f155328
2 changed files with 44 additions and 9 deletions

View file

@ -19,8 +19,37 @@ It is an effective replacement to your NGINX installation, but you can have
them coexisting (say, NGINX on port 80, OpenResty being reverse proxied by them coexisting (say, NGINX on port 80, OpenResty being reverse proxied by
NGINX on port 8069, though I wouldn't recommend it in production environments). NGINX on port 8069, though I wouldn't recommend it in production environments).
### how does it work
aproxy has two "hooks" into openresty:
- initialization of the lua vm
- callback for every incoming request
initialization will run validation of your configuration file and check
if it is valid. if it is not you will see logs emitted about what failed
when a request comes in, the scripts declared in the aproxy config file will
be executed sequentially (TODO: ensure order on conf file is chain order).
each script has two types of callbacks: init and request
init callbacks are called when initializing the request, so that the script
may do some conversion or transform the config data into a more performant
in-memory structure.
request callbacks are called on each request, as directed by the main script.
scripts define which paths they want to attach to (via PCRE regex), and so
they can do their own filtering.
look at `scripts/webfinger_allowlist.lua` for an example of how this looks
in a simple form.
### actually installing aproxy ### actually installing aproxy
- get openresty installed
- keep in mind that the specifics of configuring openresty for a double reverse proxy setup aren't included here.
- instructions here are for aproxy's setup in an existing openresty installation
```sh ```sh
mkdir /opt mkdir /opt
git clone https://gitdab.com/luna/aproxy git clone https://gitdab.com/luna/aproxy
@ -28,6 +57,9 @@ git clone https://gitdab.com/luna/aproxy
cd aproxy cd aproxy
mkdir /etc/aproxy mkdir /etc/aproxy
cp ./conf.lua /etc/aproxy/conf.lua cp ./conf.lua /etc/aproxy/conf.lua
# keep in mind the default configuration will lead to your users not being discovered at all,
# it is provided as an example for you to modify.
$EDITOR /etc/aproxy/conf.lua $EDITOR /etc/aproxy/conf.lua
``` ```
@ -51,21 +83,24 @@ http {
You need to do the following: You need to do the following:
- Configure OpenResty package path so that it can call aproxy. - Configure OpenResty package path so that it can call aproxy.
- Insert aproxy as a callback on `location / {` block - insert aproxy hooks for initialization and for callbacks on every request
It'll look something like this: It'll look something like this if you use a single `location /` block:
```nginx ```nginx
http { # set this to 'on' after you have tested that it actually works.
lua_package_path '/opt/?.lua;/opt/aproxy/?.lua;;'; # once you do that, performance will be increased
# while the friction to quickly debug aproxy will also be increased
lua_code_cache off;
lua_package_path '/opt/?.lua;/opt/aproxy/?.lua;;';
init_by_lua_block {
require("aproxy.main").init()
}
http {
server { server {
server_name example.com; server_name example.com;
location / { location / {
# set this to 'on' after you have tested that it actually works.
# once you do that, performance will be increased
# while the friction to quickly debug aproxy will also be increased
lua_code_cache off;
access_by_lua_block { access_by_lua_block {
require("aproxy.main").access() require("aproxy.main").access()
} }

View file

@ -1,10 +1,10 @@
lua_code_cache off;
init_by_lua_block { init_by_lua_block {
require("aproxy.main").init() require("aproxy.main").init()
} }
server { server {
listen 80; listen 80;
lua_code_cache off;
location / { location / {
default_type text/html; default_type text/html;