{"id":13624736,"url":"https://github.com/ppy/s3-nginx-proxy","last_synced_at":"2025-04-30T19:31:31.481Z","repository":{"id":42676200,"uuid":"336690691","full_name":"ppy/s3-nginx-proxy","owner":"ppy","description":"A lightweight kubernetes deployable nginx-based caching reverse proxy","archived":false,"fork":false,"pushed_at":"2024-12-27T18:30:02.000Z","size":63,"stargazers_count":28,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-06T04:26:12.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ppy.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}},"created_at":"2021-02-07T03:19:42.000Z","updated_at":"2025-04-04T04:35:51.000Z","dependencies_parsed_at":"2023-02-10T20:00:38.332Z","dependency_job_id":null,"html_url":"https://github.com/ppy/s3-nginx-proxy","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppy%2Fs3-nginx-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppy%2Fs3-nginx-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppy%2Fs3-nginx-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppy%2Fs3-nginx-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ppy","download_url":"https://codeload.github.com/ppy/s3-nginx-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251769351,"owners_count":21640887,"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":[],"created_at":"2024-08-01T21:01:45.751Z","updated_at":"2025-04-30T19:31:31.115Z","avatar_url":"https://github.com/ppy.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# s3-nginx-proxy [![dev chat](https://discordapp.com/api/guilds/188630481301012481/widget.png?style=shield)](https://discord.gg/ppy)\n\nA feature-rich Amazon S3 NGINX-based proxy, running in Docker and Kubernetes.\n\n# Features\n\n- Authentication to private buckets\n- Multiple buckets\n- Multiple domains per bucket (with shared cache)\n- Multiple regions\n- Cache duration based on HTTP status\n- Auto-reload after every configuration update (in production too)\n- Single-key cache purge support (using HTTP DELETE)\n- Cloudflare cache purging support\n- Third-party S3 providers support\n- Observability (Prometheus-compatible)\n\n# Usage\n\nRecommended setup is to create an AWS IAM user for each `s3-nginx-proxy` deployment. You should then attach a policy to exclusively grant it the `GetObject` permission on the required buckets, such as:\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Sid\": \"VisualEditor0\",\n      \"Effect\": \"Allow\",\n      \"Action\": \"s3:GetObject\",\n      \"Resource\": \"arn:aws:s3:::thepoon.ppy.sh/*\"\n    }\n  ]\n}\n```\n\nGranting too much permissions may lead to security risks (such as listing the entire bucket content). Be careful!\n\n## Docker\n\nEdit `./data/etc/proxy-config/virtualhosts.json` and `./data/etc/proxy-config/cache.json` to match your desired settings.\nPut your AWS credentials in `./data/etc/proxy-config/secrets.json` (see template in `./data/etc/proxy-config/secrets.json.example`).\nStart the NGINX and config generator containers with `docker-compose up -d`.\n\n## Kubernetes (Helm)\n\nHelm chart is available at https://github.com/ppy/helm-charts/tree/master/osu/s3-nginx-proxy\n\n## Purge configuration\n\nSingle files can be purged from cache using the HTTP `DELETE` method.\n\nBy default, this is enabled to everyone with no authentication.  \nAuthentication can be enabled by setting `purgeAuthorizationKey` in the cache config and using the HTTP `Authorization` header.\n\n### Cloudflare purging\n\nIf Cloudflare is placed in front of s3-nginx-proxy, files can also be purged on Cloudflare's CDN using their API.\n\nIt can be enabled by setting the following variables in the cache config:\n- `purgeCloudflareApiToken` must be a purging-enabled token.  \n  Head to your [account's API Keys](https://dash.cloudflare.com/profile/api-tokens) and create a custom token with the `Zone \u003e Cache Purge \u003e Purge` permission enabled on the desired zone.\n- `purgeCloudflareZoneId` is found on your domain's home page on your Cloudflare dashboard.\n\n## Third-Party S3 Providers\n\nS3 endpoint is computed from the `region` property if you're using Amazon S3. For other providers, `upstream` can be used instead.\n\nFor example, endpoint for DigitalOcean Spaces in region NYC3 is `nyc3.digitaloceanspaces.com`.\n\nBe aware however that you will not be benifitting of the added security of the Amazon S3 very granular permissions (may make your bucket listing public!).\n\n## Observability\n\nA Prometheus-compatible metrics endpoint can be enabled in `metrics.json`.  \nThe following metrics are exposed:\n- `nginx_http_requests_total`: Number of HTTP requests (counter)\n- `nginx_http_request_duration_seconds`: HTTP request latency (histogram)\n- `nginx_http_connections`: Number of HTTP connections (gauge)\n- `nginx_upstream_cache_status`: Number of HTTP requests per upstream cache status (counter)\n\n# Breaking Changes\n\n## 2022.705.0\n\nSecrets have been moved to `./data/etc/proxy-config/secrets.json`, and key for each secret set need to be added to the virtual hosts config (see default `./data/etc/proxy-config/virtualhosts.json`).\n\n# Contributing\n\nThis project is very bare-bones for now; a sort of Minimum Viable Product.  \nPlanned features are the ability to purge cache (both full and specific key), and more configuration options.\n\nContributions can be made via pull requests to this repository. We hope to credit and reward larger contributions via a [bounty system](https://www.bountysource.com/teams/ppy). If you're unsure of what you can help with, check out the [list of open issues](https://github.com/ppy/s3-nginx-proxy/issues).\n\nNote that while we already have certain standards in place, nothing is set in stone. If you have an issue with the way code is structured; with any libraries we are using; with any processes involved with contributing, *please* bring it up. I welcome all feedback so we can make contributing to this project as pain-free as possible.\n\n# Licence\n\nThe osu! client code, framework, and server-side components are licensed under the [MIT licence](https://opensource.org/licenses/MIT). Please see [the licence file](LICENCE) for more information. [tl;dr](https://tldrlegal.com/license/mit-license) you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source.\n\nPlease note that this *does not cover* the usage of the \"osu!\" or \"ppy\" branding in any software, resources, advertising or promotion, as this is protected by trademark law.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppy%2Fs3-nginx-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fppy%2Fs3-nginx-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppy%2Fs3-nginx-proxy/lists"}