Skip to content

Commit ec52c5b

Browse files
rahulrajaramrahulrajaram
authored
Merge pull request #5 from aws/BundledInstallerForUnix
Bundled installer for unix
2 parents 34de91a + 770391d commit ec52c5b

File tree

6 files changed

+409
-6
lines changed

6 files changed

+409
-6
lines changed

‎DEMO.png

450 KB
Loading

‎README.md

Lines changed: 167 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,171 @@
1-
## AWS Elastic Beanstalk CLI Setup
1+
## EBCLI Installer
22

3-
The EB CLI is a command line interface for Elastic Beanstalk that provides interactive commands that simplify creating, updating and monitoring environments from a local repository.
3+
------
44

5-
## License
5+
### 1. Overview
6+
7+
------
8+
9+
This repository hosts scripts to generate self-contained installations of the [EBCLI](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3.html).
10+
11+
------
12+
13+
### 2. Usage
14+
15+
------
16+
17+
#### 2.1. Clone this repository:
18+
19+
```bash
20+
git clone https://github.com/aws/aws-elastic-beanstalk-cli-setup.git
21+
```
22+
23+
#### 2.2. Install:
24+
25+
On Bash and Zsh:
26+
27+
```bash
28+
python aws-elasticbeanstalk-cli-setup/scripts/bundled_installer
29+
```
30+
31+
On PowerShell and CMD Prompt:
32+
33+
```bash
34+
python .\aws-elasticbeanstalk-cli-setup\scripts\bundled_installer
35+
```
36+
37+
#### 2.3. Post-installation activities:
38+
39+
The emitted output will contain instructions to add the EBCLI (and Python) executable to the shell's `$PATH` variable, if it is not already in it. Ensure you follow the steps emitted in the output.
40+
41+
#### 2.4. Demo execution of `bundled_installer`
42+
43+
![Demo](./DEMO.png)
44+
45+
### 3. Advanced usage:
46+
47+
To install the EBCLI, `bundled_installer` runs `ebcli_installer.py`. `ebcli_installer.py` has the following capabilities:
48+
49+
- to install a **specific version** of the EBCLI:
50+
51+
```bash
52+
python scripts/ebcli_installer.py --version 3.14.13
53+
```
54+
55+
- to install the EBCLI with a specific **version of Python** (such a `python` need not even exist in `$PATH`)
56+
57+
```bash
58+
python scripts/ebcli_installer.py --python-installation /path/to/some/python/on/your/computer
59+
```
60+
61+
- to install the EBCLI **from source** (Git repository, .tar, .zip)
62+
```bash
63+
python scripts/ebcli_installer.py --ebcli-source /path/to/awsebcli.zip
64+
65+
python scripts/ebcli_installer.py --ebcli-source /path/to/EBCLI/codebase/on/your/computer
66+
```
67+
- to install the EBCLI at a **specific location** rather than the standard `.ebcli-virtual-env` directory in the user's home.
68+
69+
```bash
70+
python scripts/ebcli_installer.py --location /path/to/ebcli/installation/location
71+
```
72+
73+
Run the following to view the help text associated with `ebcli_installer.py`:
74+
75+
```bash
76+
python scripts/ebcli_installer.py --help
77+
```
78+
79+
### 4. FAQs:
80+
81+
------
82+
83+
#### 4.1. Can I skip Python installation?
84+
85+
**Yes.** If you already have Python installed on your system, you can simply run the following after step `2.1.`:
86+
87+
On **Bash** and **Zsh**:
88+
89+
```bash
90+
python aws-elasticbeanstalk-cli-setup/scripts/ebcli_installer.py
91+
```
92+
93+
On **PowerShell** and **CMD Prompt**:
94+
95+
```bash
96+
python .\aws-elasticbeanstalk-cli-setup\scripts\ebcli_installer.py
97+
```
98+
99+
#### 4.2. For the **seasoned Python developer**, what is the advantage of this mode of installation over regular `pip` inside a `virtualenv`:
100+
101+
Even within a `virtualenv`, a developer might find the need to install multiple packages whose dependencies are in conflict. For instance, at various points in time, the AWSCLI and the EBCLI have been conflict with one another due to their dependency on `botocore`. [One such instance](https://github.com/aws/aws-cli/issues/3550) was particularly egregious. When there are conflicts, users have to bear the onus of managing separate virtualenvs for each of the conflicting packages, or find a combination of the packages devoid of conflicts. Both these workarounds become unmanageable over time and as the number of packages that are in conflict increases.
102+
103+
#### 4.3. On OS X (or Linux systems with `brew`), is this better than `brew install awsebcli`?
104+
105+
**Yes**, for a few reasons:
106+
107+
- the Beanstalk team does not have control over how `brew` operates. So installation problems will take time to fix as will general queries to be responded to.
108+
- the `brew install ...` mechanism does not solve the problem of dependency conflicts, which is a primary goal of this project.
109+
110+
#### 4.3. For the developers who are **new to Python**, does this mode of installation pose challenges?
111+
112+
The opinion of the Beanstalk team is "**No**".
113+
114+
Aside from the problem described in `3.2.`, developers new to Python are often confused by the presence of multiple Pythons, and `pip` executables on their system. A common problem that such developers encounter is where they install `eb` with one `pip` executable (presumably using the `sudo` prefix) only to find that only to find that no `eb`-related commands work because the correct set of directories is not properly referenced.
115+
116+
Normally, for such developers, usage of `virtualenv` is the correct path forward, however, this becomes yet another hurdle before executing with `eb`.
117+
118+
Another common problem is where users install Python and `pip` though means not recommended by AWS Documentation such as arbitrary PPAs on Ubuntu, or similar unmaintained sources that lack scrutiny.
119+
120+
#### 4.4. Can I execute the Bash scripts in a Cygwin, git-bash and other Bash-like shells on Windows?
121+
122+
**No**. At this time, we do not directly support execution on Bash-like environments on Windows. Please use PowerShell or CMD Prompt to install. You may add to `$PATH` the location of the `eb` and `Python` executables.
123+
124+
#### 4.5. Can I execute the Bash scripts in a `fish` shell?
125+
**Yes**, but only if you have Bash on your computer. At this time we do not provide specific guidance on how to set `$PATH` in Fish, however, Fish has [detailed documentation](https://fishshell.com/docs/current/tutorial.html#tut_path) for this purpose.
126+
127+
#### 4.6. I already have Python installed. Can I still execute `bundled_installer`?
128+
129+
**Yes**. It is safe to execute `bundled_installer` even if you already have a Python installed. The installer will simply skip reinstallation.
130+
131+
#### 4.7. I already have the EBCLI installed. Can I still execute `ebcli_installer.py`?
132+
133+
**Yes**.
134+
135+
There are two cases to consider:
136+
137+
- `ebcli_installer.py` was previously run, thereby creating `.ebcli-virtual-env` in the user's home directory (or the user's choice of a directory indicated through the `--location` argument). In this case, the EBCLI will simply overwrite `.ebcli-virtual-env` and attempt to install the latest version of the EBCLI in the virtualenv within it.
138+
139+
- `eb` is in `$PATH`, however, it was not installed by `ebcli_installer.py`. In this case, the installer will install `eb` within `.ebcli-virtual-env` in the user's home directory (or the user's choice of a directory indicated through the `--location` argument) and prompt the user to prefix `/path-to/.ebcli-virtual-env/executables` to `$PATH`. Until you perform this action, the older `eb` executable will continue to be referenced when you type `eb`.
140+
141+
#### 4.8. How does `ebcli_installer.py` work?
142+
143+
Upon executing the Python script, it will:
144+
145+
- create a virtualenv exclusive to the `eb` installation
146+
- install `eb` inside that virtualenv
147+
- generate inside the `<installation-location>/executables` directory:
148+
- a `.py` wrapper for `eb` on Linux/OS X
149+
- `.bat` and `.ps1` wrappers for `eb` on Windows
150+
- upon completion, you will be prompted to add `<installation-location>/executables` to `$PATH`, only if the directory is not already in it.
151+
152+
#### 4.8. How does `bundled_installer` work?
153+
154+
- On OS X/Linux, `bundled_installer` uses the extremely popular [`pyenv` project](https://github.com/pyenv/pyenv) to install the latest version of Python 3.7.
155+
- On Windows, it simply downloads the MSI installer of the latest Python from Python's website and silently installs it.
156+
157+
#### 4.9. Are there dependency problems that this mode of installation does not solve?
158+
159+
Unfortunately, **yes**.
160+
161+
Suppose the dependencies of `eb`, say `Dep A` and `Dep B` are in conflict. Because `pip` lacks dependency management capabilities, the resulting `eb` installation might be rendered defective.
162+
163+
#### 4.10. Is it okay to use Python 2.7 to install the EBCLI?
164+
165+
**Yes**, however, note that Python 2.7 will become deprecated on the 1st of January 2020, beyond which point, security updates will cease to come through.
166+
167+
Besides, the latest minor version series, Python 3.7, offers significant improvements over the Python 2.7 series, and it is highly recommended that you use Python 3.7 for the purposes of testing, even though the Beanstalk team tests the EBCLI against Python 2.7.
168+
169+
### 5. License
6170

7171
This library is licensed under the Mozilla Public License Version 2.0.

‎VERSION

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.1.0

‎scripts/bundled_installer

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
#!/usr/bin/env bash
2+
# ******************************************************************
3+
# ABOUT
4+
# ******************************************************************
5+
#
6+
# This script installs:
7+
#
8+
# - the latest (or close to it) Python
9+
# - the latest version of the EBCLI
10+
export PYTHON_VERSION="3.7.3"
11+
export PYENV_ROOT="$HOME/.pyenv"
12+
export PYENV_BIN="$PYENV_ROOT/versions/$PYTHON_VERSION/bin"
13+
14+
function change_to_scripts_directory() {
15+
SCRIPTS_DIRECTORY=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
16+
17+
cd "$SCRIPTS_DIRECTORY"
18+
}
19+
20+
function echo_with_colors_inverted()
21+
{
22+
MESSAGE=$1
23+
echo -e "\033[7m$MESSAGE\033[0m"
24+
}
25+
26+
function exit_if_return_code_is_non_zero() {
27+
if [[ $? -ne 0 ]] ; then
28+
echo_with_indentation "Exiting due to failure"
29+
30+
exit $?
31+
fi
32+
}
33+
34+
function install_python() {
35+
echo ""
36+
echo_with_colors_inverted "=============================================="
37+
echo_with_colors_inverted "I. Installing Python "
38+
echo_with_colors_inverted "=============================================="
39+
if [ -f python_installer ]; then
40+
./python_installer
41+
exit_if_return_code_is_non_zero
42+
fi
43+
}
44+
45+
function install_ebcli() {
46+
echo ""
47+
echo_with_colors_inverted "=============================================="
48+
echo_with_colors_inverted "II. Creating self-contained EBCLI installation"
49+
echo_with_colors_inverted "=============================================="
50+
if [ -f ebcli_installer.py ]; then
51+
${PYENV_BIN}/python ./ebcli_installer.py \
52+
--python-installation ${PYENV_BIN}/python \
53+
--virtualenv-executable ${PYENV_BIN}/virtualenv
54+
exit_if_return_code_is_non_zero
55+
fi
56+
}
57+
58+
change_to_scripts_directory
59+
install_python
60+
install_ebcli

‎scripts/ebcli_installer.py

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@
3535

3636
EBCLI_INSTALLER_STAMP = '.ebcli_installer_stamp'
3737

38+
PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
39+
with open(os.path.join(PROJECT_ROOT, 'VERSION')) as version_file:
40+
EBCLI_INSTALLER_VERSION = version_file.read().strip()
41+
3842

3943
EXECUTABLE_WRAPPERS = {
4044
'bat': '\n'.join(
@@ -725,7 +729,11 @@ def _parse_arguments():
725729
arguments passed by the user.
726730
"""
727731
parser = argparse.ArgumentParser(
728-
usage='python bundled_script.py [optional arguments]'
732+
description='EBCLI installer {}\n\n'
733+
'This program creates an isolated virtualenv solely meant for invoking '
734+
'`eb` within.'.format(EBCLI_INSTALLER_VERSION),
735+
usage='python {file_name} [optional arguments]'.format(file_name=__file__),
736+
formatter_class=argparse.RawTextHelpFormatter
729737
)
730738
parser.add_argument(
731739
'-e', '--virtualenv-executable',
@@ -738,7 +746,7 @@ def _parse_arguments():
738746
parser.add_argument(
739747
'-p', '--python-installation',
740748
help='path to the python installation under which to install the '
741-
'awsebcli and its dependencies'
749+
'awsebcli and its \ndependencies'
742750
)
743751
parser.add_argument(
744752
'-q', '--quiet',
@@ -747,7 +755,7 @@ def _parse_arguments():
747755
)
748756
parser.add_argument(
749757
'-s', '--ebcli-source',
750-
help='filesystem path to a Git repository of the EBCLI, or a .zip or .tar file of '
758+
help='filesystem path to a Git repository of the EBCLI, or a .zip or .tar file of \n'
751759
'the EBCLI source code; useful when testing a development version of the EBCLI.'
752760
)
753761
parser.add_argument(

0 commit comments

Comments
 (0)