{"id":21159001,"url":"https://github.com/onecricketeer/gryllidae","last_synced_at":"2025-08-30T07:12:47.708Z","repository":{"id":147421412,"uuid":"260073820","full_name":"OneCricketeer/gryllidae","owner":"OneCricketeer","description":"Opinionated CNCF-based, Docker Compose setup for everything needed to develop a 12factor app","archived":false,"fork":false,"pushed_at":"2022-02-23T22:04:12.000Z","size":1963,"stargazers_count":18,"open_issues_count":14,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-09T13:50:25.264Z","etag":null,"topics":["12-factor","alpine","cloud-native","cncf","docker","docker-compose","golang","instrumentation","microservices","scalability"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause-clear","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneCricketeer.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-04-30T00:09:32.000Z","updated_at":"2024-07-03T04:37:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"dcd082c2-ca01-4229-8065-51643c3f1c3e","html_url":"https://github.com/OneCricketeer/gryllidae","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OneCricketeer/gryllidae","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneCricketeer%2Fgryllidae","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneCricketeer%2Fgryllidae/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneCricketeer%2Fgryllidae/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneCricketeer%2Fgryllidae/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneCricketeer","download_url":"https://codeload.github.com/OneCricketeer/gryllidae/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneCricketeer%2Fgryllidae/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272817236,"owners_count":24997953,"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","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["12-factor","alpine","cloud-native","cncf","docker","docker-compose","golang","instrumentation","microservices","scalability"],"created_at":"2024-11-20T12:41:55.255Z","updated_at":"2025-08-30T07:12:47.687Z","avatar_url":"https://github.com/OneCricketeer.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gryllidae 🦗\n\nAn (opininated) collection of open-source [CNCF](https://cncf.io)-based Docker services that assist in making [12factor](https://12factor.net) applications.\n\n**Future work** - Contribute to [awesome-compose](https://github.com/docker/awesome-compose).\n\n## Table of Contents\n\n- [What you get](#what-you-get)\n- [What you end up with](#what-you-end-up-with)\n- [Getting Started](#getting-started)\n  - [**tl;dr** - How do we run this thing?](#are-we-there-yet)\n- [Extending](#extending)\n- [Troubleshooting](#troubleshooting)\n  - [What is my Docker Compose \"`image`\"?](#what-is-my-image)\n  - [I only have a `Dockerfile`... How do I use this?](#i-only-use-dockerfile-not-maven-what-now)\n  - [The sirens are sounding, and there is no shelter nearby!!!](#what-is-going-wrong-everything-is-falling-apart)\n- [canihazk8s-plz](#extras)?\n\n## What you get\n\n- Service Discovery\n  - [Consul](https://www.consul.io/)\n  - [Registrator](https://github.com/gliderlabs/registrator) (registers Docker containers with Consul as services)\n- [Traefik](https://docs.traefik.io/) for load balancing \u0026 proxy against Consul\u003csup\u003e \\[1\\]\u003c/sup\u003e services\n- [Logspout](https://github.com/gliderlabs/logspout) for [Log collection](https://12factor.net/logs)\n- Metrics - The TIG Stack\n  - [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) (metrics aggregator and pipeline) w/ [DataDog StatsD parser](https://docs.datadoghq.com/developers/dogstatsd/). Refer to [telegraf.conf](conf/telegraf/telegraf.conf) for customization options.\n  - [InfluxDB 1.x](https://www.influxdata.com/) (metrics storage)\n  - [Grafana](https://grafana.com/) (visualization)\n  - **TODO**: Prometheus (PR's welcome) (Telegraf+Influx work fine, though. Telegraf can be configured to scrape Prometheus Metrics)\n- Instrumentation\n  - [Jaeger](https://www.jaegertracing.io/) (distributed tracing)\n\nAny passwords for services are `instrument`. For example, Grafana creds are `admin:instrument`. InfluxDB can be queried using `instrument` as the password.\n\n## What you end up with\n\n### Consul - \u003chttp://localhost:8500\u003e\n\n![consul](doc/img/consul.png)\n\n### Logspout - \u003chttp://localhost:8000/logs\u003e\n\n![logspout](doc/img/logspout-cli.png)\n\n### Traefik - \u003chttp://localhost:8080/dashboard\u003e\n\n![traefik dash](doc/img/traefik-dash.png)\n\n![traefik routes](doc/img/traefik-routes.png)\n\n### Grafana - \u003chttp://localhost:3000\u003e\n\n[Docker dashboard](https://grafana.com/grafana/dashboards/893) - id:`893`\n\n![grafana-docker](doc/img/grafana-docker.png)\n\n[Telegraf dashboard](https://grafana.com/grafana/dashboards/928) - id:`928`, id:`5955`\n\n![grafana-telegraf](doc/img/grafana-telegraf.png)\n\n### Jaeger - \u003chttp://localhost:16686\u003e\n\n![jaeger](doc/img/jaeger.png)\n\n## Getting Started\n\nFirst, download this repo as a ZIP (use the clone button) and extract it as a folder into your project as `.instrument`.\n\nNext, create a Docker network for the components\n\n```sh\ndocker network create instrument_web\n```\n\nThen, if you are using your own `Makefile`, then add the `.instrument` make targets to it\n\n```sh\necho -e '\\ninclude .instrument/targets.mk' \u003e\u003e Makefile\n```\n\nOtherwise, since we've provided `make` targets for you, go ahead and create your own `Makefile`. (Trust me, using one is nicer than memorizing a bunch of Docker commands)\n\nHere's a starting template. Note: `clean` and `install` should be updated to actually do things that are dependent on your own code. Also important: tabs matter when updating a `Makefile`.\n\n```Makefile\ninstall:\n\t@echo \"installing!\"\n\nclean:\n\t@echo \"cleaning!\"\n\ninclude .instrument/targets.mk\n```\n\n\u003e _Alright, alright, alright!_\n\nHaving the infrastructure in place is great, **but** it doesn't help, you, _the application developer_, ensure your app will run on these services.\nIn order to test your _own app_ in this environment, [make your own `docker-compose.yml` file](https://docs.docker.com/compose/compose-file/)\n\nHere's a starting template\n\n```yaml\nversion: '3'\nnetworks:\n  instrument_web:\n    external: true\n\n## Update here\nservices:\n  app:\n    image: containous/whoami  # Replace with your own image\n    ports:  # Update with your own ports\n      - \"8081:80\"\n    networks: ['instrument_web']  # This attaches to the underlying infrastructure network\n    environment:  # Update with your environment\n      FOO: bar\n```\n\nNext, add additional services that specify:\n\n1. Any dependent services (such as [databases](https://github.com/bitnami/bitnami-docker-mariadb/blob/5.5.48/docker-compose.yml), [Kafka](https://github.com/confluentinc/cp-all-in-one/blob/5.5.0-post/cp-all-in-one-community/docker-compose.yml), etc.). Make sure to only copy the internal sections of any `services` block.\n2. (Optional) Any [links to existing, external services](https://docs.docker.com/compose/networking/).\n\n    If you use a remote service over the network, it is up to you to ensure you have the appropriate  network connectivity and firewall options from your machine to those.\n\n   Best practices say to configure such connections via the  `environment` block of Compose or [in-app config wiring](https://12factor.net/config).\n\n3. Externalized secrets\n\n    \u003e ***Note***: For simplicity, Hashicorp Vault is excluded from this stack.\n    \u003e\n    \u003e[Docker Compose can reference a `.env` file](https://docs.docker.com/compose/environment-variables/#the-env-file), should you need local credentials, otherwise use dummy credentials for test databases and such.\n    \u003e\n    \u003e**No one** responsible leaking access credentials in Git repos but yourself._\n\n   ```sh\n   # add to your gitignore\n   echo -e '\\n.env' \u003e\u003e .gitignore\n\n   vim .env\n   ```\n\n### Are we there, yet?\n\nYES!!!\n\nWith all that in place, write in your services (refer to Compose docs above as needed), then get ready to run your application(s)!\n\n```sh\nmake ult-instrument\n```\n\nThis will run until stopped via \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e.\n\n## Extending\n\nHopefully the sevices listed above in [what you get](#what-you-get) are enough. Of course, feel free to mix-and-match with what you think is necessary.\n\n## Troubleshooting\n\n### It doesn't seem to work\n\nMake sure you have the following file structure. Any extra files should include documentation and your local application code + build processes. As mentioned below, this has mostly been tested with Apache Maven, but NPM, or similar tooling could be build around this process.\n\n```txt\n.instrument/\n  conf/\n    grafana/\n    telegraf/\n      telegraf.conf\n  targets.mk\n  docker-compose.yml\nMakefile\ndocker-compose.yml\n```\n\n### What is my `image`?\n\nAre you stuck here?\n\n```yaml\nversion: '3'\nservices:\n   myapp:\n      image: ???\n```\n\nYou can either pull an image directly off [Docker Hub](https://hub.docker.com/), or more commonly, you are in development mode, and you are testing services locally. When an image is local, you can find it with `docker images`. \n\nWhen using any Docker image, the full image name would look like\n\n```sh\n[docker-registry]/[git-org]/[image-name]:[image-version]\n```\n\nWhere each part of a full Docker image reference are:\n\n1. (optional) Docker Registry\n2. (optional) Docker Org/User\n3. (**required**) Docker Image\n4. (**preferred**) Image version\n\nWithout a registry specified, the default is [Docker Hub](https://hub.docker.com/). Use `docker images` to see what images are already downloaded on your local machine. Creating a Docker accont is free, and will let you create your own Docker Org/User where you can push images for others to use. \n\nIf you exclude the image version, then it defaults to `latest`. Best practices of Docker say to always use a defined version. Preferabbly [SemVer](https://semver.org/), by which the `maven-release-plugin` can generate alongside the [Fabric8 `docker-maven-plugin`](https://dmp.fabric8.io/).\n\n\u003e Wait... [***Apache Maven***](https://apache.maven.org)?\n\nYes, you heard me right... Read on.\n\n### I only use Dockerfile, not Maven, what now?\n\nMaven is not only for Java apps! You _will_ need Java installed, but the featureset of Maven outweighs that burden.\n\nAs mentioned, the Fabric8 plugin works fine and has been tested with this project, so refer its documentation for configuration options. In general, it works similarly to the `maven-assembly-plugin` in that it bundles up the final build artifacts into a Docker image.\n\nOther options for building Docker images from Maven include\n\n- (My favorite) : [`jib-maven-plugin` by Google](https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin). Note: This is being merged into the Fabric8 Maven plugins - see [Eclipse JKube](https://github.com/eclipse/jkube).\n- [Spotify Docker Maven Plugin (INACTIVE)](https://github.com/spotify/docker-maven-plugin) - It is stable and functional, but Jib builds more optimized images.\n\nIf you find Gradle, SBT, or another build tool works better for you, feel free to let us know.\n\n### What is going wrong? Everything is falling apart!\n\n*Relax. Breeeaathee.*\n\nIf everything started okay, logs from `stdout` / `stderr` of all the services will be `tail`'d.\nThey can also be followed in another tab (termainal or browser) via `curl http://localhost:8000/logs`. Refer [Logspout documentation](https://github.com/gliderlabs/logspout#including-specific-containers) on performing filters. Of course, `grep` works great here too.\n\nShould a container die, you'll need to debug it.\n\nUseful [commands](https://docs.docker.com/compose/reference/):\n\n- `docker-compose ps` - See what's running (must be ran in same folder as the compose file)\n- `docker-compose logs \u003cname\u003e` - dump the logs of that image. Include `logs -f \u003cname\u003e` to follow the logs.\n- `docker-compose exec \u003cname\u003e bash` - can be used to shell into a container to inspect files and processes like any other terminal session.\n\n## Extras\n\n### I really like Minikube/Minishift and Helm\n\nThey are nice, sure, but Kube YAML is needlessly verbose for a local environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonecricketeer%2Fgryllidae","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonecricketeer%2Fgryllidae","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonecricketeer%2Fgryllidae/lists"}