{"id":22870214,"url":"https://github.com/dadav/gorge","last_synced_at":"2025-05-05T22:13:15.482Z","repository":{"id":226104837,"uuid":"762648864","full_name":"dadav/gorge","owner":"dadav","description":"Puppet-Forge implementation in golang.","archived":false,"fork":false,"pushed_at":"2025-05-05T16:07:25.000Z","size":552,"stargazers_count":12,"open_issues_count":11,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-05T22:13:04.732Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dadav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2024-02-24T09:52:24.000Z","updated_at":"2025-04-22T13:28:08.000Z","dependencies_parsed_at":"2024-06-05T22:33:44.829Z","dependency_job_id":"34fd68fc-6252-40cd-bddc-d71aee302989","html_url":"https://github.com/dadav/gorge","commit_stats":null,"previous_names":["dadav/gorge"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadav%2Fgorge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadav%2Fgorge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadav%2Fgorge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadav%2Fgorge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadav","download_url":"https://codeload.github.com/dadav/gorge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252584331,"owners_count":21771945,"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-12-13T13:14:10.037Z","updated_at":"2025-05-05T22:13:15.473Z","avatar_url":"https://github.com/dadav.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⭐ Gorge\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" width=\"400\" /\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://github.com/dadav/gorge/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/dadav/gorge.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/dadav/gorge?tab=doc\"\u003e\u003cimg src=\"https://godoc.org/github.com/golang/gddo?status.svg\" alt=\"Go Docs\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/dadav/gorge/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/dadav/gorge/build.yml\" alt=\"Build Status\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"GitHub License\" src=\"https://img.shields.io/github/license/dadav/gorge\"\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\nGorge is a go implementation for \u003ca href=\"https://forgeapi.puppet.com\"\u003eforgeapi.puppet.com\u003c/a\u003e\n\u003c/p\u003e\n\n## 🅰️ Status\n\nThis project is still in an very early stage. Contributions are very welcome.\n\n## 🐶 How it works\n\nYou put your modules in the directory `~/.gorge/modules/$module/$release.tar.gz` and gorge will\nsend them to incoming requests from puppet or r10k.\nIf the module is not found locally it will forward the request (if configured) to an upstream\nforge.\nThe results will be cached for one day (if not disabled with `--no-cache`).\nUsually the request results in a module tarball being downloaded. You can set `--import-proxied-releases`\nto automatically import them in your `~/.gorge/modules` directory.\n\n## 🌹 Installation\n\nVia `go install`:\n\n```bash\ngo install github.com/dadav/gorge@latest\n```\n\nVia `tarball`:\n\n```bash\nwget https://github.com/dadav/gorge/releases/download/0.4.2-alpha/gorge_0.4.2-alpha_Linux_x86_64.tar.gz\nsudo tar xf gorge_0.4.2-alpha_Linux_x86_64.tar.gz -C /usr/local/bin/ gorge\n```\n\nVia `container image`:\n\n```bash\npodman run --rm -p 8080:8080 ghcr.io/dadav/gorge:latest\n```\n\nVia various package types:\n\n```bash\n# rpm\nwget https://github.com/dadav/gorge/releases/download/0.4.2-alpha/gorge_0.4.2-alpha_linux_amd64.rpm\nsudo yum localinstall gorge_0.4.2-alpha_linux_amd64.rpm\n\n# deb\nwget https://github.com/dadav/gorge/releases/download/0.4.2-alpha/gorge_0.4.2-alpha_linux_amd64.deb\nsudo apt install gorge_0.4.2-alpha_linux_amd64.deb\n\n# apk\nwget https://github.com/dadav/gorge/releases/download/0.4.2-alpha/gorge_0.4.2-alpha_linux_amd64.apk\nsudo apk add --allow-untrusted gorge_0.4.2-alpha_linux_amd64.apk\n```\n\nVia `helm`:\n\n```bash\ngit clone https://github.com/dadav/gorge.git\ncd gorge/helm/gorge\nhelm install --namespace gorge --create-namespace gorge .\n```\n\n## 💎 Usage\n\n```bash\nRun this command to start serving your own puppet modules.\nYou can also enable one or more fallback proxies to forward the requests to\nwhen you don't have the requested module in your local module\nset yet.\n\nYou can also enable the caching functionality to speed things up.\n\nUsage:\n  gorge serve [flags]\n\nFlags:\n      --api-version string        the forge api version to use (default \"v3\")\n      --backend string            backend to use (default \"filesystem\")\n      --bind string               host to listen to (default \"127.0.0.1\")\n      --cache-max-age int         max number of seconds responses should be cached (default 86400)\n      --cache-prefixes string     url prefixes to cache (default \"/v3/files\")\n      --cache-by-full-request-uri will cache responses by the full request URI (incl. query fragments) instead of only the request path\n      --cors string               allowed cors origins separated by comma (default \"*\")\n      --dev                       enables dev mode\n      --drop-privileges           drops privileges to the given user/group\n      --fallback-proxy string     optional comma separated list of fallback upstream proxy urls\n      --proxy-prefixes string     url prefixes to proxy (default \"/v3\")\n      --group string              give control to this group or gid (requires root)\n  -h, --help                      help for serve\n      --import-proxied-releases   add every proxied modules to local store\n      --jwt-secret string         jwt secret (default \"changeme\")\n      --jwt-token-path string     jwt token path (default \"~/.gorge/token\")\n      --modules-scan-sec int      seconds between scans of directory containing all the modules. (default 0 means only scan at startup)\n      --modulesdir string         directory containing all the modules (default \"~/.gorge/modules\")\n      --no-cache                  disables the caching functionality\n      --port int                  the port to listen to (default 8080)\n      --tls-cert string           path to tls cert file\n      --tls-key string            path to tls key file\n      --ui                        enables the web ui\n      --user string               give control to this user or uid (requires root)\n\nGlobal Flags:\n      --config string   config file (default is $HOME/.gorge.yaml)\n```\n\n### ⛳ Autostart\n\nYou can use [gorge.service](./gorge.service) to integrate gorge into your systemd autostart.\n\nThe required steps are:\n\n```bash\nwget https://raw.githubusercontent.com/dadav/gorge/main/gorge.service\nwget https://raw.githubusercontent.com/dadav/gorge/main/defaults.yaml\nsudo mv gorge.service /etc/systemd/system/gorge.service\nsudo mv defaults.yaml /etc/gorge.yaml\nsudo systemctl daemon-reload\nsudo systemctl enable --now gorge.service\n```\n\nIf you've installed gorge as a package (rpm, deb, apk), the required files should already be there.\n\n## 🐂 Examples\n\n```bash\n# just start with defaults\ngorge serve\n\n# use fallback forge and cache request of modules and files\ngorge serve --fallback-proxy https://forge.puppetlabs.com --cache-prefixes /v3/files,/v3/modules\n\n# first use the internal forge server, then (if failed) the official forge and cache request of modules and files\ngorge serve --fallback-proxy https://internal-forge.example.com,https://forge.puppetlabs.com --cache-prefixes /v3/files,/v3/modules\n```\n\n## 🍰 Configuration\n\nYou can configure gorge in multiple ways.\n\nVia commandline parameters as seen above.\n\nVia file (`$HOME/.config/gorge.yaml` or `./gorge.yaml`):\n\n```yaml\n---\n# Enable basic web ui\nui: false\n# Set uid of process to this users uid\nuser: \"\"\n# Set gid of process to this groups gid\ngroup: \"\"\n# The forge api version to use. Currently only v3 is supported.\napi-version: v3\n# The backend type to use. Currently only filesystem is supported.\nbackend: filesystem\n# Max seconds to keep the cached responses.\ncache-max-age: 86400\n# The host to bind the webservice to.\nbind: 127.0.0.1\n# The prefixes of requests to cache responses from. Multiple entries must be separated by comma.\ncache-prefixes: /v3/files\n# Value of the `Access-Control-Allow-Origin` header.\ncors: \"*\"\n# Enables the dev mode.\ndev: false\n# Drop privileges if running as root (user \u0026 group options must be set)\ndrop-privileges: false\n# List of comma separated upstream forge(s) to use when local requests return 404\nfallback-proxy:\n# The prefixes of requests to send to the proxies. Multiple entries must be separated by comma.\nproxy-prefixes: /v3\n# Import proxied modules into local backend.\nimport-proxied-releases: false\n# Path to local modules.\nmodulesdir: ~/.gorge/modules\n# Seconds between scans of directory containing all the modules\nmodules-scan-sec: 0\n# Disable cache functionality.\nno-cache: false\n# Port to bind the webservice to.\nport: 8080\n# The jwt secret used in the protected endpoint validation\njwt-secret: changeme\n# The path to write the jwt token to\njwt-token-path: ~/.gorge/token\n# Path to tls cert file\ntls-cert: \"\"\n# Path to tls key file\ntls-key: \"\"\n```\n\nVia environment:\n\n```bash\nGORGE_UI=false\nGORGE_USER=\"\"\nGORGE_GROUP=\"\"\nGORGE_API_VERSION=v3\nGORGE_BACKEND=filesystem\nGORGE_BIND=127.0.0.1\nGORGE_CACHE_MAX_AGE=86400\nGORGE_CACHE_PREFIXES=/v3/files\nGORGE_CACHE_BY_FULL_REQUEST_URI=false\nGORGE_CORS=\"*\"\nGORGE_DEV=false\nGORGE_DROP_PRIVILEGES=false\nGORGE_FALLBACK_PROXY=\"\"\nGORGE_PROXY_PREFIXES=/v3\nGORGE_IMPORT_PROXIED_RELEASES=false\nGORGE_MODULESDIR=~/.gorge/modules\nGORGE_MODULES_SCAN_SEC=0\nGORGE_NO_CACHE=false\nGORGE_PORT=8080\nGORGE_JWT_SECRET=changeme\nGORGE_JWT_TOKEN_PATH=~/.gorge/token\nGORGE_TLS_CERT=\"\"\nGORGE_TLS_KEY=\"\"\n```\n\nDirectories are create automatically and the `~` (tilde) in paths are expanded.\n\n## 🐛 Security\n\nSome endpoints are protected and need a valid jwt token. When gorge first starts,\nit will create an admin token in the file `~/.gorge/token`. Use this token\nin the Authorization header like this:\n\n`Authorization: Bearer \u003ctoken\u003e`\n\nIn dev mode these security checks are disabled.\n\n### 💊 Using privileged ports (\u003c1024)\n\nIf you want to use a port smaller 1024, consider using linux capabilities instead\nof running gorge as root.\n\n```bash\n# add capability\nsudo setcap 'cap_net_bind_service=+ep' /usr/bin/gorge\n\n# run gorge\ngorge serve --port 80\n```\n\n### 💧 Dropping privileges\n\nThere is no need to run gorge as root. But if you still want to do it, be sure to\nuse the `--drop-privileges` option combined with `--user` and `--group`. You could\nset these to `www-data`. It will ensure gorge won't keep running as root, after the\nrequired root actions are done.\n\n```bash\nsudo gorge serve --drop-privileges --user www-data --group www-data --port 80\n```\n\n## 🐝 Development\n\nThe code template for `v3` was generated with this command:\n\n```bash\nopenapi-generator generate -c config.yaml -g go-server -i forge_api_v3.json -o pkg/gen/v3\n```\n\n`go-server` does not support the generation of the auth logic, so I had to create a\n[middleware for that](./internal/middleware/auth.go) which uses `jwtauth`.\n\n## 🔑 License\n\n[Apache](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadav%2Fgorge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadav%2Fgorge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadav%2Fgorge/lists"}