{"id":13528242,"url":"https://github.com/lambda-linux/baseimage-amzn","last_synced_at":"2025-04-01T11:31:12.098Z","repository":{"id":217016290,"uuid":"61764751","full_name":"lambda-linux/baseimage-amzn","owner":"lambda-linux","description":"A minimal Docker Base Image based on Amazon Linux","archived":true,"fork":false,"pushed_at":"2017-07-25T10:52:13.000Z","size":15,"stargazers_count":37,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-02T13:34:19.436Z","etag":null,"topics":["amazon-linux","docker-container"],"latest_commit_sha":null,"homepage":"https://lambda-linux.io/","language":"Shell","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/lambda-linux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2016-06-23T01:55:25.000Z","updated_at":"2023-08-18T05:44:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"91ad6ad7-c431-4b5c-b38f-613edb3521ab","html_url":"https://github.com/lambda-linux/baseimage-amzn","commit_stats":null,"previous_names":["lambda-linux/baseimage-amzn"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-linux%2Fbaseimage-amzn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-linux%2Fbaseimage-amzn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-linux%2Fbaseimage-amzn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambda-linux%2Fbaseimage-amzn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambda-linux","download_url":"https://codeload.github.com/lambda-linux/baseimage-amzn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246631803,"owners_count":20808759,"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":["amazon-linux","docker-container"],"created_at":"2024-08-01T06:02:20.964Z","updated_at":"2025-04-01T11:31:12.092Z","avatar_url":"https://github.com/lambda-linux.png","language":"Shell","readme":"# A minimal Docker Base Image based on Amazon Linux Container Image\n\nbaseimage-amzn is a [Docker](https://www.docker.com) [Base Image](https://docs.docker.com/v1.11/engine/reference/glossary/#base-image) that is configured for use within Docker containers. It is based on [Amazon Linux Container Image](https://aws.amazon.com/blogs/aws/new-amazon-linux-container-image-for-cloud-and-on-premises-workloads/), plus:\n\n * Modifications for Docker-friendliness.\n * Administration tools that are useful in the context of Docker.\n * Mechanisms for running multiple processes.\n\nYou can use it as a base for your own Docker images.\n\nbaseimage-amzn is available for pulling from [the docker registry!](https://hub.docker.com/r/lambdalinux/baseimage-amzn/)\n\nIf you need additional help, please contact us on our [support](https://lambda-linux.io/support/) channels or open a GitHub [Issue](https://github.com/lambda-linux/baseimage-amzn/issues).\n\nbaseimage-amzn is inspired by [baseimage-docker](https://github.com/phusion/baseimage-docker) project. We would like to say thank you to Phusion for providing some good ideas and code. We would also like to say thank you to [Amazon Linux Team](https://aws.amazon.com/amazon-linux-ami/) for providing excellent Amazon Linux Container Image.\n\n-----------------------------------------\n\n**Related resources**:\n  [Website](https://lambda-linux.io/) |\n  [Slack](http://slack.lambda-linux.io/) |\n  [Discussion Forum](https://groups.google.com/group/lambda-linux) |\n  [Twitter](https://twitter.com/lambda_linux) |\n  [Blog](https://lambda-linux.io/blog/) |\n  [FAQs](http://lambda-linux.io/faqs/#!/baseimage-amzn-questions)\n\n **Table of contents**\n\n  * [What's inside the image?](#whats_inside)\n    * [Overview](#overview)\n    * [A note about SSH server](#about_ssh_server)\n    * [baseimage-amzn Version Numbering](#version_numbering)\n    * [Inspecting baseimage-amzn](#inspecting)\n  * [Using baseimage-amzn as Docker Base Image](#using)\n    * [Getting started](#getting_started)\n    * [Building and running our Docker Image](#building_and_running)\n    * [Adding additional daemons](#adding_additional_daemons)\n    * [Running scripts during container startup](#running_startup_scripts)\n    * [Environment variables](#environment_variables)\n      * [Defining environment variables in our image at build time](#envvar_central_definition)\n      * [Using environment variable dump files](#envvar_dumps)\n    * [Installing and updating packages inside the container](#updating_packages)\n  * [Container administration](#container_administration)\n    * [Running a one-shot command in a new container](#oneshot)\n    * [Running a command in an existing container](#run_inside_existing_container)\n  * [Conclusion](#conclusion)\n\n-----------------------------------------\n\n\u003ca name=\"whats_inside\"\u003e\u003c/a\u003e\n## What's inside the image?\n\n\u003ca name=\"overview\"\u003e\u003c/a\u003e\n### Overview\n\n| Component        | Why is it included? / Remarks |\n| ---------------- | ------------------- |\n| Amazon Linux | The base system. |\n| A init process | baseimage-amzn comes with an init process. Available as `/sbin/my_init`. |\n| rsyslog | Syslog daemon is used by various services and applications to log to `/var/log/*` files. |\n| logrotate | Rotates and compresses logs files on a regular basis. |\n| cron | A cron daemon for cron jobs to run within the container. |\n| [runit](http://smarden.org/runit/) | Used for service supervision and management. |\n| `setuser` | A tool for running a command as another user. Sets `$HOME` correctly. Available as `/sbin/setuser`. |\n| `ll-user` | Image is configured with `ll-user:ll-user` unix user and group, and has a UID/GID pair of 500/500. This UID/GID pair maps correctly to `ec2-user:ec2-user` on Amazon Linux EC2 host. Correct UID/GID mapping between host and container helps avoid permission related issues.|\n\n\u003ca name=\"about_ssh_server\"\u003e\u003c/a\u003e\n### A note about SSH server\n\nWe do not ship SSH server in our image. For most users we recommend using [`docker exec`](#run_inside_existing_container) instead.\n\nWhile it is certainly possible to run SSH server within baseimage-amzn, securing SSH correctly in an operational setting is _non-trivial_. If your use-case _really_ requires running SSH server within baseimage-amzn, please [contact us](https://lambda-linux.io/support/) and we will find a good way to help you.\n\n\u003ca name=\"version_numbering\"\u003e\u003c/a\u003e\n### baseimage-amzn Version Numbering\n\nWe would like to give an overview of the version numbering convention that we follow and how that relates to Amazon Linux releases.\n\nAmazon Linux is a _rolling_ distribution. We can think of Amazon Linux as a single river of packages, and images themselves are just snapshots in time. When we run `yum update` our package set gets updated to the tip of this flow.\n\nReleases usually occur in March and September. Release version numbers have the form `20YY.MM`, where `YY` refers to the year, and `MM` refers to the month. For example `2017.03`.\n\nBetween major releases, point releases are made by Amazon Linux Team. Point releases have the form `20YY.MM.X`, where `X` is the point release number. For example `2017.03.1`.\n\nbaseimage-amzn uses version numbering of the form `20YY.MM-00X`, where `00X` is our point release. For example `2017.03-003`.\n\nWe will see the form `20YY.MM-00X` used in the documentation below. You can find the list of baseimage-amzn versions [here](https://hub.docker.com/r/lambdalinux/baseimage-amzn/tags/)\n\n\u003ca name=\"inspecting\"\u003e\u003c/a\u003e\n## Inspecting baseimage-amzn\n\nTo look around the image as `root` user, run:\n\n    docker run --rm -t -i lambdalinux/baseimage-amzn:2017.03-003 /sbin/my_init -- /bin/bash -l\n\n    docker run --rm -t -i lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e /sbin/my_init -- /bin/bash -l\n\nTo look around the image as `ll-user` user, run:\n\n    docker run --rm -t -i lambdalinux/baseimage-amzn:2017.03-003 /sbin/my_init -- /sbin/setuser ll-user /bin/bash -l\n\n    docker run --rm -t -i lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e /sbin/my_init -- /sbin/setuser ll-user /bin/bash -l\n\nHere `\u003c20YY.MM-00X\u003e` is baseimage-amzn [version number](#version_numbering).\n\nYou don't have to download anything manually. The above command will automatically pull baseimage-amzn image from the Docker registry.\n\n\u003ca name=\"using\"\u003e\u003c/a\u003e\n## Using baseimage-amzn as Docker Base Image\n\n\u003ca name=\"getting_started\"\u003e\u003c/a\u003e\n### Getting started\n\nThe image is called `lambdalinux/baseimage-amzn` and is available on the Docker registry.\n\n    # Use lambdalinux/baseimage-amzn as base image.\n    # See https://hub.docker.com/r/lambdalinux/baseimage-amzn/tags/ for\n    # a list of version numbers.\n    FROM lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e\n\n    # Use baseimage-amzn's init system\n    CMD [\"/sbin/my_init\"]\n\n    RUN \\\n      # Update RPM packages\n      yum update \u0026\u0026 \\\n\n      # ...put your own build instructions here...\n\n      # Clean up YUM when done\n      yum clean all \u0026\u0026 \\\n      rm -rf /var/cache/yum/* \u0026\u0026 \\\n      rm -rf /tmp/* \u0026\u0026 \\\n      rm -rf /var/tmp/*\n\n\u003ca name=\"building_and_running\"\u003e\u003c/a\u003e\n### Building and running our Docker Image\n\nWe use [`docker build`](https://docs.docker.com/v1.11/engine/reference/commandline/build/) command to build our Docker Image.\n\nOnce the image is built, we can start our container with [`docker run`](https://docs.docker.com/v1.11/engine/reference/commandline/run/) command.\n\n    docker run -d \u003cDOCKER_IMAGE\u003e\n\nSince our `Dockerfile` includes the instruction `CMD [\"/sbin/my_init\"]`, Docker will start the `my_init` process. `my_init` will set up our [container environment](#environment_variables) and start runit process supervisor. Runit then launches and manage processes inside our container.\n\nWe can run `pstree` command within the Docker container to see this behavior in action.\n\nFind the container name of the running Docker container.\n\n    docker ps\n\nExecute `pstree` command in the container.\n\n    docker exec \u003cCONTAINER_NAME\u003e /usr/bin/pstree\n\n    my_init---runsvdir-|-runsv---rsyslogd---2*[{rsyslogd}]\n                       `-runsv---crond`\n\nWe can stop the running Docker container with [`docker stop`](https://docs.docker.com/v1.11/engine/reference/commandline/stop/) command.\n\n\u003ca name=\"adding_additional_daemons\"\u003e\u003c/a\u003e\n### Adding additional daemons\n\nWe can add additional daemons (e.g. our own app) to the image by creating runit entries. We have to write a small shell script which runs our daemon, and runit will keep it running for us, restarting it when it crashes, etc.\n\nRunit requires the shell script to be named `run`. It must be an executable, and should be placed in the directory `/etc/service/\u003cNAME\u003e`.\n\nHere is an example showing how a memcached server runit entry can be made.\n\nCreate a file `memcached.sh`. Make sure this file is has execute permission set (`chmod +x`).\n\n    #!/bin/sh\n    # `/sbin/setuser memcached` runs the given command as the user `memcached`.\n    # If you omit that part, the command will be run as root.\n    exec /sbin/setuser memcached /usr/bin/memcached \u003e\u003e /var/log/memcached.log 2\u003e\u00261\n\nIn `Dockerfile`:\n\n    RUN mkdir /etc/service/memcached\n    ADD memcached.sh /etc/service/memcached/run\n\nNote that the daemon being executed by the `run` shell script **must not put itself into the background and must run in the foreground**. Daemons usually have a command line flag or a config file option for running in foreground mode.\n\n\u003ca name=\"running_startup_scripts\"\u003e\u003c/a\u003e\n### Running scripts during container startup\n\nThe baseimage-amzn init system, `/sbin/my_init`, can run scripts during startup. They are run in the following order if they exist.\n\n  * All executable scripts in `/etc/my_init.d`. The scripts in this directory are executed in alphabetical order.\n  * The script `/etc/rc.local`.\n\nAll scripts must exit correctly, that is with an exit code 0. If any script exits with a non-zero exit code, the booting will fail.\n\nThe following example shows us how to add startup script. This script logs the time of boot to the file `/tmp/boottime.txt`.\n\nCreate a file `logtime.sh`. We need to make sure this file has execute permission set (`chmod +x`).\n\n    #!/bin/sh\n    date \u003e /tmp/boottime.txt\n\nIn `Dockerfile`:\n\n    RUN mkdir -p /etc/my_init.d\n    ADD logtime.sh /etc/my_init.d/logtime.sh\n\n\u003ca name=\"environment_variables\"\u003e\u003c/a\u003e\n### Environment variables\n\nWhen we use `/sbin/my_init` as our main container command, any environment variables defined using `docker run --env` or the [`ENV`](https://docs.docker.com/v1.11/engine/reference/builder/#env) instruction in the `Dockerfile` will be picked up by `/sbin/my_init`. These environment variables will be passed to all child processes, including `/etc/my_init.d` [startup scripts](#running_startup_scripts), runit and [runit managed services](#adding_additional_daemons).\n\nFollowing example shows this in action.\n\n    $ docker run --rm -t -i \\\n      --env FOO=bar --env HELLO='my beautiful world' \\\n      lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e /sbin/my_init -- /bin/bash -l\n\n    [...]\n\n    *** Running /bin/bash -l...\n    [root@ff6cbb791855] / # echo $FOO\n    bar\n    [root@ff6cbb791855] / # echo $HELLO\n    my beautiful world\n    [root@ff6cbb791855] / #\n\nHere `\u003c20YY.MM-00X\u003e` is baseimage-amzn [version number](#version_numbering).\n\n\u003ca name=\"envvar_central_definition\"\u003e\u003c/a\u003e\n#### Defining environment variables in our image at build time\n\nWhen `/sbin/my_init` starts up, before running any [startup scripts](#running_startup_scripts), `/sbin/my_init` imports environment variables from the directory `/etc/container_environment`. This directory contains files that are named after the environment variable names. The file contents contain the environment variable values.\n\n`/etc/container_environment` is a good place to define our environment variables at build time. The environment variables defined in `/etc/container_environment` is inherited by all startup scripts and runit services.\n\nFor example, here is how we can define an environment variable in our `Dockerfile`.\n\n    RUN echo Apachai Hopachai \u003e /etc/container_environment/MY_NAME\n\nWe can verify that it works, as follows:\n\n    $ docker run --rm -t -i \\\n      \u003cDOCKER_IMAGE\u003e /sbin/my_init -- /bin/bash -l\n\n    [...]\n\n    *** Running /bin/bash -l...\n    [root@2a3356297ec4] / # echo $MY_NAME\n    Apachai Hopachai\n    [root@2a3356297ec4] / #\n\n\u003ca name=\"envvar_dumps\"\u003e\u003c/a\u003e\n#### Using environment variable dump files\n\nCertain services such as Nginx, resets the environment variables of its child processes. When this happens, `/sbin/my_init` provides a way to query the original environment variables that was passed at the time of container launch.\n\nDuring startup, right after importing environment variables from `/etc/container_environment`, `/sbin/my_init` dumps all its environment variables (that is, all variables imported from `/etc/container_environment` and variables picked up from `docker run --env`) to the following locations.\n\n  * `/etc/container_environment.sh` - Contains the environment variables in bash format. We can source this file from a bash shell script.\n  * `/etc/container_environment.json` - Contains the environment variables in JSON format.\n\nMultiple formats makes it easy to query the original environment variables from our favorite programming/scripting language.\n\nHere is an example showing how this works.\n\n    $ docker run --rm -t -i \\\n      --env FOO=bar --env HELLO='my beautiful world' \\\n      lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e /sbin/my_init -- /bin/bash -l\n\n    [...]\n\n    *** Running /bin/bash -l...\n    [root@42d4b4cd09b3] / # ls /etc/container_environment\n    FOO  HELLO  HOME  HOSTNAME  LANG  LC_CTYPE  PATH  PS1  TERM\n    [root@42d4b4cd09b3] / # cat /etc/container_environment/FOO; echo\n    bar\n    [root@42d4b4cd09b3] / # cat /etc/container_environment/HELLO; echo\n    my beautiful world\n    [root@42d4b4cd09b3] / # cat /etc/container_environment.json; echo\n    {\"LANG\": \"en_US.UTF-8\", \"TERM\": \"xterm\", \"PS1\": \"[\\\\u@\\\\h] \\\\w \\\\$ \", \"HOSTNAME\": \"42d4b4cd09b3\", \"LC_CTYPE\": \"en_US.UTF-8\", \"PATH\": \"/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\", \"HOME\": \"/\", \"FOO\": \"bar\", \"HELLO\": \"my beautiful world\"}\n    [root@42d4b4cd09b3] / # source /etc/container_environment.sh\n    [root@42d4b4cd09b3] / # echo $HELLO\n    my beautiful world\n    [root@42d4b4cd09b3] / # ls -la /etc/container_environment.sh\n    -rw-r----- 1 root docker_env 249 Jun 25 11:02 /etc/container_environment.sh\n    [root@42d4b4cd09b3] / # ls -la /etc/container_environment.json\n    -rw-r----- 1 root docker_env 254 Jun 25 11:02 /etc/container_environment.json\n\nHere `\u003c20YY.MM-00X\u003e` is baseimage-amzn [version number](#version_numbering).\n\n`/etc/container_environment.sh` and `/etc/container_environment.json` files are owned by root and accessible only by the `docker_env` group. To read these files as non-root user, we need to add the non-root user to `docker_env` group.\n\n\u003ca name=\"updating_packages\"\u003e\u003c/a\u003e\n### Installing and updating packages inside the container\n\nPackages can be installed and updated inside the container using `yum install` and `yum update` commands.\n\nWe recommend that including the following in `Dockerfile` so that the docker image has the latest packages.\n\n    RUN \\\n      yum update \u0026\u0026 \\\n      yum clean all \u0026\u0026 \\\n      rm -rf /var/cache/yum/* \u0026\u0026 \\\n      rm -rf /tmp/* \u0026\u0026 \\\n      rm -rf /var/tmp/*\n\n\u003ca name=\"container_administration\"\u003e\u003c/a\u003e\n## Container administration\n\nWhen working with containers, we will encounter situations where we may want to run a command inside a container or login to it. This could be for development, debugging or inspection purposes.\n\n\u003ca name=\"oneshot\"\u003e\u003c/a\u003e\n### Running a one-shot command in a new containers\n\nThis section describes how to run a command inside a new container. To run a command inside an existing container see [Running a command inside an existing, running container](#run_inside_existing_container).\n\nbaseimage-amzn provides a facility to run a single one-shot command inside a new container the following way.\n\n    docker run \u003cDOCKER_IMAGE\u003e /sbin/my_init -- COMMAND ARGUMENTS ...\n\nThis command does the following.\n\n * Runs all system startup files, such as `/etc/my_init.d/*` and `/etc/rc.local`.\n * Starts all runit services.\n * Runs the specified command.\n * When the specified command exists, stops all runit services.\n\nFor example:\n\n    $ docker run lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e /sbin/my_init -- /bin/ls\n    *** Running /etc/rc.local...\n    *** Booting runit daemon...\n    *** Runit started as PID 7\n    *** Running /bin/ls...\n    bin\n    boot\n\n    [...]\n\n    usr\n    var\n    *** /bin/ls exited with status 0.\n    *** Shutting down runit daemon (PID 7)...\n    *** Killing all processes...\n\nWe can customize how `/sbin/my_init` is invoked. Run `docker run \u003cDOCKER_IMAGE\u003e /sbin/my_init --help` for more information.\n\nThe following example runs `/bin/ls` without running the startup files, in quite mode, while running all runit services.\n\n    $ docker run lambdalinux/baseimage-amzn:\u003c20YY.MM-00X\u003e \\\n      /sbin/my_init --skip-startup-files --quiet -- /bin/ls\n    bin\n    boot\n\n    [...]\n\n    usr\n    var\n\nHere `\u003c20YY.MM-00X\u003e` is baseimage-amzn [version number](#version_numbering).\n\n\u003ca name=\"run_inside_existing_container\"\u003e\u003c/a\u003e\n### Running a command in an existing container\n\nStart Docker container:\n\n    docker run -d \u003cDOCKER_IMAGE\u003e\n\nFind the container name of the running Docker container.\n\n    docker ps\n\nOnce we have the container name, we can use [`docker exec`](https://docs.docker.com/v1.11/engine/reference/commandline/exec/) to run commands in the container. For example, to run `echo hello world`:\n\n    docker exec \u003cCONTAINER_NAME\u003e /bin/echo hello world\n\nTo open a bash session inside a running container, we need to pass `-t -i` so that a terminal is available.\n\n    docker exec -t -i \u003cCONTAINER_NAME\u003e /bin/bash -l\n\n\u003ca name=\"conclusion\"\u003e\u003c/a\u003e\n## Conclusion\n\n  * Using baseimage-amzn? [Tweet about us](https://twitter.com/share) and [follow us on Twitter](https://twitter.com/lambda_linux).\n  * Having problems? Please contact us on any of our [support](https://lambda-linux.io/support) channels or post a GitHub [Issue](https://github.com/lambda-linux/baseimage-amzn/issues).\n\nThank you for using baseimage-amzn.\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambda-linux%2Fbaseimage-amzn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambda-linux%2Fbaseimage-amzn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambda-linux%2Fbaseimage-amzn/lists"}