{"id":13587264,"url":"https://github.com/lovette/bootstrap-bash","last_synced_at":"2025-04-07T21:33:29.604Z","repository":{"id":1297225,"uuid":"1239254","full_name":"lovette/bootstrap-bash","owner":"lovette","description":"A simple server kickstart and software configuration tool that relies only on shell scripts and package managers.","archived":false,"fork":false,"pushed_at":"2023-05-19T16:22:47.000Z","size":354,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-02-13T21:46:28.576Z","etag":null,"topics":["bash","configuration-management","docker","linux","podman","shell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lovette.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}},"created_at":"2011-01-10T20:10:19.000Z","updated_at":"2023-10-03T09:31:13.000Z","dependencies_parsed_at":"2023-07-06T05:57:00.945Z","dependency_job_id":null,"html_url":"https://github.com/lovette/bootstrap-bash","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovette%2Fbootstrap-bash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovette%2Fbootstrap-bash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovette%2Fbootstrap-bash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lovette%2Fbootstrap-bash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lovette","download_url":"https://codeload.github.com/lovette/bootstrap-bash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247732840,"owners_count":20986936,"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":["bash","configuration-management","docker","linux","podman","shell"],"created_at":"2024-08-01T15:06:07.803Z","updated_at":"2025-04-07T21:33:24.588Z","avatar_url":"https://github.com/lovette.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# bootstrap-bash\n\nA simple server kickstart and software configuration tool.\n\n\nOverview\n---\nThere are a lot of ways to kickstart a server and manage software configurations.\nThe most basic (and probably most future-proof) is to rely only on shell scripts\nand package managers. This tool makes the task of configuring servers and software as easy\nas creating directories that contain shell scripts and files listing packages\nto install or remove.\n\nIf you're looking for more power or automation, have a look at these tools:\n\n* [Chef](https://www.chef.io/products/chef-infra)\n* [Puppet](https://puppet.com/)\n* [Ansible](https://www.ansible.com/)\n\n\n### Basic Example\n\nHere are the commands you might execute in a shell to build PHP CLI SAPI:\n\n\tcd /tmp\n\twget http://us.php.net/distributions/php-5.3.6.tar.gz\n\ttar xvfz php-5.3.6.tar.gz\n\tcd php-5.3.6\n\t./configure\n\tmake\n\tmake install\n\nOr, alongside regular shell commands, you can use some built-in convenience functions to get \nbetter error handling, progress output and an audit trail.\n\n\tbootstrap_file_wget  http://us.php.net/distributions/php-5.3.6.tar.gz /tmp/php-5.3.6.tar.gz\n\tbootstrap_file_untar /tmp/php-5.3.6.tar.gz /tmp/php-5.3.6 root:root\n\tbootstrap_build_exec /tmp/php-5.3.6 configure.out make ./configure\n\tbootstrap_build_make /tmp/php-5.3.6 make.out\n\tbootstrap_build_make /tmp/php-5.3.6 make-install.out install\n\nSave either set of commands to a file named `install.sh` in a directory\ncalled `php-cli` and you now have a \"module\" to build the PHP CLI SAPI.\nRepeat this process to create a module for each server component or software package\nyou want to manage and bootstrap-bash will take care of running specific\nmodules based on the selected server \"role\".\n\n\nRequirements\n---\n\n* [BASH 3.0 or later](http://www.gnu.org/software/bash/) or compatible shell\n\nWill not run on *macOS* because it does not (yet) support `readlink -f`.\n\n\nInstallation\n---\nDownload the archive and extract into a folder. Then, to install the package:\n\n\tmake install\n\nThis installs scripts to `/usr/sbin` and man pages to `/usr/share/man`.\nYou can also stage the installation with:\n\n\tmake DESTDIR=/stage/path install\n\nYou can undo the install with:\n\n\tmake uninstall\n\n\nBootstrap Containers\n---\n\n`bootstrap-bash` works well in containers as long as the runtime requirements are met. \nIt can be run directly from the source directory using a `RUN` statement such as:\n\n\tARG BOOTSTRAP_ROLE=database\n\n\tADD https://github.com/lovette/bootstrap-bash/archive/refs/heads/master.zip /root/bootstrap-bash.zip\n\n\tCOPY bootstrap-container /root/bootstrap-container\n\n\tRUN set -eux; \\\n\t\tapt-get update; \\\n\t\tunzip -q /root/bootstrap-bash.zip -d /root; \\\n\t\tbash /root/bootstrap-bash-master/src/bootstrap-bash.sh -y -c /root/bootstrap-container ${BOOTSTRAP_ROLE}; \\\n\t\trm -rf /root/bootstrap-bash.zip /root/bootstrap-bash-master /root/bootstrap-container; \\\n\t\trm -rf /var/lib/apt/lists/*\n\nOr use a multi-stage build to copy the source from a container image:\n\n\tARG BOOTSTRAP_ROLE=database\n\n\tCOPY --from=ghcr.io/lovette/bootstrap-bash:master /bootstrap-bash/src /usr/local/opt/bootstrap-bash\n\n\tCOPY bootstrap-container /root/bootstrap-container\n\n\tRUN set -eux; \\\n\t\tapt-get update; \\\n\t\tbash /usr/local/opt/bootstrap-bash/bootstrap-bash.sh -y -c /root/bootstrap-container ${BOOTSTRAP_ROLE}; \\\n\t\trm -rf /usr/local/opt/bootstrap-bash /root/bootstrap-container; \\\n\t\trm -rf /var/lib/apt/lists/*\n\n\nUsage\n---\n\n\tbootstrap-bash [OPTION]... -c CONFIGPATH [ROLE]\n\nRun the command with `--help` argument or see bootstrap-bash(8) for available OPTIONS.\n\n\nGetting Started\n---\nGetting started is easy.\n\n1. Create a configuration file (optional)\n2. Create a directory containing one or more modules\n3. Create a directory containing one or more roles (optional)\n\n\nConfiguration File\n---\nAn optional configuration file can be created to customize default configuration variables\nand define (and export) any other global variables that modules can reference.\nThis is a normal shell script that is sourced at runtime.\nIf the `-c` argument is a directory, a file named `bootstrap.conf` can be\nplaced in the directory or an `etc` subdirectory.\n\nThese default variables may be overridden if necessary:\n\n\tBOOTSTRAP_DIR_MODULES=\"/path/to/modules directory\"\n\tBOOTSTRAP_DIR_ROLES=\"/path/to/roles directory\"\n\tBOOTSTRAP_DIR_CACHE=\"/var/bootstrap-bash\"\n\tBOOTSTRAP_DIR_CACHE_RPM=\"$BOOTSTRAP_DIR_CACHE/rpms\"\n\tBOOTSTRAP_DIR_TMP=\"/tmp/bootstrap-bash-$$.tmp\"\n\n\nModules\n---\nEach available module must be a subdirectory below a root modules directory.\nEach module directory contains one or more files that control the installation,\nconfiguration and package management for the module.\n\n\tmodules/\n\t|- \u003cmodule name\u003e/\n\t|...\n\nIf you are not using roles and want to select a subset of defined modules you can create \na `modules.txt` in the root `modules` directory. \nTo control the modules selected for multiple roles, create a `roles` directory as outlined below.\n\n### Files\nEach module directory contains one or more shell scripts or text files that\ndefine the module operations.\n\n#### version.txt\n\nText file that provides metadata to describe the module.\n\n\tDescription: Module description\n\tVersion: 1.0\n\n#### preinstall.sh\n\nShell script to execute before modules are installed. This script is executed\nbefore package management and other module scripts.\nThis script is not executed if bootstrap-bash is run in update configurations mode.\n\n#### install.sh\n\nShell script with commands and functions to install the software related\nto the module. This script is executed after `preinstall.sh` and package management\nand before `config.sh`. This script is not executed if bootstrap-bash is run in\nupdate configurations mode.\n\n#### config.sh\n\nShell script to execute to configure module. This script is executed\nafter `install.sh`. Only this script is executed if bootstrap-bash is run in\nupdate configurations mode.\n\n#### yum-packages.txt\n\nText file listing Yum packages to install or remove. See Package Management for details.\n\n#### rpm-packages.txt\n\nText file listing RPM packages to install or remove. See Package Management for details.\n\n### Variables\n\nThe following global variables are available to `preinstall.sh`, `install.sh`\nand `config.sh` scripts:\n\n* `BOOTSTRAP_MODULE_NAME` - The name of the module being installed\n* `BOOTSTRAP_ROLE` - The active role being installed; can be blank.\n* `BOOTSTRAP_INCLUDE_TAGS` - The tags given to select modules, comma-delimited; can be blank.\n* `BOOTSTRAP_BASEARCH` - The server hardware (base) architecture (e.g. i386, x86_64)\n* `BOOTSTRAP_PROCARCH` - The server processor architecture (e.g. i686, x86_64)\n* `BOOTSTRAP_INSTALL_FORCED` - The install is being run for the first time or with the `-f` option\n* `BOOTSTRAP_DIR_LIB` - The directory with bootstrap library scripts\n* `BOOTSTRAP_DIR_ROLE` - The active roles directory\n* `BOOTSTRAP_DIR_MODULE` - The directory containing the active module install script\n* `BOOTSTRAP_DIR_MODULE_CACHE` - The directory where module installation state is saved\n* `BOOTSTRAP_DIR_TMP` - The directory where temporary files can be saved\n\n### Exit Status\n\nModule scripts must exit with a zero status if successful. A non-zero exit status\ncauses bootstrap-bash to stop execution. The default exit status of a script is that of\nthe last command executed, so an explicit call to `exit` is typically not required.\nYou can use the convenience function `bootstrap_die` to exit with an error message.\n\n\nRoles\n---\nYou can define \"roles\" to select the modules installed for particular a installation.\nDefine roles by creating a `roles` directory with a subdirectory for each role,\neach containing a `modules.txt`.\n\n\troles/\n\t|- \u003crole\u003e/\n\t   |-- \u003csubrole\u003e/\n\t   |...\n\nEach role directory can have subdirectories that define a \"subrole\".\nFor example, you could define the top-level roles \"development\" and \"public\".\nBeneath each of those roles you could have a subrole for each specific type of\nserver, such as \"web\" and \"database\".\n\nThe `modules.txt` file in each directory above a subrole will be applied when\na role is selected. This allows for common modules to be defined in parent role directories.\n\n### Files\n\nEach role directory contains a text file that defines the active modules for the role.\n\n#### modules.txt\n\nText file listing names of modules that will be applied for the role.\nThe following formats are accepted:\n\n\tmodule\n\t(module)\n\tmodule first|last|N\n\tmodule before|after module\n\nBlank lines and comment lines beginning with \"#\" will be ignored.\n\nOptional modules can be specified by enclosing the name within parenthesis.\nThese modules will only be installed when explicitly specified with `-m` option.\n\nThe default installation order is based on the order modules are listed in `modules.txt`.\nThe order can be explicitly controlled by assigning modules a relative order `N`.\nModules can be installed `first`, `last` or `before` or `after` another module.\nThis allows subroles to install modules before or after inherited modules.\n\nModules can also be associated with tags which can be used to filter selected modules.\n\n\tmodulea before moduleb (tag1,tag2,...)\n\n\nPackage Management\n---\nModules can contain text files defining package management operations.\n\nPackages are removed after they are added so dependencies on removed packages\ncan be fulfilled by new packages (as when replacing syslogd with rsyslogd).\nPackages without dependency management (ie. individual RPMs) are installed last\nso dependencies can be managed through a package manager.\n\n### YUM\n\n`yum-packages.txt` lists all packages that should be installed or removed with `yum`.\nThis will be skipped if `yum` command is not available.\n\n#### Packages\n\nEach line should contain the name of a package to install or remove.\nBlank lines and comment lines beginning with \"#\" will be ignored.\nPackages that should be removed must be prefixed with \"-\" (e.g. \"-package\").\nAll other lines in the file will be considered a package name and installed.\nPackages that need to be installed from a specific repository can be prefixed\nwith the repo name as: repo/package.\n\n#### Repositories\n\nYum repositories that packages are installed from can be added to `/etc/yum.repos.d`\nautomatically using the \"yum-repo-add:\" tag. This tag can either install an RPM to update\nthe repolist or copy a local file to yum.repos.d.\n\nAdd RPMs via a URL or local file with this syntax:\n\n\tyum-repo-add:\u003cURL or path\u003e.rpm\n\nAdd local files with this syntax:\n(If the path is relative, it will be prepended with the module directory.)\n\n\tyum-repo-add:\u003cpath\u003e.repo\n\nIf you need a custom repository that does not follow these conventions,\nyou can modify yum.repos.d with `preinstall.sh`.\n\n`yum-repo-add` statements and repo configuration text files can reference\nthe hardware architecture (e.g. i386, x86_64) with the tag {BOOTSTRAP_BASEARCH}\nor the processor architecture (e.g. i686, x86_64) with {BOOTSTRAP_PROCARCH}.\n\n### RPM\n\n`rpm-packages.txt` lists all packages that should be installed with `rpm` directly.\nThis will be skipped if `rpm` command is not available.\n\n\tPATH|URL [nodeps]\n\nEach line should contain the URL (HTTP or FTP) or local file path to a .rpm file.\n(If the path is relative, it will be prepended with the module directory.)\nNon-local RPMs will be downloaded with `wget` and saved to the directory\nspecified by BOOTSTRAP_DIR_CACHE_RPM.\n\nBlank lines and comment lines beginning with \"#\" will be ignored.\n\nThe file path or URL can be followed by the option \"nodeps\" to force the\ninstall without checking dependencies. These RPMs will be installed before\nother RPMs.\n\n### Other package management tools\n\nThe framework is not dependent on Yum and can easily be expanded to support\nother package management tools.\n\n\nHooks\n---\nModules can hook into various parts of the bootstrap process for further customization.\nHooks are enabled in the Configuration File by defining an array variable for each hook.\n\n* Modules listed in variable `BOOTSTRAP_HOOK_INSTALLPACKAGES` will have their\n  `installpackages-hook.sh` script executed after default package management\n  is complete.\n\n* Modules listed in variable `BOOTSTRAP_HOOK_BEFOREINSTALL` will have their\n  `beforeinstall-hook.sh` script executed prior to any modules being installed.\n\n* Modules listed in variable `BOOTSTRAP_HOOK_AFTERINSTALL` will have their\n  `afterinstall-hook.sh` script executed after all modules have been installed.\n\nFor example, to define modules that implement custom package management you would\ninclude this in your Configuration File:\n\n\tBOOTSTRAP_HOOK_INSTALLPACKAGES=( modulename [modulename] [...] )\n\nModules can use the convenience function `bootstrap_list_active_modules` to get\na list of the modules being installed.\n\nHook modules are normal modules and can be included in `modules.txt` with their\nown package management, installation and configuration scripts.\n\n\nOrder of operations\n---\n1.  Modules are enumerated based on role, unless specified on the command line\n2.  Module preinstall scripts are executed (preinstall.sh)\n3.  Yum repositories are updated (yum-packages.txt)\n4.  Yum packages are installed (yum-packages.txt)\n5.  Yum packages are removed (yum-packages.txt)\n6.  RPM packages are installed (rpm-packages.txt)\n7.  Install packages hook scripts are executed (installpackages-hook.sh)\n8.  Before-install hook scripts are executed (beforeinstall-hook.sh)\n9.  Module install scripts are executed (install.sh)\n10. After-install hook scripts are executed (afterinstall-hook.sh)\n11. Module configuration scripts are executed (config.sh)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovette%2Fbootstrap-bash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flovette%2Fbootstrap-bash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flovette%2Fbootstrap-bash/lists"}