{"id":13733777,"url":"https://github.com/Scalingo/nginx-buildpack","last_synced_at":"2025-05-08T09:32:52.651Z","repository":{"id":11589733,"uuid":"70073639","full_name":"Scalingo/nginx-buildpack","owner":"Scalingo","description":"Buildpack to deploy a customizable reverse proxy: nginx","archived":false,"fork":false,"pushed_at":"2025-02-24T23:15:51.000Z","size":158,"stargazers_count":6,"open_issues_count":3,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-02-25T00:23:57.264Z","etag":null,"topics":["buildpack","nginx","reverse-proxy","scalingo"],"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/Scalingo.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":"support/lib/deb.lib.sh","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-05T15:30:12.000Z","updated_at":"2025-02-07T14:57:15.000Z","dependencies_parsed_at":"2024-06-12T14:21:21.299Z","dependency_job_id":"2a02f2b7-5da2-41f6-9b03-79dc2bfd061a","html_url":"https://github.com/Scalingo/nginx-buildpack","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/Scalingo%2Fnginx-buildpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scalingo%2Fnginx-buildpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scalingo%2Fnginx-buildpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scalingo%2Fnginx-buildpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Scalingo","download_url":"https://codeload.github.com/Scalingo/nginx-buildpack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253036779,"owners_count":21844280,"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":["buildpack","nginx","reverse-proxy","scalingo"],"created_at":"2024-08-03T03:00:48.841Z","updated_at":"2025-05-08T09:32:52.344Z","avatar_url":"https://github.com/Scalingo.png","language":"Shell","funding_links":[],"categories":["Apps deployable on Scalingo"],"sub_categories":["Apps deployed with buildpacks or other adaptation"],"readme":"# Scalingo Nginx Buildpack\n\nThis buildpack aims at installing a nginx instance and let you configure it at\nyour convenance.\n\n## Defining the Version\n\nBy default we're installing the latest available version of Nginx, but if you\nwant to use a specific version, you can define the environment variable `NGINX_VERSION`\n\n```console\n$ scalingo env-set NGINX_VERSION=1.8.0\n```\n\n## Configuration\n\nThe buildpack is expecting a configuration file at the root of the project\nwhich can be:\n\n* `nginx.conf`: Simple configuration file\n* `nginx.conf.erb`: Template to generate the configuration file\n* `servers.conf.erb`: (optional) Let you configure your nginx instance at the `http` level if required\n\nIf the template is found, it will be rendered as configuration file, it let you use environment\nvariables as in the following examples.\n\n## Discouraged Directives\n\nThe following directives should not be used in you configuration file: `listen`, `access_log`, `error_log` and `server_name`.\n\n## Configuration Examples (`nginx.conf`)\n\n### Split Traffic to 2 APIs\n\n```\nlocation /api/v1 {\n  proxy_pass https://api-v1-app.scalingo.io;\n}\n\nlocation /api/v2 {\n  proxy_pass https://api-v2-app.scalingo.io;\n}\n```\n\nUsing a template to give the names of the app from the environment: `nginx.conf.erb`\n\n```\nlocation /api/v1 {\n  proxy_pass \u003c%= ENV[\"API_V1_BACKEND\"] %\u003e;\n}\n\nlocation /api/v2 {\n  proxy_pass \u003c%= ENV[\"API_V2_BACKEND\"] %\u003e;\n}\n```\n\nUse nginx configuration:\n[https://nginx.org/en/docs/](https://nginx.org/en/docs/) to get details about\nhow to configure your app.\n\n## Configuration Examples (`servers.conf.erb`)\n\nWhen using this configuration method, the previous one won't be considered,\nthey are exclusive.\n\n\n###  Setup throttling with a `limit_req_zone`\n\n```\n# instruction at the http level like\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n\nserver {\n    server_name localhost;\n    listen \u003c%= ENV['PORT'] %\u003e;\n\n    charset utf-8;\n    location {\n        limit_req zone=one burst=5;\n        proxy_pass http://\u003c%= ENV[\"API_V1_BACKEND\"] %\u003e;\n    }\n}\n```\n\n### Multiple domains configuration\n\n```\nserver {\n    server_name front.example.com;\n    listen \u003c%= ENV['PORT'] %\u003e;\n\n    charset utf-8;\n    location {\n        proxy_pass http://\u003c%= ENV[\"FRONT_BACKEND\"] %\u003e;\n    }\n}\n\nserver {\n    server_name api.example.com;\n    listen \u003c%= ENV['PORT'] %\u003e;\n\n    charset utf-8;\n    location {\n        proxy_pass http://\u003c%= ENV[\"API_BACKEND\"] %\u003e;\n    }\n}\n```\n\n## Using Nginx as a WAF with ModSecurity and the OWASP Core Rule Set\n\n### Glossary:\n\n- **WAF**: Web Application Firewall. In a web architecture, this component’s\n  sole role is to filter inbound HTTP traffic by applying pre-defined rules.\n  Some WAF are adaptive and “learn” from patterns, some are static and need to\n  have their rules updated.\n- **ModSecurity**: embedded interpreter for query filtering. It is deployed as\n  a plugin in most web servers (Nginx, Apache, etc…)\\\n  **default version**: `3.0.12`\n- **CRS**: Core Rule Set, it's the set of community rules edited under the\n  OWASP governance that aim to protect against the Top 10 threat for web\n  applications.\\\n  **default version**: `4.4.0`\n\n### How-to deploy and test on Scalingo\n\n- Create an nginx application on Scalingo: [https://doc.scalingo.com/platform/deployment/buildpacks/nginx](https://doc.scalingo.com/platform/deployment/buildpacks/nginx#purpose-of-this-buildpack)\n- Set the environment variable `ENABLE_MODSECURITY=true` and do a redeploy the app. For that create an empty commit and push it to your scalingo remote.\n  Several additional actions will be done in this new deployment:\n  \n    1. ModSecurity and its dependencies will be installed\n    2. Default configuration for ModSecurity will be enabled\n\n- You can test that the CRS are active with the following request:\n    \n    `curl -X INVALID_HTTP_METHOD https://$YOUR_APP_NAME.osc-fr1.scalingo.io -v`\n    \n    You should expect a 403 forbidden answer such as the following:\n    \n    ```bash\n    \u003e INVALID_HTTP_METHOD / HTTP/2\n    \u003e Host: $YOUR_APP_NAME.osc-fr1.scalingo.io\n    \u003e User-Agent: curl/7.64.1\n    \u003e Accept: */*\n    \u003e\n    * Connection state changed (MAX_CONCURRENT_STREAMS == 128)!\n    \u003c HTTP/2 403\n    \u003c date: Tue, 31 May 2022 13:58:46 GMT\n    \u003c content-type: text/html; charset=utf-8\n    \u003c content-length: 146\n    \u003c x-request-id: 343e6a24-640e-499a-9dfe-f5dbb636ef45\n    \u003c strict-transport-security: max-age=31536000\n    \u003c\n    \u003chtml\u003e\n    \u003chead\u003e\u003ctitle\u003e403 Forbidden\u003c/title\u003e\u003c/head\u003e\n    \u003cbody\u003e\n    \u003ccenter\u003e\u003ch1\u003e403 Forbidden\u003c/h1\u003e\u003c/center\u003e\n    \u003chr\u003e\u003ccenter\u003enginx\u003c/center\u003e\n    \u003c/body\u003e\n    \u003c/html\u003e\n    ```\n    \n\n### Updating the CRS rules\n\nYou have to redeploy the application, the latest stable version is downloaded\nduring the build phase. For that, create an empty commit on your repository and\npush it to the scalingo remote.\n\nYou can manually specify the version of CRS you want by setting the variable\n`MODSECURITY_CORE_RULE_SET_VERSION`.\n\n### Updating the ModSecurity version\n\nUpon each deployment, the latest packaged version of modsecurity is used.\nScalingo does not provide any guarantee in term of packagin time after each\nrelease, get in touch with the support if you need a specific version.\n\n### How-to add a custom rule\n\n- Note that, on Scalingo, the root of your repository is deployed on `/app`\n- Create a file to hold all the custom rules you will write and reference it in\n  the nginx config file like so:\n\n```bash\n##############################################\n# in nginx.conf.erb file\n# This file is written in Nginx config language\n\nlocation / {\n    modsecurity on; # Enable ModSecurity on /\n    modsecurity_rules_file /app/custom-rules.modsecurity; # load custom rules file\n    # (...)\n    # The rest of your NGINX config file\n}\n\n##############################################\n# in custom-rules.modsecurity file:\n# This file is written in ModSecurity config language\n\n# CUSTOM RULE id:1234\n# IF query or body parameter contains a parameter named “param1” which contains “test”\n# THEN block the request with a code 403 and log the event\nSecRule ARGS:param1 \"@contains test\" \\\n\t\"id:1234,\\\n\t deny,\\\n\t log,\\\n\t status:403,\\\n\t severity: 'CRITICAL',\\\n\t tag: 'custom-rule',\\\n\t msg: 'this is the log message you will see',\\\n\t logdata: '%{MATCHED_VAR_NAME}=%{MATCHED_VAR}'\"\n```\n\n- Note: The id:1234 is an arbitrary number, you can use any number \u003c 100000 (see: https://coreruleset.org/docs/rules/ruleid/)\n- Note on logdata: See here the list of all variables you can use: https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#variables\n\n### How-to disable a CRS rule\n\nIf you identified a CRS rule that you want to disable, you can use this modsecurity directive to disable it:\n\n```bash\n##############################################\n# in nginx.conf.erb file:\n# This file is written in Nginx config language\n\nlocation / {\n    modsecurity on; # Enable ModSecurity on /\n    modsecurity_rules_file /app/custom-rules.modsecurity; # load custom rules from file\n    # \n    # (...)\n    # Rest of your config file\n}\n\n##############################################\n# in custom-rules.modsecurity file:\n# This file is written in the ModSecurity config language\n\n# Rule 911100 filters unknown HTTP methods. We want to allow exotic HTTP methods\nSecRuleRemoveId 911100\n```\n\n\n### Customizing configuration\n\nA few environment variables can be tweaked in order to configure ModSecurity\n\n* `MODSECURITY_DEBUG_LOG_LEVEL` (default `0`): from `0` to `9` (no log to super verbose)\n* `MODSECURITY_AUDIT_LOG_LEVEL` (default `Off`): Either `On` (all requests), or `RelevantOnly` (requests returning 4XX and 5XX status code)\n\n### Usage with a minimal Stack\n\nCompatibility: `scalingo-22-minimal` only\n\nIf this buildpack is used with a minimal stack , the following dependencies should be installed through the [APT buildpack](https://doc.scalingo.com/platform/deployment/buildpacks/apt):\n\n```\nlibxml2\nlibssl3\nlibpcre3\nlibcurl4\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FScalingo%2Fnginx-buildpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FScalingo%2Fnginx-buildpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FScalingo%2Fnginx-buildpack/lists"}