{"id":21988017,"url":"https://github.com/maxivak/docker-builder","last_synced_at":"2025-04-30T11:06:54.358Z","repository":{"id":62557318,"uuid":"70465610","full_name":"maxivak/docker-builder","owner":"maxivak","description":"Build and run Docker containers with Chef, Dockerfile and other tools","archived":false,"fork":false,"pushed_at":"2017-05-03T14:08:12.000Z","size":116,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-24T20:03:58.773Z","etag":null,"topics":["docker","docker-builder","docker-compose"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/maxivak.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-10T08:04:33.000Z","updated_at":"2017-06-29T15:45:17.000Z","dependencies_parsed_at":"2022-11-03T06:30:24.188Z","dependency_job_id":null,"html_url":"https://github.com/maxivak/docker-builder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxivak%2Fdocker-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxivak%2Fdocker-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxivak%2Fdocker-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxivak%2Fdocker-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxivak","download_url":"https://codeload.github.com/maxivak/docker-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227196132,"owners_count":17746178,"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":["docker","docker-builder","docker-compose"],"created_at":"2024-11-29T19:15:18.167Z","updated_at":"2024-11-29T19:15:18.768Z","avatar_url":"https://github.com/maxivak.png","language":"Ruby","readme":"# Docker builder\n\nTool to build and install Docker containers with Chef, Dockerfile and other provisioning tools.\n\nFeatures:\n* Config files are in Ruby.\n* Manage complexity of running Docker containers for your environment in one place.\n* Manage multiple containers\n\n\nOther tools:\n* docker-composer - with configs in yml\n\n\nDocker-builder is similar to docker-compose but has some more functionality to customize installation of servers on the host.\n\n\n# Overview\n\nProcess of installing server in Docker container consists of the following stages:\n\nProcess of building and running container on the host machine:\n* Build Docker image\n    * it will create a Docker image on the host machine\n    * build using Dockerfile or Chef provisioning\n    \n* Run Docker container\n    * provision host machine - run scripts locally on the host machine. It can be shell script of Chef recipe\n    * run container - `docker run`\n    * provision container - run script inside the container. It can be shell script of Chef recipe\n\n* Install systemd service on the host machine to run Docker container automatically (optional)\n\n* Start/Stop container\n\n* Destroy container\n\n* Destroy image\n\n\nConcepts of running Docker containers:\n* you can rerun containers without losing data. Data is stored on the host machine and shared with container.\n\n\n\n\nBuild Docker image:\n* from Dockerfile\n* Chef provisioning (machine_image) \n\nProvision during installation container on the host machine by:\n* running shell script inside container\n* running Chef script inside container with Chef provisioning\n\n\n\n# Installation\n\n* Install gem:\n```\ngem install docker-builder\n```\n\n\n\n# Quickstart\n\nWe will build and run a simple Docker container with Nginx server.\n\n* install gem\n\n```\ngem install docker-builder\n```\n\n\n* generate directory structure using generator\n\n```\ndocker-builder generate --name=nginx --type=chef\n``` \n\nit will create a folder `nginx` with necessary directory structure inside.\n\n\n* in the folder edit config file `config.rb` with common settings\n\n```\ncommon({\n    'prefix' =\u003e \"example-\",\n    'image_prefix' =\u003e 'example-',\n    'dir_data' =\u003e '/disk3/data/my-examples/',\n\n})\n\nservers({\n    'nginx'=\u003e{\n        # some server options here\n    },\n\n\n})\n\n\nbase({\n\n})\n\n\n```\n\n* edit custom settings for the server in file `servers/nginx/config.rb`\n \n```\n\nadd 'build', {\n    \"image_name\" =\u003e \"nginx\",\n    'build_type' =\u003e 'chef',\n    \"base_image\" =\u003e {        \"name\" =\u003e \"nginx\",        \"repository\" =\u003e \"nginx\",        \"tag\" =\u003e \"1.10\"    },\n\n}\n\nadd 'install', {\n    \"host\" =\u003e {      'script_type' =\u003e 'chef_recipe',       'script' =\u003e 'install_host',    },\n    \"node\" =\u003e {       'script_type' =\u003e 'chef_recipe',       'script' =\u003e 'install',    }\n}\n\nadd 'docker', {\n    \"command\"=\u003e \"nginx -g 'daemon off;'\",\n    'ports' =\u003e [\n        [8080,80],\n    ],\n    'volumes' =\u003e [\n        ['html', '/usr/share/nginx/html'],\n        ['log/nginx', '/var/log/nginx/'],\n    ],\n    'links' =\u003e [    ]\n}\n\nadd 'attributes', {\n  'nginx' =\u003e{\n      \"sitename\" =\u003e\"mysite.local\"\n  },\n\n\n}\n\n\n```\n\n* build Docker image\n\n```\n# from the folder with project\n\ndocker-builder build\n```\n\n* run container\n\n```\ndocker-builder up\n```\n\n* check container is running\n```\ndocker ps\n\n# see container named example-nginx\n```\n\n* access container \n\n```\ndocker exec -ti example-nginx /bin/bash\n```\n\n* access container from browser\n\n```\nhttp://localhost:8080\n```\n\n\n\n\n# Install Docker container. Overview\n\nProcess:\n* Create container - docker create\n* setup network and other settings for container\n\n* run provision to setup host machine. Script is running on the host machine.\n```\n{   \n'provision'=\u003e{\n    'setup' =\u003e [\n        {type: 'shell', ..}, \n        ..\n    ]\n    ...\n}\n```\n\n* run provision to setup created (not running) container. \nRun script to copy/update files in container.\n\n```\n{   \n'provision'=\u003e{\n   'setup'=\u003e [\n        {type: 'ruby', \u003c\u003cscript_options\u003e\u003e}, \n        ..\n    ]\n    ...\n}\n```\n\n* run container with `docker run`. Specify env variables, hostname and other options\n* first provision of container - bootstrap script. Run script from inside running container only once. \nScript should be located inside container.\n```\n{   \n'provision'=\u003e{\n   'bootstrap'=\u003e [\n        {type: 'chef', ..},\n        ..\n    ]\n}\n```\n\n* provision to initialize container. \nRun script every time after container starts. Script should be located inside container.\n```\n{   \n'provision'=\u003e{\n    'init'=\u003e [\n        {type: 'chef'},\n        ..\n    ]\n}\n```\n\n* Use lock file to make sure the container does not start until the provision is finished.\n\n\n\n\n\n# Basic usage\n\n# Provision with shell script\n\n* put scripts in `/path/to/project/ \u003c\u003cserver_name\u003e\u003e / scripts / install.sh`\n\n\n# Provisioning with Chef\n\nProcess of building and running container on the host machine:\n* Build Docker image\n    * it will create a Docker image on the host machine\n    \n* Run Docker container\n    * provision host machine - run scripts locally on the host machine\n    (recipe install_host.rb)\n    * run container (docker run)\n    * provision container - run script in the container\n    (recipe install.rb)\n\n* Install systemd service to run Docker container (optional)\n\n* Start/Stop container\n\n* Destroy container\n\n* Destroy image\n\n\n## Install server with Chef provisioning\n \n* generate directory structure using generator\n```\ndocker-builder generate --name=nginx --type=chef\n``` \n\nit will create a folder `nginx`\n\n* in the folder edit config file `config.rb` with common settings\n\n```\n\n```\n\n* edit custom settings for the server in file `servers/nginx/config.rb`\n \n```\n```\n\n* build Docker image\n\n```\n# from the folder with project\n\ndocker-builder build\n```\n\n* run container\n\n```\ndocker-builder up\n```\n\n* check container is running\n```\ndocker ps\n```\n\n* access container from browser\n\n```\nhttp://localhost:8080\n```\n\n\n\n\n\n# Usage\n\n\n* Build docker image\n\n```\ncd /path/to/servers\n\ndocker-builder build -s server_name\n```\n\n* run docker container\n\n```\ncd /path/to/servers\n\ndocker-builder run -s server_name\n```\n\nit will run container.\n\naccess container:\n\n```\ndocker exec -ti container_name /bin/bash\n```\n\n\n\n\n# Provision\n\n\n\n## Run provision after start\n\n### Run provision from host machine\n\nRun from outside container\n\n```\n'provision' =\u003e {\n    \"bootstrap\" =\u003e [\n        {'type' =\u003e 'shell', 'run_from'=\u003e'host', 'script'=\u003e'name=myserver ruby myprovision1.rb'     }\n    ]\n}\n    \n```\n\nit will run script `name=myserver ruby myprovision1.rb` from the host machine.\n\n\n### Provision with Chef\n\n* in config file\n```\n    'provision' =\u003e {\n        \"bootstrap\" =\u003e [\n            {'type' =\u003e 'chef', \"script\"=\u003e\"\", \"dir_base\"=\u003e\"/opt/bootstrap\", \"recipe\"=\u003e\"server::bootstrap\" },\n        ]\n    },\n```\n\nit will run chef provisioning:\n```\ncd /opt/bootstrap/ \u0026\u0026 chef-client -z -j /opt/bootstrap/config.json --override-runlist \"recipe[server::bootstrap]\"\n\n```\n\nconfig file with attributes (`/opt/bootstrap/config.json`) for chef-client is generated automatically.\n\n\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. \nYou can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n\n\n\n# Configuration\n\n* edit config.rb in your root folder\n\nYou can put all settings in this config.rb file and/or use config.rb file in each server's folder.\n\nConfig files:\n```\n/path/to/project/config.rb\n/path/to/project/servers/server1/config.rb\n/path/to/project/servers/server2/config.rb\n```\n\n\n## config.rb\n\n\n* CHEF_COOKBOOKS - list of paths to chef cookbooks\n\n\n# Build Docker image\n\nBuild types:\n* 'none' - no build required\n* 'Dockerfile' - using Dockerfile and docker build command\n* 'chef' - using Chef provisioning (gem chef-provisioning-docker)\n* 'packer' - using Packer tool\n\n\n# Chef provisioning\n\n* add additional paths for cookbooks\n\nin folder with servers:\n\n```\n# /path/to/my/servers/.chef/knife.rb\n\ncookbook_path cookbook_path+[\n    '/path/to/my/cookbooks',\n    '/path/to/my/other/cookbooks',\n]\n\n```\n\n\n# Build Docker container with Chef\n\nExample of building Docker container with Chef.\n\nAssume that our server name is 'nginx'.\n\n\n* edit config file 'myserver/config.rb'\n\n```\n####\n```\n\n* Chef recipes\n* cookbooks/nginx/recipes/build.rb \nplace chef resources to be included in the Docker image\n\n* cookbooks/nginx/recipes/install.rb\n\n* cookbooks/nginx/recipes/install_host.rb\n\n* build\n\n```\n# run from the folder\n\ndocker-builder build['nginx']\n```\n\n* shared data:\n/disk3/data/server-api/nginx-front\n\ndata for nginx server:\n* /etc/nginx/conf.d\n* /var/www/html\n* /var/log/nginx\n\n\n* Main site - /var/www/html ==\u003e /disk3/data/server-api/nginx-front/var/www/html\n\n \n\n* Config\n\n\n## Run container\n\n\n\n## Manage multiple servers\n\n\n\n\n\n\n# Build container\n\n## Build from Dockerfile\n\n* config for server\n```\n'build' =\u003e {\n      'build_type' =\u003e 'Dockerfile',\n      \"image_name\" =\u003e \"myname\",\n\n      \"base_image\" =\u003e {} # not used\n  },\n```\n\n\n## Build with Packer\n\n* config for server\n```\n'build' =\u003e {\n      'build_type' =\u003e 'packer',\n      \"image_name\" =\u003e \"myname\",\n\n      \"base_image\" =\u003e {\n        \"name\" =\u003e \"nginx\",        \n        \"repository\" =\u003e \"nginx\",        \n        \"tag\" =\u003e \"1.10\"\n      },\n      \n      \"packer\" =\u003e { options for packer }\n  },\n```\n\n* options for packer\n\n* cookbook_paths - list of paths\n* recipe_name\n\n\n* examples:\n```\n```\n\n\n# Run container\n\n\n## Run from existing image\n\n* config for server\n```\n'build' =\u003e {\n      'build_type' =\u003e 'none',\n      \"image_name\" =\u003e \"myname\",\n\n      \"base_image\" =\u003e {\n          \"name\" =\u003e \"mysql\", \n          \"repository\" =\u003e \"mysql\", \n          \"tag\" =\u003e \"3.4.9\"\n      },\n  },\n      \n```\n\nit will NOT build a new Docker image.\n\n\n\n## Run Docker container with Chef\n\n* run recipe install_host which runs on the host machine (not in container)\n* run recipe install which runs from within the running container \n\n\n\n# Start Docker container\n\ndocker-builder start -s server_name\n\nit starts docker container which was previously created.\n\nProcess:\n* Start docker container container with `docker start ..`\n* Provision container\n\n\n\n# Other tools\n\n* packer - https://github.com/mitchellh/packer\n\nPacker is a tool for creating machine images for multiple platforms from a single source configuration.\n\n\n\n# Docker options for running container\n\n* `run_extra_options` - additional options for docker run command\n \n* hostname\n\n```\n{\n..\nservers({\n    'zookeeper'=\u003e{\n    ...\n        'docker'=\u003e {\n            ...\n            'run_extra_options'=\u003e'--hostname zookeeper'\n        }\n}\n```\n\n\n\n# Clear cache\n\nSometimes you need to clear cache with server info in chef-zero server\n\n```\ndocker-builder clear_cache\n```\n\n\n# Run in swarm mode\n\n* commands\n\ndocker-builder :up_swarm\n\ndocker-builder :destroy_swarm\n\n\n* config\n\n```\ndocker: {\n    # options here...\n}\n```\n\n* swarm_network - network name\n* swarm_options - options to pass to docker service create command\n\n\n\n# Options\n\n## prefix\n\nprefix for image names, container names, and service names (for swarm mode)\n\n* prefix - common prefix. Added to all names\n* container_prefix - prefix for containers\n* image_prefix - prefix for images\n* service_prefix  - prefix for services\n    \n    \nExample:\n* container name = $prefix$container_prefix$name\n\n```\nprefix='my-'\ncontainer_prefix='test-'\n\ncontainer name will be like \nmy-test-redis\n\n```\n\n    \n\n# Provision\n\n## Setup container\n\n### Setup container with shell script\n\n* run script from the host\n\n```\n'provision' =\u003e {\n    \"setup\" =\u003e [\n        {  'type' =\u003e 'shell',     'script' =\u003e 'scripts/mysetup.sh',  },\n     ]\n},\n```\n\n* it will run the script\n```\nscripts/mysetup.sh\n```\n\n## Bootstrap container\n\n* first provision of container\n* provision scripts run only once\n\n\n\n### Bootstrap with shell script\n\n* Dockerfile\n\n* include script /opt/bootstrap/bootstrap.sh in container\n```\nADD scripts/bootstrap.sh /opt/bootstrap/\n\nRUN chmod +x /opt/bootstrap/bootstrap.sh\n\n```\n\n* config\n\n```\n'provision' =\u003e {\n    \"bootstrap\" =\u003e [\n        {  'type' =\u003e 'shell',     'script' =\u003e '/opt/bootstrap/bootstrap.sh',  },\n     ]\n},\n\n\n```\n\n## Provision with chef\n\ndocker-builder up -s server_name\n\nProcess:\n* docker create with docker options\n    * entrypoint: /etc/bootstrap\n* generate config with node attributes for chef and save it to temp/boostrap-__server__.json\n* copy config file to container to /opt/bootstrap/config.json\n* docker start \n* when container starts it runs /etc/bootstrap which\n    * runs chef-client to provision server first time\n\n\n\n\n\n\n# Network\n\n* Docker container can be connected to multiple networks. \nContainer has an IP in each network. \n\nDocker networks can be created using docker command `docker network create`\n\n\nDocker-builder allows you to manage networks for your container.\n\n\n\n\n\n\n## multiple networks\n\n\n* connect to multiple networks and specify default gateway\n\ndefine IP in each network.\n\nit assumes that networks 'my_bridge1' and 'my_overlay1' exist.\n\n\n```\n'docker'=\u003e {\n..\n'network': {\n   default_gateway: '192.168.1.1',\n   networks: {\n      {net: 'bridge'}, # default docker bridge\n      {net: 'my_bridge1', ip: '10.1.0.12'},\n      {net: 'my_overlay1', ip: '51.1.0.15'},\n   }\n   \n}\n\n}\n```\n\nin this example container will be connected to three networks:\n     * docker default bridge named 'bridge'\n     * custom docker network named 'my_bridge1' with ip='10.1.0.12'\n     * custom docker network named 'my_overlay1'\n     \n     \n\ncreate networks:\n```\ndocker network create --driver bridge --subnet=51.1.0.0/16 --gateway=51.1.0.1  my_bridge1\ndocker network create -d macvlan --subnet=10.1.0.0/16  --gateway=10.1.0.1 --ip-range=10.1.12.0/24 -o parent=eth0 my_overlay1\n```\n\nsee docker networks:\n```\ndocker network ls\n```\n\n\n* check\n```\ndocker exec -ti mycontainer bash\n\nip route\n\n# sample output\n...\n\n```\n\n\n## remove default Docker bridge network \n\n\n* Container will be connected to two networks and NOT connected to default Docker network 'bridge'\n\n```\n'docker'=\u003e {\n..\n'network': {\n   networks: {\n      {net: 'bridge', action: 'remove'}, # remove default docker bridge\n      {net: 'mybridge1', ip: '10.1.0.12'},\n      {net: 'my_overlay1', ip: '51.1.0.15'},\n   }\n}\n\n}\n```\n\n\n# Examples\n\n* [Nginx with Mysql](https://github.com/maxivak/docker-nginx-mysql-example)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxivak%2Fdocker-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxivak%2Fdocker-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxivak%2Fdocker-builder/lists"}