The Python package Cookiecutter assists in creating directory structure for whatever purpose you need such as for example a new Python project, an Ansible role or a docker-compose project - anything really that benefits from a unifirm reproducible directory structure. If you've ever wanted to put project structure best practices into version control then Cookiecutter's here to help.

Cookiecutter is governed by so-called Cookiecutter templates, most of its magic inside Cookiecutter templates happens via the Jinja2 template engine. You'll feel right at home if you're familiar with Ansible.

Repo layout

Each subdirectory in this repo is a Cookiecutter template, you'll recognize them from their telltale cookiecutter.json files. Directories usually also have a readme file explaining more about each individual template.

Get started

Get Cookiecutter like so:

pip install cookiecutter

Unfamiliar with Python and pip? Check out Developing further down to get started with a virtual environment.

When all is set execute a template like so, docker-compose as an example:

cookiecutter https://quico.space/Quico/py-cookiecutter-templates.git --directory 'docker-compose'

Cookiecutter prompts you for whatever info the template needs then generates files and directories.

This is Cookiecutter prompting for info:

project_slug [dir-name]: grafana
service [grafana]:
component_list [grafana]: grafana,nginx
Select build:
1 - no
2 - yes
Choose from 1, 2 [1]:

The end result is a directory structure that has everything you need to hit the ground running.

.
└── grafana
    ├── build-context
    │   ├── grafana
    │   │   ├── docker-data
    │   │   │   └── .gitkeep
    │   │   ├── Dockerfile
    │   │   └── extras
    │   │       └── .gitkeep
    │   └── nginx
    │       ├── docker-data
    │       │   └── .gitkeep
    │       ├── Dockerfile
    │       └── extras
    │           └── .gitkeep
    ├── common-settings.yaml
    ├── compose.override.yaml
    ├── compose.yaml
    ├── env
    │   └── fqdn_context.env.example
    └── README.md

Developing

To change Cookiecutter templates get yourself an environment then make, test and commit your changes. First things first, the environment.

Environment

Get yourself a Python virtual environment. In this example we're assuming you're running a Linux operating system and you'll be using pyenv to manage virtual environments.

pyenv

Install pyenv with what they are calling their automatic installer. Feel free to also read up on pyenv on their GitHub project page.
```
curl https://pyenv.run | bash
```

Following the installer's instruction add at least the following commands to your ~/.bashrc file

export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

You will also likely want to add this line which will make sure pyenv auto-activates venvs when you navigate into certain directories. More on that down at venv.
```
eval "$(pyenv virtualenv-init -)"
```
Also make sure ~/.bashrc gets loaded for example by including this in a ~/.bash_profile file
```
[[ -f ~/.bashrc ]] && . ~/.bashrc
```
Reload ~/.bashrc
```
source ~/.bashrc
```

Python

Update pyenv's package list
```
pyenv update
```

Pick a Python version you like, for example copy-paste 3.11.4:

pyenv install --list | less

...
3.10.12
3.11.0
3.11-dev
3.11.1
3.11.2
3.11.3
3.11.4
3.12.0b2
3.12-dev
3.13-dev
...

Install Python, wait for compilation to finish on your machine
```
pyenv install 3.11.4
```

Repo

Clone this repo

git clone https://quico.space/Quico/py-cookiecutter-templates.git ~/py-cookiecutter-templates

venv

Create a virtual environment where 3.11.4 is the Python version you want to use in this venv and cookiecutter-3.11.4 is the name of your venv. Adding or dropping the Python version from your venv name comes down to personal preference.
```
pyenv virtualenv 3.11.4 cookiecutter-3.11.4
```
In your repo path ~/py-cookiecutter-templates create a .python-version file to tell pyenv to always activate your desired venv when inside this dir.
```
cd ~/py-cookiecutter-templates
pyenv local cookiecutter-3.11.4
```
pyenv will immediately prefix your shell's ${PS1} prompt with the venv name.
```
(cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ 
```
It will deactivate the venv and drop its prefix as soon as you navigate out of this dir.
```
(cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ cd
[✔ 23:19 user@machine ~]$ 
```
For now though stay in ~/py-cookiecutter-templates, you're going to want to pip-install cookiecutter.
Upgrade pip
```
pip install --upgrade pip
```
Install cookiecutter
```
pip install cookiecutter
```

All done, your environment is set up.

Change

Make some code changes, for example to the Docker Compose Cookiecutter template. When you're happy run your local Cookiecutter template to see how your changes are rendering.

Create /tmp/cookiecutter-docker-compose

mkdir '/tmp/cookiecutter-docker-compose'

Render a Docker Compose directory into your output directory, answer Cookiecutter's prompts:

# cookiecutter ~/py-cookiecutter-templates \
    --directory docker-compose \
    --output-dir /tmp/cookiecutter-docker-compose

project_slug [dir-name]: mydir
service [mydir]: myservice
component_list [myservice]: mycomponent_one,mycomponent_two
Select build:
1 - no
2 - yes
Choose from 1, 2 [1]: 2

Observe that in /tmp/cookiecutter-docker-compose you now have your rendered Docker Compose dir:

# tree -a .

.
└── mydir
    ├── build-context
    │   ├── mycomponent_one
    │   │   ├── docker-data
    │   │   │   └── .gitkeep
    │   │   ├── Dockerfile
    │   │   └── extras
    │   │       └── .gitkeep
    │   └── mycomponent_two
    │       ├── docker-data
    │       │   └── .gitkeep
    │       ├── Dockerfile
    │       └── extras
    │           └── .gitkeep
    ├── common-settings.yaml
    ├── compose.override.yaml
    ├── compose.yaml
    ├── env
    │   └── fqdn_context.env.example
    └── README.md

For rapid testing you will most likely want to not type prompt answers repeatedly. Give them as command line arguments instead, also specify --no-input to suppress prompts:

cookiecutter ~/py-cookiecutter-templates \
    --no-input \
    --directory docker-compose \
    --output-dir /tmp/cookiecutter-docker-compose \
    project_slug=mydir \
    service=myservice \
    component_list=mycomponent_one,mycomponent_two \
    build=yes

Commit prep

When you're about ready to commit changes into this repo check the following bullet points.

Did you update the Cookiecutter template README.md file, here for example for Docker Compose?
- Change in behavior?
- An updated example directory layout?
- Updated example file content?
Did you commit a new completely rendered example directory structure into docker-compose/examples dir?
Did you change something that affects existing example directories? If so rerender them.