| 1 |
# Share content across dotfiles |
| 2 |
|
| 3 |
There are cases in which two or more dotfiles are very similar. For example, |
| 4 |
two files exporting environment variables for two projects built with the same |
| 5 |
technology (eg. two node.js web servers deployed on AWS). In these cases it's |
| 6 |
nice to share as much code as possible across the dotfiles by leveraging |
| 7 |
templating and merging them into the same dotfile in dotdrop's `dotpath`. Here |
| 8 |
are a few suggestions about how to achieve this: |
| 9 |
|
| 10 |
* [Brute force templating](#brute-force-templating) |
| 11 |
* [Profile variables](#profile-variables) |
| 12 |
* [Jinja macros](#jinja-macros) |
| 13 |
|
| 14 |
## Brute force templating |
| 15 |
|
| 16 |
The first approach is sheer use of templating and variables. |
| 17 |
In order to do this, we need to: |
| 18 |
|
| 19 |
1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`. |
| 20 |
2. Create two `dotfile` entries in `config.yaml`, both having the merged |
| 21 |
dotfile as `src`, but their own `dst`. |
| 22 |
|
| 23 |
Here we have an example: |
| 24 |
|
| 25 |
The merged dotfile in `dotpath` (`dotpath/projects/env`): |
| 26 |
```bash |
| 27 |
# .env |
| 28 |
|
| 29 |
{%@@ if _dotfile_key == 'server0-env' @@%} |
| 30 |
{%@@set aws_db_host = 'super-duper.host' @@%} |
| 31 |
{%@@set aws_db_port = 4521 @@%} |
| 32 |
{%@@ elif _dotfile_key == 'server1-env' @@%} |
| 33 |
{%@@set aws_db_host = 'cheaper.host' @@%} |
| 34 |
{%@@set aws_db_host = 9632 @@%} |
| 35 |
{%@@ endif @@%} |
| 36 |
|
| 37 |
export DB_HOST='{{@@ aws_db_host @@}}' |
| 38 |
export DB_PORT='{{@@ aws_db_port @@}}' |
| 39 |
``` |
| 40 |
|
| 41 |
Part of dotdrop `config.yaml` file: |
| 42 |
```yaml |
| 43 |
# config.yaml |
| 44 |
|
| 45 |
dotfiles: |
| 46 |
server0-env: |
| 47 |
src: projects/env |
| 48 |
dst: ~/projects/server0/.env |
| 49 |
server1-env: |
| 50 |
src: projects/env |
| 51 |
dst: ~/projects/server1/.env |
| 52 |
``` |
| 53 |
|
| 54 |
Installing the dotfile `server0-env` will create an environment file in |
| 55 |
`~/projects/server0/.env` with the following content: |
| 56 |
|
| 57 |
```bash |
| 58 |
# .env |
| 59 |
|
| 60 |
export DB_HOST='super-duper.host' |
| 61 |
export DB_PORT='4521' |
| 62 |
``` |
| 63 |
|
| 64 |
## Profile variables |
| 65 |
|
| 66 |
The previous method, albeit flexible, is a bit cumbersome for some use cases. |
| 67 |
For example, when the dotfiles belong to different profiles, the cleanest |
| 68 |
solution consists of using |
| 69 |
[profile variables](../config/config-profiles.md#profile-variables-entry). This is achieved by: |
| 70 |
|
| 71 |
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. |
| 72 |
2. Adding some variables in the merged dotfile via templating. |
| 73 |
3. Overriding them with different values in each profile via profile variables. |
| 74 |
4. Typically, making the dotfile `dst` dynamic, as different profiles need |
| 75 |
usually to deploy the dotfiles in different locations. |
| 76 |
|
| 77 |
**NOTE**: This technique does *not* require two different `dotfiles` entry in |
| 78 |
`config.yaml`. |
| 79 |
|
| 80 |
An example: |
| 81 |
|
| 82 |
The merged dotfile (`dotpath/projects/env`): |
| 83 |
```bash |
| 84 |
# .env |
| 85 |
|
| 86 |
export DB_HOST='{{@@ aws_db_host @@}}' |
| 87 |
export DB_PORT='{{@@ aws_db_port @@}}' |
| 88 |
``` |
| 89 |
|
| 90 |
Part of dotdrop `config.yaml` file: |
| 91 |
```yaml |
| 92 |
# config.yaml |
| 93 |
|
| 94 |
dotfiles: |
| 95 |
env: |
| 96 |
src: projects/env |
| 97 |
dst: '{{@@ server_path @@}}/.env' |
| 98 |
|
| 99 |
profiles: |
| 100 |
server0: |
| 101 |
dotfiles: |
| 102 |
- env |
| 103 |
variables: |
| 104 |
aws_db_host: super-duper.host |
| 105 |
aws_db_port: 4521 |
| 106 |
server_path: ~/projects/server0 |
| 107 |
|
| 108 |
server1: |
| 109 |
dotfiles: |
| 110 |
- env |
| 111 |
variables: |
| 112 |
aws_db_host: cheaper.host |
| 113 |
aws_db_port: 9632 |
| 114 |
server_path: ~/projects/server1 |
| 115 |
``` |
| 116 |
|
| 117 |
With this setup, installing the `server1` profile will create an environment |
| 118 |
file in `~/projects/server1/.env` with the following content: |
| 119 |
|
| 120 |
```bash |
| 121 |
# .env |
| 122 |
|
| 123 |
export DB_HOST='cheaper.host' |
| 124 |
export DB_PORT='9632' |
| 125 |
``` |
| 126 |
|
| 127 |
## Jinja macros |
| 128 |
|
| 129 |
Even though it has cleaner dotfiles, the profile-variable-based procedure can't |
| 130 |
be used in two scenarios: when the dotfiles belong to the same profile, and |
| 131 |
when variable values require some complex computations. In both cases, the brute |
| 132 |
force templating approach can be used, but in the latter one it also makes the |
| 133 |
dotfiles bloated with "bookkeeping" logic, thus hard to read. |
| 134 |
|
| 135 |
A solution for this relies in leveraging Jinja macros. This method is a |
| 136 |
variation of the brute force templating one where the merged dotfile is |
| 137 |
included from many different dotfiles in `dotpath` via Jinja macros rather |
| 138 |
than via many `dotfile` entries with the same `src` attribute. This way, the |
| 139 |
merged original dotfiles stays clean as in the profile variables solution |
| 140 |
because computations are in other files. |
| 141 |
|
| 142 |
The steps to achieve this are: |
| 143 |
|
| 144 |
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. |
| 145 |
2. Wrapping the whole content of the merged dotfile in a Jinja macro with the |
| 146 |
necessary parameters. |
| 147 |
3. Calling the macro in each original dotfile, computing the parameters there. |
| 148 |
|
| 149 |
**NOTE**: The merged dotfile will be empty, as it only contains a Jinja macro. |
| 150 |
If it needs to not be deployed, the `ignoreempty` entry can be set to |
| 151 |
`true` in `config.yaml`. |
| 152 |
|
| 153 |
As usual, an example: |
| 154 |
|
| 155 |
The merged dotfile in `dotpath` (`dotpath/projects/env`): |
| 156 |
```bash |
| 157 |
{%@@ macro env(db_host, db_port) @@%} |
| 158 |
# .env |
| 159 |
|
| 160 |
export DB_HOST='{{@@ db_host @@}}' |
| 161 |
export DB_PORT='{{@@ db_port @@}}' |
| 162 |
{%@@ endmacro @@%} |
| 163 |
``` |
| 164 |
|
| 165 |
Server0's environment file (`projects/server0/.env`): |
| 166 |
```jinja2 |
| 167 |
{%@@ from projects/env import env @@%} |
| 168 |
|
| 169 |
{%@@ set keyPieces = _dotfile_key.split('-') @@%} |
| 170 |
{%@@ if keyPieces[-1] == 'dbg' @@%} |
| 171 |
{%@@ set isLocal = keyPieces[-2] == 'local' @@%} |
| 172 |
{%@@ set remote_host = 'super-duper-dbg.host' |
| 173 |
if not isLocal |
| 174 |
else 'localhost' @@%} |
| 175 |
{%@@set aws_db_port = 3333 @@%} |
| 176 |
|
| 177 |
{%@@ elif keyPieces[-1] == 'dev' @@%} |
| 178 |
{%@@set aws_db_host = 'localhost' @@%} |
| 179 |
{%@@set aws_db_host = 4521 @@%} |
| 180 |
{%@@ endif @@%} |
| 181 |
|
| 182 |
{{@@ env(db_host, db_port) @@}} |
| 183 |
``` |
| 184 |
|
| 185 |
Server1's environment file (`projects/server1/.env`): |
| 186 |
```jinja2 |
| 187 |
{%@@ from projects/env import env @@%} |
| 188 |
|
| 189 |
{{@@ env('average-host.com', 9632) @@}} |
| 190 |
``` |
| 191 |
|
| 192 |
Part of dotdrop `config.yaml` file: |
| 193 |
```yaml |
| 194 |
# config.yaml |
| 195 |
|
| 196 |
dotfiles: |
| 197 |
server0-env-remote-dbg: |
| 198 |
src: projects/server0/.env |
| 199 |
dst: ~/projects/server0/.env.remote.dbg |
| 200 |
server0-env-local-dbg: |
| 201 |
src: projects/server0/.env |
| 202 |
dst: ~/projects/server0/.env.local.dbg |
| 203 |
server1-env: |
| 204 |
src: projects/server1/.env |
| 205 |
dst: ~/projects/server1/.env |
| 206 |
``` |
| 207 |
|
| 208 |
With this configuration, installing the dotfile `server0-env-local-dbg` will |
| 209 |
create an environment file in `~/projects/server0/.env.local.dbg` with the |
| 210 |
following content: |
| 211 |
|
| 212 |
```bash |
| 213 |
# .env |
| 214 |
|
| 215 |
export DB_HOST='localhost' |
| 216 |
export DB_PORT='3333' |
| 217 |
``` |