Debian Codegraph @

docs/howto/sharing-content.md

raw
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 ```