1 | # resty-gitweb |
2 |
|
3 | A git web interface for Lua/OpenResty. |
4 |
|
5 | ## Requirements |
6 |
|
7 | Lua modules (Lua 5.1/LuaJIT 2.1.0/OpenResty LuaJIT compatible, accessible from |
8 | Lua path/cpath): |
9 |
|
10 | | Module | Description | |
11 | | ------ | ----------- | |
12 | | [lyaml](https://github.com/gvvaughan/lyaml) | Reads and parses YAML config files | |
13 | | [puremagic](https://github.com/wbond/puremagic) | MIME type by content, used in blob rendering | |
14 | | [etlua](https://github.com/leafo/etlua) | Embedded Lua templating (for HTML rendering) | |
15 |
|
16 | Other command line tools (installed on system path, accessible from shell): |
17 |
|
18 | | Program | Description | |
19 | | ------- | ----------- | |
20 | | [md4c](https://github.com/mity/md4c) (md2html) | Renders GitHub flavored Markdown | |
21 | | [highlight](http://www.andre-simon.de/doku/highlight/en/highlight.php) | Syntax highlighting in HTML format | |
22 |
|
23 | Linkable Libraries (installed on system path, accessible with LuaJIT's C FFI): |
24 |
|
25 | | Library | Description | |
26 | | ------- | ----------- | |
27 | | [libgit2](https://github.com/libgit2/libgit2) | Dynamically linkable C API for Git | |
28 |
|
29 | ## Using |
30 |
|
31 | 1. Copy this directory with its scripts to a place OpenResty/nginx workers have |
32 | access, such as `/srv/[SITE]/resty-gitweb`. (In reality it doesn't matter |
33 | where, as long as it's accessible.) |
34 |
|
35 | 2. Copy your config file (`resty-gitweb.yaml`) to |
36 | `/etc/[SITE]/resty-gitweb.yaml` (or somewhere else) |
37 |
|
38 | 3. Add the following near the top (`main` context, outside of any blocks) of |
39 | your OpenResty/nginx configuration file: |
40 |
|
41 | ``` |
42 | # resty-gitweb configuration |
43 | env RESTY_GITWEB; # Script won't run without this |
44 | env RESTY_GITWEB_ENV=PROD; # PROD for Production, DEV for Development. DEV by default. |
45 | env RESTY_GITWEB_CONFIG=/etc/[SITE]/resty-gitweb.yaml; # Wherever you put your configuration file |
46 | ``` |
47 |
|
48 | 4. Add the following to the `http` block in your OpenResty/nginx configuration |
49 | file: |
50 |
|
51 | ``` |
52 | lua_package_path "/usr/local/lib/lua/5.1;/srv/[SITE]/resty-gitweb/?.lua;;"; # Add resty-gitweb to your Lua package path |
53 | init_by_lua_file /srv/[SITE]/resty-gitweb/init.lua; # Initialize modules for nginx workers |
54 | ``` |
55 |
|
56 | 5. And in whichever `location` block you wish to serve content: |
57 |
|
58 | ``` |
59 | content_by_lua_file /srv/[SITE]/resty-gitweb/app.lua; |
60 | ``` |
61 |
|
62 | 6. Reload OpenResty/nginx to update config |
63 |
|
64 | ## OpenResty or nginx? |
65 |
|
66 | Note that I use "OpenResty/nginx" instead of just OpenResty; while you can just |
67 | install and use the pre-built |
68 | [OpenResty](https://openresty.org/en/download.html) package, you could actually |
69 | use nginx with only a few added OpenResty components. These are the only |
70 | OpenResty components you actually need to |
71 | [compile](https://www.nginx.com/resources/wiki/extending/compiling/) to use |
72 | this package: |
73 |
|
74 | #### nginx modules |
75 |
|
76 | * [lua-nginx-module](https://github.com/openresty/lua-nginx-module) |
77 |
|
78 | #### Lua libraries |
79 |
|
80 | (run `sudo make all install LUA_VERSION=5.1` for each) |
81 |
|
82 | * [lua-resty-core](https://github.com/openresty/lua-resty-core) |
83 | * [lua-resty-shell](https://github.com/openresty/lua-resty-shell) |
84 | * [lua-resty-lrucache](https://github.com/openresty/lua-resty-lrucache) |
85 | * [lua-resty-signal](https://github.com/openresty/lua-resty-signal) |
86 | * [lua-tablepool](https://github.com/openresty/lua-tablepool) |
87 |
|
88 | Note that lua-nginx-module is the only nginx module that needs to be installed |
89 | with nginx compatibility. The other dependencies just need to be installed on |
90 | your Lua path/cpath. **If you're compiling OpenResty components yourself, you |
91 | may need to build them with OpenResty's |
92 | [branch](https://github.com/openresty/luajit2) of LuaJIT 2.1.0 instead of the |
93 | original.** |
94 |
|
95 | (The full OpenResty package has far more precompiled OpenResty components, so |
96 | you may just want to use that if resty-gitweb isn't the only thing you want to |
97 | use OpenResty for.) |
98 |
|
99 | ## Copyright and Licensing |
100 |
|
101 | This package is copyrighted by [Joshua 'joshuas3' |
102 | Stockin](https://joshstock.in/) and licensed under the [MIT License](LICENSE). |
103 |
|
104 | <<https://joshstock.in>> | josh@joshstock.in | joshuas3#9641 |
105 |
|