-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathguide.html
More file actions
499 lines (469 loc) · 36.7 KB
/
guide.html
File metadata and controls
499 lines (469 loc) · 36.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using Rootbox — Rootbox 0.1 documentation</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-material/css/bootstrap-material-design.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-material/css/ripples.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-material/js/material.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-material/js/ripples.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
</head>
<body>
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
Rootbox</a>
<!-- <span class="navbar-text navbar-version pull-left"><b>0.1</b></span> -->
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li>
<a href="#">
Guide
<div class="ripple-container"></div>
</a>
</li>
<li>
<a href="https://github.com/project-rootbox/rootbox">
GitHub
<div class="ripple-container"></div>
</a>
</li>
<!-- No global TOC -->
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-12 content">
<div class="section" id="using-rootbox">
<h1>Using Rootbox<a class="headerlink" href="#using-rootbox" title="Permalink to this headline">¶</a></h1>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>Rootbox requires two things:</p>
<ul class="simple">
<li>A Linux system. Some others Unixes (like the BSDs) may work, but they’re
untested.</li>
<li>An file system with sparse file support to store the workspace directory (see
below). Rootbox relies on the magic of sparse files to easily create boxes and
images. (Note that only ext4 has been tested.)</li>
</ul>
<p>Also, here’s something import:</p>
<p><strong>ROOTBOX IS NOT SECURE.</strong></p>
<p>Let me repeat:</p>
<p><strong>ROOTBOX IS NOT SECURE.</strong></p>
<p>Third time’s the charm:</p>
<p><strong>ROOTBOX IS NOT SECURE.</strong></p>
<p>Rootbox’s “boxes” are not intended to be used like you would use containers.
They <em>are</em> designed to be created and easily distributed and portable
development environments, but they are <em>not</em> designed for running web servers or
untrusted code. Use containers for that!</p>
</div>
<div class="section" id="getting-started">
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>Just run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">curl</span> <span class="o">-</span><span class="n">L</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">goo</span><span class="o">.</span><span class="n">gl</span><span class="o">/</span><span class="n">H3OpCL</span> <span class="o">|</span> <span class="n">sudo</span> <span class="n">sh</span>
</pre></div>
</div>
<p>If you’re not confortable with running random internet scripts, you can also
install it from GitHub instead:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">project</span><span class="o">-</span><span class="n">rootbox</span><span class="o">/</span><span class="n">rootbox</span><span class="o">.</span><span class="n">git</span>
<span class="n">cd</span> <span class="n">rootbox</span>
<span class="n">sudo</span> <span class="n">sh</span> <span class="n">install</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>Once that’s done, you need to initialize the Rootbox workspace directory, which
is where all your images and boxes will be stored. You can do so using
<code class="docutils literal"><span class="pre">rootbox</span> <span class="pre">init</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">init</span>
</pre></div>
</div>
<p>This will initialize Rootbox in <code class="docutils literal"><span class="pre">$HOME/.rootbox</span></code>. If you want to use a
different directory, just say so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">init</span> <span class="n">my_directory</span>
</pre></div>
</div>
<p>This will create the directory and symlink it to <code class="docutils literal"><span class="pre">$HOME/.rootbox</span></code>.</p>
<p>Note that, as already mentioned above, <strong>this directory must be on a file system
with sparse file support</strong>!</p>
<p>If at any point in the future, you want to use a different workspace directory,
you’ll need to pass <code class="docutils literal"><span class="pre">-f</span></code> to force the reinitialization.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do <strong>NOT</strong> tamper with the workspace directory! By that, I mean don’t go
touching it in any way. Remember when I said that Rootbox uses sparse files?
Well, that means that, if you try to play with the directory or copy/move
files outside of it, there’s a chance all the sparse files will inflate to
their full 128 GB size. Ouch!!</p>
</div>
</div>
<div class="section" id="concepts">
<h2>Concepts<a class="headerlink" href="#concepts" title="Permalink to this headline">¶</a></h2>
<p>Before we continue, I’d like to introduce some terms you’ll see floating around
this document:</p>
<ul class="simple">
<li><strong>workspace</strong>: As mention above, this is the directory where Rootbox will save
all your images and boxes (see below) into.</li>
<li><strong>boxes</strong>: Boxes are essentially Rootbox’s version of containers. They hold
an <a class="reference external" href="https://alpinelinux.org/">Alpine Linux</a> installation, as well as
whatever else you want to put in them. Note that, unlike containers, boxes are
intentionally insecure, and they aren’t intended to be used for everything
that one might use containers for.</li>
<li><strong>images</strong>: Every box is base on an <em>image</em>. Images are just vanilla,
unmodified Alpine Linux installations.</li>
<li><strong>bind mounts</strong>: These allow you to “mount” external directories inside your
boxes.</li>
</ul>
<p>Got that? Let’s go on!</p>
</div>
<div class="section" id="creating-an-image">
<h2>Creating an image<a class="headerlink" href="#creating-an-image" title="Permalink to this headline">¶</a></h2>
<p>As already mentioned, images are unmodified installations of Alpine Linux, ready
to be converted to a box when desired. They’re easy to create:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">image</span><span class="o">.</span><span class="n">add</span> <span class="mf">3.5</span>
</pre></div>
</div>
<p>Here, we’re using Alpine Linux 3.5, as passed to the version argument. Note that
the resulting image will be around 210 MB in size. This seems rather big, but
it also contains several development tools and libraries, such as GCC,
libstdc++, git, and more. If you want just a plain Alpine Linux installation,
then you can also pass <code class="docutils literal"><span class="pre">-s</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">image</span><span class="o">.</span><span class="n">add</span> <span class="mf">3.5</span> <span class="o">-</span><span class="n">s</span>
</pre></div>
</div>
<p>This will create a <em>slim</em> or <em>nodev</em> image, which is significantly lighter
(around ~13 MB in size) but doesn’t contain development tools inside. When you
create a slim image, you can later reference using <code class="docutils literal"><span class="pre">VERSION-nodev</span></code>, like
<code class="docutils literal"><span class="pre">3.5-nodev</span></code>.</p>
<p>(You can also use <code class="docutils literal"><span class="pre">image.list</span></code> to list all your installed images and
<code class="docutils literal"><span class="pre">image.remove</span> <span class="pre">-v</span> <span class="pre">VERSION</span></code> to remove one of your images.)</p>
</div>
<div class="section" id="creating-a-box">
<h2>Creating a box<a class="headerlink" href="#creating-a-box" title="Permalink to this headline">¶</a></h2>
<p>Creating a new box is easy:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>Here, we’re creating a box called <em>mybox</em>, using the Alpine Linux 3.5 image that
was created earlier. If you want to use a different image instead, use <code class="docutils literal"><span class="pre">-v</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">v</span> <span class="mf">3.4</span>
</pre></div>
</div>
<p>(To use the slim/nodev image, pass <code class="docutils literal"><span class="pre">-v</span> <span class="pre">3.5-nodev</span></code> instead.)</p>
<p>You can also pass a list of bind mounts to be mounted whenever the box is run.
For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="n">outside_directory</span><span class="o">///</span><span class="n">inside_directory</span>
</pre></div>
</div>
<p>Now, whenever this box is run <code class="docutils literal"><span class="pre">outside_directory</span></code> will appear inside it as
<code class="docutils literal"><span class="pre">/inside_directory</span></code>. For instance, if you always want the current directory
to be mounted inside the box as <code class="docutils literal"><span class="pre">/cwd</span></code>, you could run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="o">-</span><span class="n">n</span> <span class="n">mybox</span> <span class="o">.///</span><span class="n">cwd</span>
</pre></div>
</div>
<p>Absolute paths can be used, too:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>rootbox box.new -n mybox /home/$USER///external_home
</pre></div>
</div>
</div>
<div class="section" id="running-your-boxes">
<h2>Running your boxes<a class="headerlink" href="#running-your-boxes" title="Permalink to this headline">¶</a></h2>
<p>Now that a box has been created, let’s run it!</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">run</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>This will put you inside an <code class="docutils literal"><span class="pre">ash</span></code> shell inside your box. Take a look around
for a bit! Once you’re done, you can Ctrl-D out of it.</p>
<p>Just like above, bind mounts can be created when the box is run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">run</span> <span class="n">mybox</span> <span class="o">.///</span><span class="n">cwd</span>
</pre></div>
</div>
<p>These will be mounted in addition to any specified when creating the box for the
first time.</p>
<p>While inside the box, you can also install packages using the Alpine package
manager,
<a class="reference external" href="https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management">apk</a>, like
this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apk</span> <span class="n">add</span> <span class="n">clang</span>
</pre></div>
</div>
<p>A command can also be passed via the command line:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">run</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">c</span> <span class="s1">'echo 123'</span>
</pre></div>
</div>
<p>If you’re planning on running X11 applications inside your box, you’ll need to
pass <code class="docutils literal"><span class="pre">-x</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">run</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">x</span>
</pre></div>
</div>
<p>(Note that you may also need to run <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apk</span> <span class="pre">add</span> <span class="pre">font-adobe-100dpi</span></code> if you
run into problems involving missing fonts, e.g. you get boxes instead of text
in your programs.)</p>
</div>
<div class="section" id="box-factories">
<h2>Box factories<a class="headerlink" href="#box-factories" title="Permalink to this headline">¶</a></h2>
<p>Factories are an imporant concept in Rootbox! A box factory is just a shell
script that’s run inside your box upon creation to set things up. For instance,
you could create a factory <code class="docutils literal"><span class="pre">clang.sh</span></code> containing:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>sudo apk add clang
</pre></div>
</div>
<p>To create a box using your factory, you can just run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">clang</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">-f</span></code> takes a path to your box factory. However, things get fancier than that!</p>
<p>You can have one factory depend on another one. For instance, you might have
<code class="docutils literal"><span class="pre">llvm.sh</span></code> to install llvm:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>sudo apk add llvm
</pre></div>
</div>
<p>Then, <code class="docutils literal"><span class="pre">clang.sh</span></code> could be modified to read:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span><span class="c1">#:DEPENDS llvm.sh</span>
sudo apk add clang
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">#:DEPENDS</span></code> means that <code class="docutils literal"><span class="pre">llvm.sh</span></code> must be run first. Now, when you use
<code class="docutils literal"><span class="pre">clang.sh</span></code> as your box factory, <code class="docutils literal"><span class="pre">llvm.sh</span></code> will be run, too!</p>
<p>Box factories can also specify Alpine Linux versions that they work on:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span><span class="c1">#:VERSION 3.5 3.5-nodev</span>
</pre></div>
</div>
<p>This factory will run under 3.5 and 3.5-nodev, but if you try to use it on an
Alpine 3.4 box, Rootbox won’t let you.</p>
</div>
<div class="section" id="using-factories-from-the-internet">
<h2>Using factories from the internet<a class="headerlink" href="#using-factories-from-the-internet" title="Permalink to this headline">¶</a></h2>
<p>If things weren’t already awesome enough, you can load your factories straight
from the web or Git. If you have a factory up at GitHub, you could use it via:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">myuser</span><span class="o">/</span><span class="n">myrepo</span><span class="o">@</span><span class="nd">@mybranch</span><span class="o">///</span><span class="n">myfactory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>If <code class="docutils literal"><span class="pre">@@mybranch</span></code> is ommited, it defaults to <em>master</em>. If <code class="docutils literal"><span class="pre">///myfactory.sh</span></code>
is ommited, it defaults to <code class="docutils literal"><span class="pre">factory.sh</span></code>. For instance, to load <code class="docutils literal"><span class="pre">factory.sh</span></code>
from <code class="docutils literal"><span class="pre">CoolRootboxScripts/cool_scripts_set_1</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">CoolRootboxScripts</span><span class="o">/</span><span class="n">cool_scripts_set_1</span>
</pre></div>
</div>
<p>To use <code class="docutils literal"><span class="pre">my_other_factory.sh</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">CoolRootboxScripts</span><span class="o">/</span><span class="n">cool_scripts_set_1</span><span class="o">///</span><span class="n">my_other_factory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>To use it from the branch <code class="docutils literal"><span class="pre">devel</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">CoolRootboxScripts</span><span class="o">/</span><span class="n">cool_scripts_set_1</span><span class="o">@</span><span class="nd">@devel</span><span class="o">///</span><span class="n">my_other_factory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>GitLab is supported, too:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">gitlab</span><span class="p">:</span><span class="n">MyGitlabUser</span><span class="o">/</span><span class="n">my_gitlab_repo</span><span class="o">@</span><span class="nd">@branch</span><span class="o">///</span><span class="n">factory_name</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>as well as any other plain old Git repository:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">whatever</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">my_repo</span><span class="o">.</span><span class="n">git</span><span class="o">@</span><span class="nd">@branch</span><span class="o">///</span><span class="n">factory_name</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>In fact, factories can be pulled from anywhere on the internet:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">f</span> <span class="n">url</span><span class="p">:</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">mysite</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">some_cool_factory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>The syntax this time is a bit different: the url must point to an absolute URL
to the factory. If the URL ends with a slash (<code class="docutils literal"><span class="pre">/</span></code>), then <code class="docutils literal"><span class="pre">factory.sh</span></code> will
be appended to it.</p>
<p>These location formats can be used inside the <code class="docutils literal"><span class="pre">DEPENDS</span></code> section of a script,
too. You could have something like this:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span><span class="c1"># This is my cool factory script!</span>
<span class="c1">#:DEPENDS git:myuser/myrepo///myfactory.sh</span>
<span class="c1">#:DEPENDS url:rootbox_factories.com/myotherfactory.sh</span>
</pre></div>
</div>
<p>There are several pre-made factories in the still-growing
<cite>rootbox-factories <https://github.com/project-rootbox/rootbox-factories></cite>
repository. If you have a really cool idea for a factory that you figure would
be useful to a lot of people, you can open up an issue there as a request.</p>
</div>
<div class="section" id="managing-exporting-and-importing-your-boxes">
<h2>Managing, exporting, and importing your boxes<a class="headerlink" href="#managing-exporting-and-importing-your-boxes" title="Permalink to this headline">¶</a></h2>
<p>If you want to see a list of all the boxes that have been installed, just run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">list</span>
</pre></div>
</div>
<p>You can get info about an individual box with <code class="docutils literal"><span class="pre">box.info</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">info</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>Boxes can be cloned:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">clone</span> <span class="n">source_box</span> <span class="n">new_box</span>
</pre></div>
</div>
<p>and deleted:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">remove</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>If you want to change your a box’s settings later on, you can use
the <code class="docutils literal"><span class="pre">box.update</span></code> command set. For instance, you can use <code class="docutils literal"><span class="pre">box.update.binds</span></code>
to update a box’s default bind mounts:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">update</span><span class="o">.</span><span class="n">binds</span> <span class="n">mybox</span> <span class="n">a</span><span class="o">///</span><span class="n">b</span> <span class="c1"># Add a///b to the default bind mounts.</span>
<span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">update</span><span class="o">.</span><span class="n">binds</span> <span class="n">mybox</span> <span class="o">^</span><span class="n">a</span><span class="o">///</span><span class="n">b</span> <span class="c1"># Remove it from the default bind mounts.</span>
</pre></div>
</div>
<p>As you can see, prefixing a bind with <code class="docutils literal"><span class="pre">^</span></code> will remove it instead of adding it.</p>
<p>Similarly, <code class="docutils literal"><span class="pre">box.update.factory</span></code> can be used to run another factory once the
box has already been created:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">update</span><span class="o">.</span><span class="n">factory</span> <span class="n">mybox</span> <span class="n">url</span><span class="p">:</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span><span class="o">/</span><span class="n">myfactory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
</div>
<div class="section" id="exporting-and-importing-your-boxes">
<h2>Exporting and importing your boxes<a class="headerlink" href="#exporting-and-importing-your-boxes" title="Permalink to this headline">¶</a></h2>
<p>Boxes can be exported using <code class="docutils literal"><span class="pre">box.dist</span></code>. It works much like you’d expect by
now:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">dist</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>The default file name is <code class="docutils literal"><span class="pre"><your_box_name>.box</span></code>. In this case, it’ll be
<code class="docutils literal"><span class="pre">mybox.box</span></code>. That can be overriden, of course:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">dist</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">o</span> <span class="n">my_custom_name</span><span class="o">.</span><span class="n">box</span>
</pre></div>
</div>
<p>In addition, you can apply compression using <code class="docutils literal"><span class="pre">-c</span></code> to make it a bit smaller:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">dist</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">o</span> <span class="n">gzip_compressed</span><span class="o">.</span><span class="n">box</span><span class="o">.</span><span class="n">gz</span> <span class="o">-</span><span class="n">c</span> <span class="n">gzip</span>
<span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">dist</span> <span class="n">mybox</span> <span class="o">-</span><span class="n">o</span> <span class="n">bzip2_compressed</span><span class="o">.</span><span class="n">box</span><span class="o">.</span><span class="n">bz2</span> <span class="o">-</span><span class="n">c</span> <span class="n">bzip2</span>
</pre></div>
</div>
<p>Boxes can also be imported:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="kn">import</span> <span class="nn">mybox.box.gz</span> <span class="n">mybox</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal"><span class="pre">mybox.box.gz</span></code> is being imported using the name <code class="docutils literal"><span class="pre">mybox</span></code>. In fact,
boxes can be imported from virtually anywhere, using the exact same syntax as
used with box factories:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="kn">import</span> <span class="nn">url</span><span class="p">:</span><span class="n">rootbox_storage</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="mi">1234567</span> <span class="n">mybox</span>
<span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="kn">import</span> <span class="nn">git</span><span class="p">:</span><span class="n">Cooluser101</span><span class="o">/</span><span class="n">myboxes</span><span class="o">///</span><span class="n">cool_stuff</span><span class="o">.</span><span class="n">box</span> <span class="n">mybox</span>
</pre></div>
</div>
</div>
<div class="section" id="some-examples">
<h2>Some examples<a class="headerlink" href="#some-examples" title="Permalink to this headline">¶</a></h2>
<div class="section" id="building-c">
<h3>Building C<a class="headerlink" href="#building-c" title="Permalink to this headline">¶</a></h3>
<p>Donald wants to create a box that can be used to statically compile his C
programs. Alpine Linux is great for static linking:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">static_c</span> <span class="o">.///</span><span class="n">cwd</span>
<span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">run</span> <span class="n">static_c</span>
<span class="c1"># Inside the box...</span>
<span class="n">cd</span> <span class="o">/</span><span class="n">cwd</span>
<span class="n">echo</span> <span class="s1">'int main() </span><span class="si">{}</span><span class="s1">'</span> <span class="o">></span> <span class="n">x</span><span class="o">.</span><span class="n">c</span>
<span class="n">gcc</span> <span class="o">-</span><span class="n">static</span> <span class="o">-</span><span class="n">o</span> <span class="n">x</span> <span class="n">x</span><span class="o">.</span><span class="n">c</span>
<span class="n">exit</span>
<span class="c1"># Back outside again...</span>
<span class="n">ldd</span> <span class="n">x</span> <span class="c1"># statically linked</span>
</pre></div>
</div>
</div>
<div class="section" id="building-nim">
<h3>Building Nim<a class="headerlink" href="#building-nim" title="Permalink to this headline">¶</a></h3>
<p>Mary wants to create a box designed for building Nim programs. She can use
factories to automate…everything:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span>sudo apk add xz linenoise-dev libexecinfo-dev
curl -L https://nim-lang.org/download/nim-0.16.0.tar.xz -o nim.txz
tar xvf nim.txz
<span class="nb">cd</span> nim-0.16.0
./build.sh
bin/nim c koch
./koch boot -d:release -d:useLinenoise
sudo ./koch install /usr/local/bin
</pre></div>
</div>
<p>She can save this to <code class="docutils literal"><span class="pre">nim-factory.sh</span></code>. Then, to create her image, she can
just run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">nim</span> <span class="o">.///</span><span class="n">cwd</span> <span class="o">-</span><span class="n">f</span> <span class="n">nim</span><span class="o">-</span><span class="n">factory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>If she uploads her Nim factory to GitHub in <code class="docutils literal"><span class="pre">mary123/factories</span></code>, someone else
can use it, too:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">rootbox</span> <span class="n">box</span><span class="o">.</span><span class="n">new</span> <span class="n">nim</span> <span class="o">.///</span><span class="n">cwd</span> <span class="o">-</span><span class="n">f</span> <span class="n">git</span><span class="p">:</span><span class="n">mary123</span><span class="o">/</span><span class="n">factories</span><span class="o">///</span><span class="n">nim</span><span class="o">-</span><span class="n">factory</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>If Robby wants to build a Nim program using Rootbox, he can create a factory,
too:</p>
<div class="highlight-shell"><div class="highlight"><pre><span></span><span class="c1">#:DEPENDS git:mary123/factories///nim-factory.sh</span>
git clone https://github.com/bobby456/my-nim-program.git
<span class="nb">cd</span> my-nim-program
nim c my-program.nim
sudo cp my-program /usr/local/bin
</pre></div>
</div>
</div>
</div>
<div class="section" id="closing-thoughts">
<h2>Closing thoughts<a class="headerlink" href="#closing-thoughts" title="Permalink to this headline">¶</a></h2>
<p>Rootbox is still in the beta stages. If you notice anything isn’t working quite
correctly, feel free to report it to the
<a class="reference external" href="https://github.com/project-rootbox/rootbox/issues/new">GitHub repo</a>.</p>
<p>Have fun playing with your boxes!!!</p>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
<br/>
<div id="sourcelink">
<a href="_sources/guide.rst.txt"
rel="nofollow">Source<div class="ripple-container"></div></a>
</div>
</p>
<p>
© Copyright 2017, Ryan Gonzalez.<br/>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.5.<br/>
</p>
</div>
</footer>
<script>$.material.init();</script>
</body>
</html>