{"id":13582456,"url":"https://github.com/alexellis/jaas","last_synced_at":"2025-04-06T14:31:03.737Z","repository":{"id":56590488,"uuid":"78229066","full_name":"alexellis/jaas","owner":"alexellis","description":"Run jobs (tasks/one-shot containers) with Docker","archived":true,"fork":false,"pushed_at":"2021-11-04T18:51:27.000Z","size":9695,"stargazers_count":309,"open_issues_count":16,"forks_count":35,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-11-05T22:41:32.177Z","etag":null,"topics":["batch","batch-jobs","cluster","cron","devops","docker-api","docker-swarm","queue","rebuild-indexes","scheduling","services","tasks"],"latest_commit_sha":null,"homepage":"https://www.alexellis.io","language":"Go","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/alexellis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-06T18:30:38.000Z","updated_at":"2024-08-10T12:12:40.000Z","dependencies_parsed_at":"2022-08-15T21:31:15.859Z","dependency_job_id":null,"html_url":"https://github.com/alexellis/jaas","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexellis%2Fjaas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexellis%2Fjaas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexellis%2Fjaas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexellis%2Fjaas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexellis","download_url":"https://codeload.github.com/alexellis/jaas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247495765,"owners_count":20948105,"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":["batch","batch-jobs","cluster","cron","devops","docker-api","docker-swarm","queue","rebuild-indexes","scheduling","services","tasks"],"created_at":"2024-08-01T15:02:43.956Z","updated_at":"2025-04-06T14:30:58.722Z","avatar_url":"https://github.com/alexellis.png","language":"Go","funding_links":["https://github.com/sponsors/alexellis/","https://github.com/sponsors/alexellis"],"categories":["Go"],"sub_categories":[],"readme":"## Notice: archived\n\nThis project is archived, which means there are no plans for further development. If your company is using this in production, contact OpenFaaS Ltd for a commercial license and support. contact@openfaas.com\n\n# Jobs as a Service (JaaS)\n\nRun jobs (tasks/one-shot containers) on Docker Swarm\n\nThis project provides a simple Golang CLI tool that binds to the Docker Swarm API to create an ad-hoc/one-shot Service and then poll until it exits. Service logs can also be retrieved if the Docker daemon API version is greater than 1.29 or if the experimental feature is enabled on the Docker daemon.\n\n[![Build Status](https://travis-ci.org/alexellis/jaas.svg?branch=master)](https://travis-ci.org/alexellis/jaas)\n\n## Motivation and context\n\nFor a blog post covering use-cases for JaaS and more on the portions of the Docker API used see below:\n\n* [Blog: One-shot containers on Docker Swarm](http://blog.alexellis.io/containers-on-swarm/)\n\nUse-cases:\n\n* Use an elastic cluster as your computer\n* Clean up DB indexes\n* Send emails\n* Batch processing\n* Replace cron scripts\n* Run your server maintenance tasks\n* Schedule dev-ops tasks\n\n## Built for developers by developers\n\n\u003ca href=\"https://github.com/sponsors/alexellis/\"\u003e\n\u003cimg alt=\"Sponsor this project\" src=\"https://github.com/alexellis/alexellis/blob/master/sponsor-today.png\" width=\"65%\" height=\"65%\"\u003e\n\u003c/a\u003e\n\n### See also: Serverless\n\nIf you would like to build Serverless applications with Kubernetes or Docker Swarm checkout OpenFaaS:\n\n* [OpenFaaS.com](https://www.openfaas.com)\n\n\u003e The OpenFaaS project has dozens of contributors and thousands of GitHub stars - if you're here because you want to run short-lived functions then try it out today for asynchronous invocations, dashboards, scale-to-zero, and detailed metrics.\n\n## Sponsor this project 🏆\n\nIf you want to see this project developed or are using it commercially, then please [sponsor it here](https://github.com/sponsors/alexellis)\n\n## Get started\n\n### Build and install the code\n\nPre-requisites:\n\n* Docker 1.13 or newer (experimental mode must be enabled if accessing service logs with Docker versions \u003e= 1.13 and \u003c 1.29)\n* [Go 1.9.2 (or Golang container)](https://golang.org/dl/)\n* Enable Swarm Mode (`docker swarm init`)\n\n**Run these commands**\n\n```\n# export GOPATH=$HOME/go\n# go get -d -v github.com/alexellis/jaas\n# cd $GOPATH/src/github.com/alexellis/jaas\n# go install\n# export PATH=$PATH:$GOPATH/bin\n```\n\nNow test `jaas` with `jaas --help`\n\n### Running a task / batch job / one-shot container\n\n* Run your first one-shot container with `jaas run`:\n\n```bash\n# jaas run -r --image alexellis2/cows:latest\n```\n\nThe `-r` flag removes the Swarm service that was used to run your container.\n\n\u003e The exit code from your container will also be available, you can check it with `echo $?`\n\n* Hiding logs\n\nIf you aren't interested in the output logs then run it with the `--show-logs=false` override:\n\n```bash\n# jaas run --image alexellis2/cows:latest --show-logs=false\n```\n\n* Override the command of the container\n\n```bash\n# jaas run --image alpine:3.12 --command \"uname -a\"\n\nPrinting service logs\nw2018-02-06T13:40:00.131678932Z Linux f56d298c4ab9 4.9.75-linuxkit-aufs #1 SMP Tue Jan 9 10:58:17 UTC 2018 x86_64 Linux\n```\n\nYou can also try the example in `examples/gotask`:\n\n\n```bash\n# jaas run -r --image alexellis2/go-task:2020-03-11\n```\n\n* Environment variables\n\nSet environment variables with `--env` or `-e`:\n\n```bash\n# jaas run --image alpine:3.12 --env ENV1=val1 --env ENV2=val2 --command \"env\"\n\nService created: inspiring_elion (j90qjtc14usgps9t60tvogmts)\nID:  j90qjtc14usgps9t60tvogmts  Update at:  2018-07-14 18:02:57.147797437 +0000 UTC\n...........\n\nExit code: 0\nState: complete\n\n\nPrinting service logs\na2018-07-14T18:03:01.465983797Z PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n52018-07-14T18:03:01.466098037Z HOSTNAME=de0b5614fc88\n)2018-07-14T18:03:01.466111965Z ENV1=val1\n)2018-07-14T18:03:01.466122558Z ENV2=val2\n*2018-07-14T18:03:01.466132520Z HOME=/root\n\nRemoving service...\n```\n\n* Removing service after completion\n\nBy default, the service is removed after it completes. To prevent that, run with the `--remove` or `-r` flag set to `false`:\n\n```bash\n# jaas run --image alpine:3.12 --remove=false\n\nService created: zen_hoover (nwf2zey3i387zkx5gp7yjk053)\nID:  nwf2zey3i387zkx5gp7yjk053  Update at:  2018-07-08 20:19:39.320494122 +0000 UTC\n............\n\nExit code: 0\nState: complete\n\n\nPrinting service logs\n\n# docker service ls\n\nID            NAME        MODE        REPLICAS  IMAGE       PORTS\nnwf2zey3i387  zen_hoover  replicated  0/1       alpine:3.7\n```\n\n* Docker authentication for registries\n\nYou can use `jaas` with Docker images in private registries or registries which require authentication.\n\nJust run `docker login` then pass the `--registry` parameter and the encoded string you find in `~/.docker/config.json`.\n\nIf you want to encode a string manually then do the following:\n\n```bash\n$ export auth='{\n    \"username\" : \"myUserName\",\n    \"password\" : \"secret\",\n    \"email\" : \"my@email\",\n    \"serveraddress\" : \"my.reg.domain\"\n  }'\n$ jaas run --registry=\"`echo $auth | base64`\" --image my.reg.domain/hello-world:latest\n```\n\n* Adding secret to service\n\nTo give the service access to an _existing secret_. run with the `--secret` or `-s` flag:\n\n```bash\n$ echo -n \"S3_ACCESS_KEY_HERE\" | docker secret create s3-access-key -\n$ jaas run --image alpine:3.7 --secret s3-access-key --command \"cat /run/secrets/s3-access-key\"\n\nService created: priceless_tesla (f8gheat9f3b8cnnsjy9dth9y7)\nID:  f8gheat9f3b8cnnsjy9dth9y7  Update at:  2018-06-29 16:41:13.723257461 +0000 UTC\n...........\n\nExit code: 0\nState: complete\n\nPrinting service logs\n(2018-06-29T16:41:19.057738088Z S3_ACCESS_KEY_HERE\n\nRemoving service...\n```\n\n_Notes on images_\n\nYou can have a multi-node swarm but make sure whatever image you choose is available in an accessible registry.\n\n\u003e A local image will not need to be pushed to a registry.\n\n* Running jaas in a container\n\nYou can also run `jaas` in a container, but the syntax becomes slightly more verbose:\n\n```\n# docker run -ti -v /var/run/docker.sock:/var/run/docker.sock \\\n  alexellis2/jaas run --image alexellis2/cows:latest\n```\n\n## Real-life example\n\nYou can use `jaas` to get the value of your OpenFaaS gateway password on Docker Swarm. See the [OpenFaaS troubleshooting guide](https://docs.openfaas.com/deployment/troubleshooting/#swarm_1) for the usage.\n\n### Roadmap:\n\nHere are several features / enhancements on the roadmap, please make additional suggestions through Github issues.\n\n* [x] Optionally delete service after fetching exit code/logs\n* [x] Support passing environmental variables\n* [x] Support private registry auth via `-registryAuth` flag\n* [x] Move to cobra flags/args package for CLI\n* [x] Support constraints on where to run tasks\n* [x] Bind-mounting volumes\n* [x] Overriding container command\n* [x] Support optional secrets through CLI flag\n* [x] Support environment variable files with `--env-file`\n\nTodo:\n\n* [ ] Add support for running jobs on Kubernetes\n* [ ] Validation around images which are not in local library\n* [ ] Extract stdout/stderr etc from logs in human readable format similar to `docker logs`\n* [ ] Support incoming [jobs API for Swarm](https://github.com/moby/moby/issues/39447)\n\n### Future:\n\n* When task logs are available in the API this will be used instead of service logs.\n* When event streams are released they will prevent the need to poll continually\n\n## Similar tools\n\n* [OpenFaaS](https://github.com/openfaas/faas) - OpenFaaS runs CLIs, microservices and functions on Kubernetes with built-in asynchronous invocation support\n* [faasd](https://github.com/openfaas/faasd) - faasd is a tiny version of OpenFaaS that runs CLIs and functions on a single node without Kubernetes\n* [kjob](https://github.com/stefanprodan/kjob) by Stefan Prodan appears to be a close variation of jaas, but for Kubernetes.\n* [argo workflows](https://github.com/argoproj/argo) - argo workflows can be used to run tasks and pielines on Kubernetes\n\n## Contributions are welcome\n\nSee the [contributing guide](CONTRIBUTING.md) and do not raise a PR unless you've read it all.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexellis%2Fjaas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexellis%2Fjaas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexellis%2Fjaas/lists"}