{"id":13443004,"url":"https://github.com/smebberson/docker-alpine","last_synced_at":"2025-04-05T00:08:36.674Z","repository":{"id":30822185,"uuid":"34379480","full_name":"smebberson/docker-alpine","owner":"smebberson","description":"Docker containers running Alpine Linux and s6 for process management. Solid, reliable containers.","archived":false,"fork":false,"pushed_at":"2022-05-20T12:43:07.000Z","size":672,"stargazers_count":593,"open_issues_count":28,"forks_count":180,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-03-28T23:07:00.931Z","etag":null,"topics":["alpine-linux","apache","confd","consul","docker","docker-container","docker-image","nginx","nodejs","rabbitmq","redis","service-discovery"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","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/smebberson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-04-22T08:49:05.000Z","updated_at":"2025-03-08T16:02:16.000Z","dependencies_parsed_at":"2022-08-24T12:01:09.897Z","dependency_job_id":null,"html_url":"https://github.com/smebberson/docker-alpine","commit_stats":null,"previous_names":[],"tags_count":179,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smebberson%2Fdocker-alpine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smebberson%2Fdocker-alpine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smebberson%2Fdocker-alpine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smebberson%2Fdocker-alpine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smebberson","download_url":"https://codeload.github.com/smebberson/docker-alpine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266564,"owners_count":20910836,"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":["alpine-linux","apache","confd","consul","docker","docker-container","docker-image","nginx","nodejs","rabbitmq","redis","service-discovery"],"created_at":"2024-07-31T03:01:54.667Z","updated_at":"2025-04-05T00:08:36.651Z","avatar_url":"https://github.com/smebberson.png","language":"Dockerfile","readme":"# docker-alpine\n\nHighly configurable Docker images running [Alpine linux][alpinelinux] and [s6][s6] process management.\n\n**Table of contents**\n\n- [Goals](#goals)\n- [Docker and microservices](#docker-and-microservices)\n- [Image design](#image-design)\n- [Consul and service discovery](#consul-and-service-discovery)\n- [Examples](#examples)\n- [Images](#images)\n- [Usage](#usage)\n- [Customization](#customization)\n- [Versioning](#versioning)\n- [FAQ](#faq)\n- [Further reading](#further-reading)\n- [Changelog](#changelog)\n- [Contributing](#contributing)\n- [Contributors](#contributors)\n\n## Goals\n\nThis project has the following goals:\n\n- To produce small Docker images.\n- To provide Docker images that are easily configurable.\n- To provide Docker images that are highly stable.\n- To quickly enable a microservices architecture using Docker.\n\nTo meet these goals, we're using:\n\n- [Alpine linux][alpinelinux] (very small but capable Linux distribution).\n- [s6][s6] for process management for both easily configurable, and highly stable images.\n\n## Docker and microservices\n\nUsing Docker makes your infrastructure and environment consistent, testable, scalable and repeatable.\n\n### What are microservices?\n\nMicroservices are isolated components (of a whole) doing one thing, and doing it well. These microservices are pulled together to provide a complete platform. For example, each of the following microservices would exist within one Docker container:\n\n- A stateless web application running in Node.js.\n- Session data for the Node.js web application provided by Redis.\n- MongoDB as the database for the Node.js web application.\n- Nginx web server proxying requests to Node.js.\n\n### How do they talk to each other?\n\nThat's called service discovery. We solve that problem using Consul (which is a distributed service discovery tool, with built-in health checks). Each container advertises their service (IP and port) via Consul.\n\nEach container with a service, connects to a member of the Consul cluster. Consul then _talks_ to all members to enable service discovery via HTTP and DNS.\n\nA good example is a container with Nginx that will query Consul for the IP address of the Node.js container so that it can proxy an incoming request through to the Node.js application.\n\n### What about scalability?\n\nSetting up your infrastructure using microservices makes scalability a breeze.\n\n[There is an example](examples/complete/README.md) showing Nginx load balancing incoming requests to multiple Node.js containers.\n\n## Image design\n\nThese images are used heavily in production by a number of different companies. They've been designed as great starting points to easily customize and use within your own platforms.\n\n### Core components\n\nThe following are common to all images within this repository.\n\n#### Alpine Linux\n\nAlpine Linux provides the foundation for all images in this repository. It's small, fast and perfect for Docker.\n\n#### s6\n\ns6 is a unix service supervisor (much like runit and supervisord only better).\n\nWhile it's true that Docker containers should have one clear focus, more often than not, you'll need to run multiple processes within the container.\n\nConsul is a great example; you need the Consul agent to join a Consul cluster and the primary service such as Nginx or Node.js. Log management is also a key consideration in which another process might need to run.\n\n#### s6-overlay\n\ns6-overlay is s6 Dockerized! It makes working with Docker and process management via s6 super easy. It also features some really nice extras such as container initialization and finalization stages (run custom scripts during these phases to setup services or tidy up from crashes).\n\n#### go-dnsmasq\n\ngo-dnsmasq has been added into the mix to add support for the DNS `search` keyword which doesn't come standard in Alpine Linux.\n\nThese images work well with the embedded DNS service that comes with Docker 1.10+.\n\n### Configuration\n\nConfiguration is a key step within a Docker-based microservices architecture. You must configure your services to interact with each other.\n\nAll Consul-based images come with `consul-template` for easy configuration based on changes within Consul.\n\nAll non-Consul-based images come with `confd`.\n\n## Consul and service discovery\n\nAll Consul-related containers have been design for use in production and development.\n\nThese containers have been configured for zero-conf Consul bootstrapping. To achieve this, `docker-engine` v1.10+ is required. along with a `docker-compose.yml` file written in the version `2` format ([see the example](examples/complete/docker-compose.yml)).\n\nTo achieve zero-conf Consul bootstrapping, Docker's new embedded DNS server is used within each container to find the IP of a consul container (**note**: there is a requirement that all Consul server services in `docker-compose.yml` are called `consul` for this to work).\n\n**Note:**: this can work in older versions of Docker however (using service links with the name consul).\n\n### Crashes and restarts.\n\nThe Consul-based images in this repository have been designed to meet the following requirements:\n\nContainers running Consul in server mode:\n\n- When Consul dies: kill the container immediately.\n- When Consul starts: remove all data associated with Consul so everything starts afresh.\n\nContainers running Consul in agent mode:\n\n- When Consul dies: immediately restart it using s6.\n- When Consul starts: it will use the Consul data previously create to quickly rejoin a cluster.\n- When the primary service dies: kill the container immediately.\n\nWe've found this to be the most consistent way to effectively run Consul in production. This also supports the development workflow in which you `CTRL+C` to stop a container from running.\n\n## Examples\n\nMost images have an example in the [examples folder](examples/).\n\nThere is also a complete example which demonstrates:\n\n- Zero-configuration Consul bootstrapping.\n- Stateless application.\n- Load balanced Nginx proxies.\n- Scaled web application.\n\nYou can read more about the [example](examples/complete/README.md).\n\n## Images\n\nThe following describes the images that are available and the inheritance chain.\n\n### Images without Consul\n\n```\n└─ alpine-base\n   ├─ alpine-apache\n   ├─ alpine-confd\n   |  └─ alpine-rabbitmq\n   ├─ alpine-nginx\n   |  └─ alpine-nginx-nodejs\n   ├─ alpine-nodejs\n   └─ alpine-redis\n```\n\n### Images with Consul\n\n```\n└─ alpine-base\n   └─ alpine-consul\n      ├─ alpine-consul-ui\n      └─ alpine-consul-base\n         ├─ alpine-consul-apache\n         ├─ alpine-consul-nodejs\n         ├─ alpine-consul-nginx\n         |  └─ alpine-consul-nginx-nodejs\n         └─ alpine-consul-redis\n```\n\n### alpine-base\n\nThis image is the base for all containers. All other Docker images within this repository inherit from this Container.\n\nLatest version is `3.3.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-base/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-base/VERSIONS.md)\n\n### alpine-apache\n\nThis image includes Apache HTTPD with a very basic configuration.\n\nLatest version is `2.0.1`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-apache/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-apache/VERSIONS.md)\n\n### alpine-confd\n\nThis image adds [confd][confd]. It should be seen as a base image suitable for heavy customisation.\n\nLatest version is `3.1.0`, or `latest`.\n\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-confd/VERSIONS.md)\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-confd/README.md)\n\n### alpine-consul\n\nThis image adds [Consul][consul].\n\nIf you want to create a Docker image to run as a Consul agent in server mode (i.e. part of a cluster) start with this image.\n\nLatest version is `3.2.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul/VERSIONS.md)\n\n### alpine-consul-base\n\nThis image inherits from `alpine-consul` and is designed as a base image for other Docker images which will join to a Consul cluster.\n\nIf you want to create a Docker image to advertise a service in Consul start with this image.\n\nLatest version is `4.2.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-base/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-base/VERSIONS.md)\n\n### alpine-consul-apache\n\nThis image is designed to run Apache within the context of service discovery (via Consul).\n\nIt is suited to running Apache as a proxy to another Docker container.\n\nLatest version is `2.0.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-apache/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-apache/VERSIONS.md)\n\n### alpine-consul-nodejs\n\nThis image is designed to run a Node.js application within the context of service discovery (via Consul).\n\nLatest version is `5.11.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nodejs/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nodejs/VERSIONS.md)\n\n### alpine-consul-nginx\n\nThis image is designed to run Nginx within the context of service discovery (via Consul).\n\nIt's suited for running an Nginx proxy or to load balance with Nginx to another container.\n\nLatest version is `3.2.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nginx/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nginx/VERSIONS.md)\n\n### alpine-consul-nginx-nodejs\n\nThis image is designed to run both Nginx and Node.js on the same container. It's a shortcut to running `alpine-consul-nodejs` via a proxy from `alpine-consul-nodejs`.\n\nLatest version is `2.0.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nginx-nodejs/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nginx-nodejs/VERSIONS.md)\n\n### alpine-consul-redis\n\nThis image has been designed to run Redis within the context of service discovery (via Consul).\n\nLatest version is `2.1.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-redis/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-redis/VERSIONS.md)\n\n### alpine-consul-ui\n\nThis image has been designed to connect to a Consul cluster (from `alpine-consul`) and make the Consul admin UI accessible.\n\nLatest version is `2.2.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-ui/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-ui/VERSIONS.md)\n\n### alpine-nginx\n\nThis image includes Nginx with a very basic setup.\n\nLatest version is `3.0.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-nginx/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-nginx/VERSIONS.md)\n\n### alpine-nginx-nodejs\n\nThis image includes both Nginx and Node.js. It's suitable if you want to have Node.js perform configuration for Nginx.\n\nLatest version is `4.4.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-nginx-nodejs/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-nginx-nodejs/VERSIONS.md)\n\n### alpine-nodejs\n\nThis includes Node.js.\n\nLatest version is `8.15.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/alpine-nodejs-v8.15.0/alpine-nodejs/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/alpine-nodejs-v8.15.0/alpine-nodejs/VERSIONS.md)\n\n### alpine-rabbitmq\n\nThis image inherits from `alpine-confd`, and includes [RabbitMQ][rabbitmq] with a basic setup.\n\nLatest version is `2.1.1`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-rabbitmq/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-rabbitmq/VERSIONS.md)\n\n### alpine-redis\n\nThis image includes Redis.\n\nLatest version is `1.0.0`, or `latest`.\n\n- [README.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-redis/README.md)\n- [VERSIONS.md](https://github.com/smebberson/docker-alpine/blob/master/alpine-redis/VERSIONS.md)\n\n## Usage\n\nAll containers come with the following features (most of them come from [s6-overlay][s6overlay]):\n\n- User hooks for container initialization, ownership and permissions management, and finalization tasks.\n- Easily drop privileges before starting a service.\n- Start and finish scripts for service management.\n- Environment management.\n\n### Using `CMD`\n\nAs a general rule, these images eschew the `CMD` option that Dockerfile provides. These images are oriented towards running multiple services.\n\nHowever, `alpine-base` is a minimalist image that can be used with `CMD`. Your command can be provided in the Dockerfile or at runtime and it will be run under the s6 supervisor. When the command fails or exits, the container will also exit (falling back to Docker restart rules or other platform controls to manage container availability).\n\nFor example:\n\n```\nvagrant@ubuntu-14:/vagrant$ docker run -it smebberson/alpine-base with-contenv sh\n[s6-init] making user provided files available at /var/run/s6/etc...exited 0.\n[s6-init] ensuring user provided files have correct perms...exited 0.\n[fix-attrs.d] applying ownership \u0026 permissions fixes...\n[fix-attrs.d] done.\n[cont-init.d] executing container initialization scripts...\n[cont-init.d] 30-resolver: executing...\n[cont-init.d] 30-resolver: exited 0.\n[cont-init.d] 40-resolver: executing...\n[cont-init.d] 40-resolver: exited 0.\n[cont-init.d] done.\n[services.d] starting services\n[services.d] done.\n/ # env\nHOSTNAME=63d07768fdc5\nSHLVL=1\nHOME=/root\nGO_DNSMASQ_LOG_FILE=/var/log/go-dnsmasq/go-dnsmasq.log\nGODNSMASQ_VERSION=1.0.5\nTERM=xterm\nS6_OVERLAY_VERSION=v1.19.1.1\nPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\nPWD=/\n/ # exit\nwith-contenv exited 0\n[cont-finish.d] executing container finish scripts...\n[cont-finish.d] done.\n[s6-finish] syncing disks.\n[s6-finish] sending all processes the TERM signal.\n[s6-finish] sending all processes the KILL signal and exiting.\nvagrant@ubuntu-14:/vagrant$\n```\n\n### Using services\n\ns6 provides us a clean and simple way to run services within these images. For example alpine-consul runs both go-dnsmasq and Consul via services, and alpine-consul-nginx adds Nginx, also via services.\n\nTo write a service script, create a directory with the name of your service in the `/etc/services.d/` directory. In that directory create an executable script named `run`. In your run script, start your service (be sure to make sure it doesn't background as s6 will attempt to start it again). For example:\n\n```\n# /etc/services.d/nginx/run\n\n#!/usr/bin/with-contenv sh\n\nnginx -g \"daemon off;\"\n```\n\ns6 will start your service and monitor it. Should your service exit or fail, s6 will execute your run script again to restart the service.\n\n#### Finish hooks\n\ns6 also provides you a hook to run tasks in between a service exiting or failing, and it being restarted. Simple create an executable script named `finish` next to your `run` script.\n\nThis script should execute fast. It has about 3 seconds to do what it needs to before it will be killed by s6, and the `run` script executed. You can also do any tasks as required in your `run` before you start your long running process.\n\n#### Bringing down a container\n\nIf you'd like to bring down a container if a particular service restarts, use this as the contents of a `finish` script:\n\n```\n#!/usr/bin/execlineb -S1\n\n# only tell s6 to bring down the entire container, if it isn't already doing so\n# http://skarnet.org/software/s6/s6-supervise.html\nif { s6-test ${1} -ne 0 }\nif { s6-test ${1} -ne 256 }\n\ns6-svscanctl -t /var/run/s6/services\n```\n\n## Customization\n\nThe docker-alpine images are highly customizable. You can customize them with the following:\n\n- Setting ENV variables to change settings.\n- Overwrite a configuration file (not all images have these) to alter an application.\n- Overwrite run scripts to change application start process.\n\nThey've also been designed so that it's easy to use these images in a non-standard context such as Docker Cloud and Rancher.\n\nThe following cover customization that is common to all images. Review the documentation for each image for image-specific customization options.\n\n### `/usr/bin/host-ip`\n\n[This file](alpine-base/root/usr/bin/host-ip) is used in other scripts to determine the IP of the container in which a script is running.\n\nOverwrite it as required to produce a correct value for your environment. Review the file itself for output requirements.\n\nIf your environment uses an overlay network (Docker Cloud, Rancher), you should change this file.\n\n### `/usr/bin/container-find`\n\n[This file](alpine-consul/root/usr/bin/container-find) (Consul-only containers) is used within other scripts to determine the IP address(es) of other containers by name.\n\nBy default, it uses `dig` to DNS query for the IP address of a container by name. `container-find` will DNS query for `consul` (the default). `container-find static` will DNS query for `static`. `container-find static.service.consul` will hand-off the DNS query to Consul.\n\n## Versioning\n\nEach image has it's own version and will be updated independently. All versions follow [semver](semver). If a software package or the operating system the image uses is updated, the level of update will be reflected in the new version number, for example:\n\n- if Alpine Linux is upgraded from 3.2 to 3.3, then the image version will receive a minor increment\n- if Alpine Linux is upgraded from 3.3 to 4, then the image version will receive a major increment\n- if s6-overlay is upgraded to the latest patch upgrade, and nginx is upgraded to the latest minor upgrade, then the image version will will receive a minor increment\n\n## FAQ\n\nThese images are a little different from your standard Docker images. The following should explain most of the differences.\n\n### DNS search\n\nBy default, Alpine Linux \u003c= v3.4 doesn't support DNS `search`. This has been enabled through the use of `go-dnsmasq`.\n\n### Where is Bash?\n\nThese images don't contain Bash by default. They're defaulted to use `sh`.\n\nYou can either write your scripts such that they're posix compliant or install Bash with `apk add --no-cache bash`.\n\n### Where is my environment?\n\nBy default, `sh` has no environment. If you need access to environment variables in scripts or when using `docker exec` you should use:\n\n- `#!/usr/bin/with-contenv sh`\n- `docker exec -it complete_consul_1 with-contenv`\n\n### Setting environment variables.\n\nThere are two ways to set environment variables. In your `Dockerfile` like any other containers or from within a custom script using `set-contenv` for example `set-contenv VAR_NAME var_value`.\n\n## Further reading\n\nIf you'd like to read more about operating environment of these images, start here:\n\n- [s6-overlay][s6overlay]\n- [s6][s6]\n- [Alpine Linux][alpinelinux]\n\n## Changelog\n\nRead the [CHANGELOG.md](CHANGELOG.md) for a chronological record of events. Each image also has it's own CHANGELOG.\n\n## Contributing\n\nWe love contributors. Read [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to contribute to this project.\n\n## Contributors\n\n- [smebberson](https://github.com/smebberson)\n- [matthewvalimaki](https://github.com/matthewvalimaki)\n- [sandytrinh](https://github.com/sandytrinh)\n- [gaff](https://github.com/Gaff)\n- [ncornag](https://github.com/ncornag)\n- [emmetog](https://github.com/emmetog)\n\nYou can view [more information about the contributors here](https://github.com/smebberson/docker-alpine/graphs/contributors).\n\n[alpinelinux]: https://www.alpinelinux.org/\n[s6]: http://skarnet.org/software/s6/\n[s6overlay]: https://github.com/just-containers/s6-overlay\n[consul]: https://consul.io/\n[semver]: http://semver.org/\n[confd]: https://github.com/kelseyhightower/confd\n[dockeralpinedesign]: https://github.com/smebberson/docker-alpine/blob/master/DESIGN.md\n[alpinebasedns]: https://github.com/smebberson/docker-alpine/tree/master/alpine-base#dns\n[rabbitmq]: http://www.rabbitmq.com/\n[consultemplate]: https://github.com/hashicorp/consul-template\n","funding_links":[],"categories":["Dockerfile","Docker","docker"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmebberson%2Fdocker-alpine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmebberson%2Fdocker-alpine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmebberson%2Fdocker-alpine/lists"}