{"id":16674135,"url":"https://github.com/byrnedo/lurch","last_synced_at":"2025-04-09T20:07:11.841Z","repository":{"id":147429826,"uuid":"144481717","full_name":"byrnedo/lurch","owner":"byrnedo","description":"No oil painting but it does serve","archived":false,"fork":false,"pushed_at":"2023-05-15T06:14:05.000Z","size":110,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T20:07:05.789Z","etag":null,"topics":["docker","gomplate","https","letsencrypt","lua","nginx","nginx-proxy","openresty","proxy","reverse-proxy","ssl"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byrnedo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-12T16:14:43.000Z","updated_at":"2024-10-14T02:10:07.000Z","dependencies_parsed_at":"2023-07-09T09:32:01.573Z","dependency_job_id":null,"html_url":"https://github.com/byrnedo/lurch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Flurch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Flurch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Flurch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Flurch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byrnedo","download_url":"https://codeload.github.com/byrnedo/lurch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","gomplate","https","letsencrypt","lua","nginx","nginx-proxy","openresty","proxy","reverse-proxy","ssl"],"created_at":"2024-10-12T12:29:24.951Z","updated_at":"2025-04-09T20:07:11.833Z","avatar_url":"https://github.com/byrnedo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Lurch\n\n![main](https://github.com/byrnedo/lurch/actions/workflows/docker-image.yml/badge.svg?branch=main)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./lurch.jpg\" alt=\"Lurch\" width=\"200\"\u003e\n \u003c/p\u003e\n\n\nOpenresty proxy with following features:\n\n- LetsEncrypt HTTPS\n- SSO via nginx auth requests\n- Simple static site hosting (with optional path proxying)\n- Dynamic config updates via Gomplate remote datasources\n\nDocker image available on [docker hub](https://hub.docker.com/r/byrnedo/lurch).\n\n### Config\n\nThe nginx config is generated from the yaml structure using [Gomplate.](https://docs.gomplate.ca)\n\nGomplate supports many kinds of [datasources](https://docs.gomplate.ca/datasources/) ( local file, remote file over\nhttp, git, you name it!).\n\nBy default the proxy expects the config file at `/etc/lurch/apps.yaml`.\n\nThis can be modified with env:\n\n- APPS_CONFIG_PATH\n\nAlternatively the config can be passed directly as env with:\n\n- APPS_CONFIG_YAML\n\nThe config looks like this:\n\n```yaml\n---\nservices:\n  - name: my-service\n    subdomains:\n      - name: www\n        enabled: 'true'\n        enableClientCerts: false\n        enableSsl: true\n        baseUrl: local.foo.bar\n    origin:\n      type: remote\n      port: 9111\n      host: app.upstream.com\n```\n\nSee [test/apps.yaml](test/apps.yaml) to see examples\n\n### Reloading\n\nSending a SIGHUP to the container will rebuild the template and reload openresty.\n\n### YAML Spec\n\n**An app can have multiple subdomains**\n\nTop level options\n\n\n| Service options        | Required | Default | Description                                |\n|------------------------|----------|---------|--------------------------------------------|\n| `workerConnections`    | false   |   1024   | No of worker connections                   |\n| `proxyReadTimeout`     | false   |    120   | Read timeout to upstream                   |\n| `proxySendTimeout`     | false   |    120   | Send timeout to upstream                   |\n| `sendTimeout`          | false   |    120   | Send timeout                               |\n| `readTimeout`          | false   |    120   | Read timeout                               |\n| `authRequestRedirect`  | false   |          | Where to redirect to if auth request fails |\n| `authRequestUpstream`  | false   |          | Where to send auth requests to             |\n| `authRequestCookie`    | false   |          | Name of cookie to take bearer token from   |\n| `letsEncrypt.endpoint` | false   |          | Endpoint for letsencrypt                   |\n| `resolver`             | false   |          | DNS resolver ip                            |\n\n`service` options\n\n|Service options      |Required|Default|Description                                      |\n|---------------------|--------|-------|-------------------------------------------------|\n|`name`               |true    |       |The service name                                 |\n|`subdomains`         |true    |       |The subdomains for the service                   |\n|`origin`             |true    |       |The origin settings for the service            |\n\n`subdomain` options explained\n\n|Subdomain options    |Required|Default|Description                                      |\n|---------------------|--------|-------|-------------------------------------------------|\n|`name`               |true    |       |The subdommain                                   |\n|`enabled`            |true    |       |Whether or not the domain is visible             |\n|`enableSsl`          |true    |       |Whether or not to apply ssl server side          |\n|`enableLetsEncrypt`  |false   |false  |Whether or not to apply auto ssl                 |\n|`enableSso`          |false   |false  |Whether or not to shield with single-sign-on     |\n|`enableClientCerts`  |true    |       |Whether or not to require client ssl cert as well|\n|`baseUrl`            |true    |       |Base domain for the sub domain                   |\n|`port`               |false   |443    |The port to listen on publicly for this domain   |\n|`clientMaxBodySize`  |false   |20m    |Max upload body size                             |\n\n`origin` options\n\nIf `origin.type = \"remote\"`\n\n|Remote options      |Required|Default|Description                                     |\n|--------------------|--------|-------|------------------------------------------------|\n|`host`              |true    |       |The host to proxy to                            |\n|`port`              |true    |       |The port to proxy to                            |\n\nIf `origin.type = \"local\"`\n\n|Local options      |Required|Default|Description                                     |\n|-------------------|--------|-------|------------------------------------------------|\n|`root`             |true    |       |The root dir where the files are hosted         |  \n|`errorPages`       |false   |       |Error pages config                              |\n|`pathRules`        |false   |       |Array of pathRules                              |\n\n`pathRules` options explained\n\n|Path Rules options    |Required|Default|Description                                     |\n|----------------------|--------|-------|------------------------------------------------|\n|`type`                |true    |       |One of [ prefix ]                               |\n|`path`                |true    |       |The url path to apply the rule to               |\n|`stripPath`           |false   |       |Strip the `path` value when proxying requests   |\n|`origin`              |true    |       |Origin object                                   |\n\nExample yaml:\n\n```yaml\ntype: prefix\npath: \"/api/\"\nstripPath: true\norigin:\n  type: remote\n  host: nginx-api.web\n  port: 80\n```\n\n`errorPages` options explained\n\nThis is an object where keys are the http status code.\nEach status code key value is an object with one property `file`.\n\n```yaml\n'404':\n  file: 404.html\n```\n\nNOTE: A subdomain of 'www' also will be available at 'foo.bar' or whatever the base-url is set to.\n\n## Examples\n\n### Static Site Which Proxies /api to Upstream\n\n```yaml\n---\nservices:\n  - name: static\n    subdomains:\n      - name: static\n        enabled: 'true'\n        baseUrl: test.com\n        enableSsl: false\n        port: 80\n    origin:\n      type: local\n      root: \"/data/static/html\"\n      fallbacks:\n        - \"/index.html;\"\n      errorPages:\n        '404':\n          file: \"/404.html\"\n      pathRules:\n        - type: prefix\n          path: \"/api/\"\n          stripPath: true\n          origin:\n            type: remote\n            host: backend.web\n            port: 80\n```\n\n## Error pages\n\nThe default error page can be overridden by changing the template file:\n`/etc/lurch/error.html`.\nNote that the syntax in error.html is for [resty.template](https://github.com/bungle/lua-resty-template#template-syntax), not golang templating\nCheck [lua/error_page.lua](./lua/error_page.lua).\n\n# SSL Defaults\n\nA default certificate needs to be supplied, even when using letsencrypt (in case issuance fails).\n\nLurch generates a self-signed one for you automatically, but should you need to add your own, lurch expects\na `server.crt` and `server.key` and placed in `/usr/local/openresty/nginx/ssl/\u003cbaseUrl\u003e/`.\n\nFYI: A `subdomain` with no `port` will default to 443\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrnedo%2Flurch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyrnedo%2Flurch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrnedo%2Flurch/lists"}