Reorg

Move bulk of README.md to markdown directory, update TOC and relative URLs

Author: pythoninthegrass

README.md

@@ -0,0 +1,65 @@
+### asdf
+
+* Install from the [Setup](../README.md#setup) section
+* WSL/Ubuntu Linux dependencies
+    ```bash
+    sudo apt update && sudo apt install \
+    make build-essential libssl-dev zlib1g-dev \
+    libbz2-dev libreadline-dev libsqlite3-dev wget \
+    curl llvm libncursesw5-dev xz-utils tk-dev \
+    libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
+    ```
+* Fedora dependencies
+    ```bash
+    sudo dnf install -y bzip2-devel libsqlite3x-devel
+    ```
+* All operating systems
+    ```bash
+    # add python plugin
+    asdf plugin-add python
+
+    # install stable python
+    asdf install python latest
+
+    # uninstall version
+    asdf uninstall python 3.9.6
+
+    # refresh symlinks for installed python runtimes
+    asdf reshim python
+
+    # set stable to system python
+    asdf global python latest
+
+    # optional: local python (e.g., python 3.9.10)
+    cd $work_dir
+    asdf list-all python 3.9
+    asdf install python 3.9.10
+    asdf local python 3.9.10
+
+    # verify python shim in use
+    asdf current
+
+    # check installed python
+    asdf list python
+    ```
+
+#### Debugging
+**No version set for command python**
+* Make sure `python` or `python3` isn't aliased in `~/.bashrc` or `~/.zshrc`
+
+[bash - Is it possible to check where an alias was defined? - Unix & Linux Stack Exchange](https://unix.stackexchange.com/questions/322459/is-it-possible-to-check-where-an-alias-was-defined/544970#544970)
+
+##### PATH
+* `asdf`, `poetry`, and `python` all need to be sourced in your shell `$PATH` in a specific order
+  * `asdf` stores its Python shims in `~/.asdf/shims`
+  * `poetry` lives in `~/.local/bin`
+    ```bash
+    export ASDF_DIR="$HOME/.asdf"
+    export PATH="$ASDF_DIR/shims:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+    ```
+* Furthermore, any aliases or alias files need to be sourced as well
+    ```bash
+    . "$ASDF_DIR/asdf.sh"
+    . "$ASDF_DIR/completions/asdf.bash"
+    . /usr/local/etc/profile.d/poetry.bash-completion
+    ```

markdown/asdf.md

@@ -0,0 +1,28 @@
+### Django
+
+* Follow the official [Django Docker Compose article](https://docs.docker.com/samples/django/)
+    * `cd django`
+    * Generate the server boilerplate code
+        ```bash
+        docker-compose run web django-admin startproject composeexample .
+        ```
+    * Fix upstream import bug and whitelist all hosts/localhost
+        ```bash
+        $ vim composeexample/settings.py
+        import os
+        ...
+        ALLOWED_HOSTS = ["*"]
+        ```
+    * Profit
+        ```bash
+        docker-compose up
+        ```
+    * **Optional**: Comment out Django exclusions for future commits
+        * Assumed if extracting Django boilerplate from template and creating a new repo
+        ```bash
+        # .gitignore
+        # ETC
+        # django/composeexample/
+        # django/data/
+        # django/manage.py
+        ```

markdown/django.md

@@ -0,0 +1,33 @@
+### Docker
+
+* Install from the [Setup](../README.md#setup) section
+* Usage
+    ```bash
+    # clean build (remove `--no-cache` for speed)
+    docker-compose build --no-cache --parallel
+
+    # start container
+    docker-compose up --remove-orphans -d
+
+    # exec into container
+    docker attach hello
+
+    # run command inside container
+    python hello.py
+
+    # stop container
+    docker-compose stop
+
+    # destroy container and network
+    docker-compose down
+    ```
+
+#### Debugging
+* Watch logs in real-time: `docker-compose logs -tf --tail="50" hello`
+* Check exit code
+    ```bash
+    $ docker-compose ps
+    Name                          Command               State    Ports
+    ------------------------------------------------------------------------------
+    docker_python      python manage.py runserver ...   Exit 0
+    ```

markdown/docker.md

@@ -0,0 +1,52 @@
+### GitHub Actions
+
+#### Update submodules recursively
+* Add the submodule to the downstream repo
+    ```bash
+    git submodule add https://github.com/pythoninthegrass/automate_boring_stuff.git
+    git commit -m "automate_boring_stuff submodule"
+    git push
+    ```
+* Create a personal access token called `PRIVATE_TOKEN_GITHUB` with `repo` permissions on the downstream repo
+    * `repo:status`
+    * `repo_deployment`
+    * `public_repo`
+* Add that key to the original repo
+    * Settings > Security > Secrets > Actions
+    * New repository secret
+* Setup a new Action workflow
+    * Actions > New Workflow
+    * Choose a workflow > set up a workflow yourself
+    ```bash
+    # main.yml
+    # SOURCE: https://stackoverflow.com/a/68213855
+    name: Send submodule updates to parent repo
+
+    on:
+    push:
+        branches:
+        - main
+        - master
+
+    jobs:
+    update:
+        runs-on: ubuntu-latest
+
+        steps:
+        - uses: actions/checkout@v2
+            with:
+            repository: username/repo_name
+            token: ${{ secrets.PRIVATE_TOKEN_GITHUB }}
+
+        - name: Pull & update submodules recursively
+            run: |
+            git submodule update --init --recursive
+            git submodule update --recursive --remote
+        - name: Commit
+            run: |
+            git config user.email "actions@github.com"
+            git config user.name "GitHub Actions - update submodules"
+            git add --all
+            git commit -m "Update submodules" || echo "No changes to commit"
+            git push
+    ```

markdown/gh_actions.md

@@ -0,0 +1,48 @@
+### Kubernetes (k8s)
+
+* Easiest way to set up a local single node cluster is via one of the following:
+    * [Rancher Desktop](https://docs.rancherdesktop.io/getting-started/installation)
+    * [minikube](https://minikube.sigs.k8s.io/docs/start/)
+      * Incidentally, `minikube` ships with the Kubernetes Dashboard
+        ```bash
+        minikube dashboard
+        ```
+      * The boilerplate [Terraform plan](#terraform) below hasn't been tested against `minikube`
+    * [multipass](https://multipass.run/) with [microk8s](https://ubuntu.com/tutorials/getting-started-with-kubernetes-ha#1-overview)
+* Add aliases to `~/.bashrc` or `~/.zshrc`
+    ```bash
+    # k8s
+    alias k="kubectl"
+    alias kc="kubectl config use-context"
+    alias kns='kubectl config set-context --current --namespace'
+    alias kgns="kubectl config view --minify --output 'jsonpath={..namespace}' | xargs printf '%s\n'"
+    KUBECONFIG="$HOME/.kube/config:$HOME/.kube/kubeconfig:$HOME/.kube/k3s.yaml"
+    ```
+* CLI/TUI (terminal user interface) management of k8s
+  * [k9s](https://github.com/derailed/k9s#installation)
+    * Built-in help: type `?`
+    * Main Screen: `:pod`
+    ![Main screen](img/k9s_main.png)
+    * Describe a pod: `d`
+    ![Describe a pod](img/k9s_describe.png)
+    * Delete a pod:
+      * `ctrl-d`
+      * Replicas rebuild
+    ![Delete a pod](img/k9s_delete_pod.png)
+    * Remove resource (permanent)
+      * `:deploy`
+      * `ctrl-d`
+    ![Remove resource](img/k9s_remove_res.png)
+* [POC](https://itnext.io/simplest-minimal-k8s-app-tutorial-with-rancher-desktop-in-5-min-5481edb9a4a5)
+  ```bash
+  git clone https://github.com/jwsy/simplest-k8s.git
+  k config get-contexts                    # should have `rancher-desktop` selected
+  kc rancher-desktop                       # switch to rancher context if not
+  k create namespace simplest-k8s
+  k apply -n simplest-k8s -f simplest-k8s
+  k delete -n simplest-k8s -f simplest-k8s
+  k delete namespace simplest-k8s
+  ```
+  * Navigate to https://jade-shooter.rancher.localhost/ in Chrome
+  * Allow self-signed cert
+  * Profit 💸

markdown/kubernetes.md

@@ -0,0 +1,37 @@
+### MongoDB
+
+* See [Docker](#docker) section above
+* Setup empty DB as a detached container with port 27017 mapped
+    ```bash
+    # start mongodb docker container
+    docker run --name mongodb -d -p 27017:27017 mongo
+
+    # stop container
+    docker stop mongodb
+    ```
+* Access DB
+  * **GUI**: Install [MongoDB Compass](https://www.mongodb.com/try/download/compass)
+    ![compass](img/compass.png)
+  * **Shell**
+    ```bash
+    # install mongo client
+    asdf install mongodb latest
+
+    # open client with defaults (mongodb://localhost:27017)
+    mongo
+
+    # list databases
+    show dbs
+    ```
+  * **Python** (ayyyy)
+    ```python
+    # ./nosql/mongo/mongo_mvp.py
+    import pymongo
+
+    client = pymongo.MongoClient('mongodb://localhost:27017/')
+    db = client["music"]
+    collection = db["albums"]
+    data = { "artist": "Grimes", "album": "Miss Anthropocene" }
+    collection.insert_one(data)
+    client.close()
+    ```

markdown/mongo.md

@@ -0,0 +1,24 @@
+### pip
+
+If a basic virtual environment (`venv`) and `requirements.txt` are all that's needed, can use built-in tools.
+```bash
+# create a virtual environment via python
+## built-in
+python3 -m venv .venv
+
+## faster
+python3 -m pip install virtualenv # _or_ pipx install virtualenv
+virtualenv .venv
+
+# activate virtual environment
+source .venv/bin/activate
+
+# install dependencies
+python3 -m pip install requests inquirer
+
+# generate requirements.txt
+python3 -m pip freeze > requirements.txt
+
+# exit virtual environment
+deactivate
+```

markdown/pip.md

@@ -0,0 +1,34 @@
+### Pipx
+
+* Install
+    ```bash
+    # macOS
+    brew install pipx
+    pipx ensurepath
+
+    # Linux
+    python3 -m pip install --user pipx
+    python3 -m pipx ensurepath
+
+    # ~/.bashrc
+    eval "$(register-python-argcomplete pipx)"
+    export PIPX_DEFAULT_PYTHON="$ASDF_DIR/shims/python"
+    ```
+
+* Usage
+    ```bash
+    # install package
+    pipx install pycowsay
+
+    # list packages
+    pipx list
+
+    # run without install (i.e., npx)
+    pipx run pycowsay moooo!
+
+    # install a package then add a dependency
+    pipx install nox
+    pipx inject nox nox-poetry
+    ```
+
+[pipx](https://pypa.github.io/pipx/)

markdown/pipx.md

@@ -0,0 +1,21 @@
+### Playwright
+
+* Install from the [Setup](../README.md#setup) section
+* Usage
+    ```bash
+    # install
+    pip install --upgrade pip
+    pip install playwright
+    playwright install
+
+    # download new browsers (chromedriver, gecko)
+    npx playwright install
+
+    # generate code via macro
+    playwright codegen wikipedia.org
+    ```
+* If `asdf` gives you lip
+  ```bash
+  # No preset version installed for command playwright
+  asdf reshim python
+  ```