{"id":13564778,"url":"https://github.com/abiosoft/caddy-exec","last_synced_at":"2026-01-12T06:06:42.874Z","repository":{"id":40495222,"uuid":"262767837","full_name":"abiosoft/caddy-exec","owner":"abiosoft","description":"Caddy v2 module for running one-off commands","archived":false,"fork":false,"pushed_at":"2024-09-14T12:47:40.000Z","size":105,"stargazers_count":133,"open_issues_count":8,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-24T17:09:54.448Z","etag":null,"topics":["caddy","caddy-module","caddyserver","command","exec"],"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/abiosoft.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}},"created_at":"2020-05-10T11:02:33.000Z","updated_at":"2024-11-22T17:06:25.000Z","dependencies_parsed_at":"2024-01-16T18:58:09.335Z","dependency_job_id":"d6fcd613-9c08-43a3-9175-d25b4a11f464","html_url":"https://github.com/abiosoft/caddy-exec","commit_stats":null,"previous_names":["abiosoft/caddy-command"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-exec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-exec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-exec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-exec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abiosoft","download_url":"https://codeload.github.com/abiosoft/caddy-exec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"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":["caddy","caddy-module","caddyserver","command","exec"],"created_at":"2024-08-01T13:01:35.727Z","updated_at":"2026-01-12T06:06:42.802Z","avatar_url":"https://github.com/abiosoft.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# caddy-exec\n\nCaddy v2 module for running one-off commands.\n\n## Installation\n\n```\nxcaddy build \\\n    --with github.com/abiosoft/caddy-exec\n```\n\n## Usage\n\nCommands can be configured to be triggered globally during startup/shutdown or by via a route.\n\nThey can also be configured to run in the background or foreground and to be terminated after a timeout.\n\n:warning: startup commands running on foreground will prevent Caddy from starting if they exit with an error.\n\n### Caddyfile\n\n```\nexec [\u003cmatcher\u003e] [\u003ccommand\u003e [\u003cargs...\u003e]] {\n    command     \u003ccommand\u003e [\u003cargs...\u003e]\n    args        \u003cargs...\u003e\n    directory   \u003cdirectory\u003e\n    timeout     \u003ctimeout\u003e\n    log         \u003clog output module\u003e\n    err_log     \u003clog output module\u003e\n    foreground\n    pass_thru\n    startup\n    shutdown\n}\n```\n\n- **matcher** - [Caddyfile matcher](https://caddyserver.com/docs/caddyfile/matchers). When set, this command runs when there is an http request at the current route or the specified matcher. You may leverage other matchers to protect the endpoint.\n- **command** - command to run\n- **args...** - command arguments\n- **directory** - directory to run the command from\n- **timeout** - timeout to terminate the command's process. Default is `10s`. A timeout of `0` runs indefinitely.\n- **log** - [Caddy log output module](https://caddyserver.com/docs/caddyfile/directives/log#output-modules) for standard output log. Defaults to `stderr`.\n- **err_log** - [Caddy log output module](https://caddyserver.com/docs/caddyfile/directives/log#output-modules) for standard error log. Defaults to the value of `log` (standard output log).\n- **foreground** - if present, runs the command in the foreground. For commands at http endpoints, the command will exit before the http request is responded to.\n- **pass_thru** - if present, enables pass-thru mode, which continues to the next HTTP handler in the route instead of responding directly\n- **startup** - if present, run the command at startup. Ignored in routes.\n- **shutdown** - if present, run the command at shutdown. Ignored in routes.\n\n#### Example\n\n`exec` can run at start via the [global](https://caddyserver.com/docs/caddyfile/options) directive.\n\n```\n{\n  exec hugo generate --destination=/home/user/site/public {\n      timeout 0 # don't timeout\n  }\n}\n```\n\n`exec` can be the last action of a route block.\n\n```\nroute /update {\n    ... # other directives e.g. for authentication\n    exec git pull origin master {\n        log file /var/logs/hugo.log\n    }\n}\n```\n\n### API/JSON\n\nAs a top level app for `startup` and `shutdown` commands.\n\n```jsonc\n{\n  \"apps\": {\n    \"http\": { ... },\n    // app configuration\n    \"exec\": {\n      // list of commands\n      \"commands\": [\n        // command configuration\n        {\n          // command to execute\n          \"command\": \"hugo\",\n          // [optional] command arguments\n          \"args\": [\n            \"generate\",\n            \"--destination=/home/user/site/public\"\n          ],\n          // when to run the command, can include 'startup' or 'shutdown'\n          \"at\": [\"startup\"],\n\n          // [optional] directory to run the command from. Default is the current directory.\n          \"directory\": \"\",\n          // [optional] if the command should run on the foreground. Default is false.\n          \"foreground\": false,\n          // [optional] if the middleware should respond directly or pass the request on to the next handler in the route. Default is false.\n          \"pass_thru\": false,\n          // [optional] timeout to terminate the command's process. Default is 10s.\n          \"timeout\": \"10s\",\n          // [optional] log output module config for standard output. Default is `stderr` module.\n          \"log\": {\n            \"output\": \"file\",\n            \"filename\": \"/var/logs/hugo.log\"\n          },\n          // [optional] log output module config for standard error. Default is the value of `log`.\n          \"err_log\": {\n            \"output\": \"stderr\"\n          }\n        }\n      ]\n    }\n  }\n}\n\n```\n\nAs an handler within a route.\n\n```jsonc\n\n{\n  ...\n  \"routes\": [\n    {\n      \"handle\": [\n        // exec configuration for an endpoint route\n        {\n          // required to inform caddy the handler is `exec`\n          \"handler\": \"exec\",\n          // command to execute\n          \"command\": \"git\",\n          // command arguments it's also possible to use \n          // caddy variables like {http.request.uuid}\n          \"args\": [\"pull\", \"origin\", \"master\", \"# {http.request.uuid}\"],\n\n          // [optional] directory to run the command from. Default is the current directory.\n          \"directory\": \"/home/user/site/public\",\n          // [optional] if the command should run on the foreground. Default is false.\n          \"foreground\": true,\n          // [optional] if the middleware should respond directly or pass the request on to the next handler in the route. Default is false.\n          \"pass_thru\": true,\n          // [optional] timeout to terminate the command's process. Default is 10s.\n          \"timeout\": \"5s\",\n          // [optional] log output module config for standard output. Default is `stderr` module.\n          \"log\": {\n            \"output\": \"file\",\n            \"filename\": \"/var/logs/hugo.log\"\n          },\n          // [optional] log output module config for standard error. Default is the value of `log`.\n          \"err_log\": {\n            \"output\": \"stderr\"\n          }\n        }\n      ],\n      \"match\": [\n        {\n          \"path\": [\"/update\"]\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Dynamic Configuration\n\nCaddy supports dynamic zero-downtime configuration reloads and it is possible to modify `exec`'s configurations at runtime.\n\n`exec` intelligently determines when Caddy is starting and shutting down. i.e. startup and shutdown commands do not get triggered during configuration reload, only during Caddy's actual startup and shutdown.\n\n## License\n\nApache 2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-exec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabiosoft%2Fcaddy-exec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-exec/lists"}