Fossil SCM
Changed several of the Docker environment variables to build arguments so the user an override them at build time rather than container creation time, and documented them in build.wiki. Using this new mechanism to pull the Fossil source tarball in such a way that we can use the Docker artifact cache without getting stale builds. You can now pass one of the new build args to force the old behavior if you want it. This required generating Dockerfile from Dockerfile.in at configure time, to inject the current Fossil checkin ID. (This busts the Docker cache when the source tree changes.)
Commit
f938438380885766c7b4eaf0af2d8c1d11b5ea4053cb86414f287d70b09801c2
Parent
d06d7c464e8deba…
5 files changed
-14
+2
-7
+1
-1
+7
+65
-17
D
Dockerfile
-14
| --- a/Dockerfile | ||
| +++ b/Dockerfile | ||
| @@ -1,14 +0,0 @@ | ||
| 1 | -0600_PFX@dir -m 700 museumeum/re# Avoid the temptation to swap the wget call below out for an ADD URL | |
| 2 | -# directive. That URL is fixed for a given release tag, which triggers | |
| 3 | -# Docker's caching behavior, causing it to reuse that version as long | |
| 4 | -# as it remains in the cache. We prefer to rely on the caching of the | |
| 5 | -# server instance on fossil-scm.org, which will keep these trunk | |
| 6 | -# tarballs around until the next trunk commit.repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3FossilENV BBXVER OSSIL_CI_PFX@dir -m 700 musearchive/refs/tags/${BBXVE to | |
| 7 | -# start as root so it can chroot itself away inside /jail. Since that's | |
| 8 | -# owned by the special fossil user, it drops root privileges for that | |
| 9 | -# user, preventing exotic root-based hacks on Dockerfossil",upxat's | |
| 10 | -# owned by the ). Since that's | |
| 11 | -# o/jail. Since that's | |
| 12 | -# own\ | |
| 13 | -museum/repo.fossil"] | |
| 14 | -${BBXVER}.tar.gz# o/jail. Since && wget -O - |
| --- a/Dockerfile | |
| +++ b/Dockerfile | |
| @@ -1,14 +0,0 @@ | |
| 1 | 0600_PFX@dir -m 700 museumeum/re# Avoid the temptation to swap the wget call below out for an ADD URL |
| 2 | # directive. That URL is fixed for a given release tag, which triggers |
| 3 | # Docker's caching behavior, causing it to reuse that version as long |
| 4 | # as it remains in the cache. We prefer to rely on the caching of the |
| 5 | # server instance on fossil-scm.org, which will keep these trunk |
| 6 | # tarballs around until the next trunk commit.repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3FossilENV BBXVER OSSIL_CI_PFX@dir -m 700 musearchive/refs/tags/${BBXVE to |
| 7 | # start as root so it can chroot itself away inside /jail. Since that's |
| 8 | # owned by the special fossil user, it drops root privileges for that |
| 9 | # user, preventing exotic root-based hacks on Dockerfossil",upxat's |
| 10 | # owned by the ). Since that's |
| 11 | # o/jail. Since that's |
| 12 | # own\ |
| 13 | museum/repo.fossil"] |
| 14 | ${BBXVER}.tar.gz# o/jail. Since && wget -O - |
| --- a/Dockerfile | |
| +++ b/Dockerfile | |
| @@ -1,14 +0,0 @@ | |
+2
-7
| --- a/Dockerfile.in | ||
| +++ b/Dockerfile.in | ||
| @@ -1,9 +1,5 @@ | ||
| 1 | -0600_PFX@dir -m 700 museumeum/re# Avoid the temptation to swap the wget call below out for an ADD URL | |
| 2 | -# directive. That URL is fixed for a given release tag, which triggers | |
| 3 | -# Docker's caching behavior, causing it to reuse that version as long | |
| 4 | -# as it remains in the cache. We prefer to rely on the caching of the | |
| 5 | -# server instance on fossil-scm.org, which will keep these trunk | |
| 6 | -# tarballs around until the next trunk commit.repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3FossilENV BBXVER OSSIL_CI_PFX@dir -m 700 musearchive/refs/tags/${BBXVE to | |
| 1 | +0600_PFX@dir -m 700 museumeum/repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3Fossil Init > /etc/groupeum/repo.fossila@FOSSIL_CI_PFX@dir -m 700 museum00 dev museum600600_PFX@dir -m 700 museumeum/repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleum# | |
| 2 | +# Implicit: We don't set USER here on purpose because we want Fossil to | |
| 7 | 3 | # start as root so it can chroot itself away inside /jail. Since that's |
| 8 | 4 | # owned by the special fossil user, it drops root privileges for that |
| 9 | 5 | # user, preventing exotic root-based hacks on Dockerfossil",upxat's |
| @@ -11,4 +7,3 @@ | ||
| 11 | 7 | # o/jail. Since that's |
| 12 | 8 | # own\ |
| 13 | 9 | museum/repo.fossil"] |
| 14 | -${BBXVER}.tar.gz# o/jail. Since && wget -O - |
| --- a/Dockerfile.in | |
| +++ b/Dockerfile.in | |
| @@ -1,9 +1,5 @@ | |
| 1 | 0600_PFX@dir -m 700 museumeum/re# Avoid the temptation to swap the wget call below out for an ADD URL |
| 2 | # directive. That URL is fixed for a given release tag, which triggers |
| 3 | # Docker's caching behavior, causing it to reuse that version as long |
| 4 | # as it remains in the cache. We prefer to rely on the caching of the |
| 5 | # server instance on fossil-scm.org, which will keep these trunk |
| 6 | # tarballs around until the next trunk commit.repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3FossilENV BBXVER OSSIL_CI_PFX@dir -m 700 musearchive/refs/tags/${BBXVE to |
| 7 | # start as root so it can chroot itself away inside /jail. Since that's |
| 8 | # owned by the special fossil user, it drops root privileges for that |
| 9 | # user, preventing exotic root-based hacks on Dockerfossil",upxat's |
| @@ -11,4 +7,3 @@ | |
| 11 | # o/jail. Since that's |
| 12 | # own\ |
| 13 | museum/repo.fossil"] |
| 14 | ${BBXVER}.tar.gz# o/jail. Since && wget -O - |
| --- a/Dockerfile.in | |
| +++ b/Dockerfile.in | |
| @@ -1,9 +1,5 @@ | |
| 1 | 0600_PFX@dir -m 700 museumeum/repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleumnull c 1 3Fossil Init > /etc/groupeum/repo.fossila@FOSSIL_CI_PFX@dir -m 700 museum00 dev museum600600_PFX@dir -m 700 museumeum/repo.fossilaren't@FOSSIL_CI_PFX@dir -m 700 museumtooleum# |
| 2 | # Implicit: We don't set USER here on purpose because we want Fossil to |
| 3 | # start as root so it can chroot itself away inside /jail. Since that's |
| 4 | # owned by the special fossil user, it drops root privileges for that |
| 5 | # user, preventing exotic root-based hacks on Dockerfossil",upxat's |
| @@ -11,4 +7,3 @@ | |
| 7 | # o/jail. Since that's |
| 8 | # own\ |
| 9 | museum/repo.fossil"] |
+1
-1
| --- Makefile.in | ||
| +++ Makefile.in | ||
| @@ -113,8 +113,8 @@ | ||
| 113 | 113 | # but Makefile won't change, so we'll reconfig but... endlessly. |
| 114 | 114 | # |
| 115 | 115 | # This is also why we repeat the reconfig target's command here instead |
| 116 | 116 | # of delegating to it with "$(MAKE) reconfig": having children running |
| 117 | 117 | # around interfering makes this failure mode even worse. |
| 118 | -Makefile: @srcdir@/Makefile.in $(SRCDIR)/main.mk @AUTODEPS@ | |
| 118 | +Makefile: @srcdir@/Makefile.in $(SRCDIR)/main.mk @AUTODEPS@ @srcdir@/Dockerfile.in | |
| 119 | 119 | @AUTOREMAKE@ |
| 120 | 120 | touch @builddir@/Makefile |
| 121 | 121 |
| --- Makefile.in | |
| +++ Makefile.in | |
| @@ -113,8 +113,8 @@ | |
| 113 | # but Makefile won't change, so we'll reconfig but... endlessly. |
| 114 | # |
| 115 | # This is also why we repeat the reconfig target's command here instead |
| 116 | # of delegating to it with "$(MAKE) reconfig": having children running |
| 117 | # around interfering makes this failure mode even worse. |
| 118 | Makefile: @srcdir@/Makefile.in $(SRCDIR)/main.mk @AUTODEPS@ |
| 119 | @AUTOREMAKE@ |
| 120 | touch @builddir@/Makefile |
| 121 |
| --- Makefile.in | |
| +++ Makefile.in | |
| @@ -113,8 +113,8 @@ | |
| 113 | # but Makefile won't change, so we'll reconfig but... endlessly. |
| 114 | # |
| 115 | # This is also why we repeat the reconfig target's command here instead |
| 116 | # of delegating to it with "$(MAKE) reconfig": having children running |
| 117 | # around interfering makes this failure mode even worse. |
| 118 | Makefile: @srcdir@/Makefile.in $(SRCDIR)/main.mk @AUTODEPS@ @srcdir@/Dockerfile.in |
| 119 | @AUTOREMAKE@ |
| 120 | touch @builddir@/Makefile |
| 121 |
M
auto.def
+7
| --- auto.def | ||
| +++ auto.def | ||
| @@ -764,8 +764,15 @@ | ||
| 764 | 764 | catch {exec chmod u+x tools/emcc.sh} |
| 765 | 765 | } else { |
| 766 | 766 | define EMCC_WRAPPER "" |
| 767 | 767 | catch {exec rm -f tools/emcc.sh} |
| 768 | 768 | } |
| 769 | + | |
| 770 | +# Insert a prefix of the checkin ID into the Dockerfile so repeated | |
| 771 | +# builds of this version generate and fetch the tarball only once, | |
| 772 | +# keeping it in the local Docker cache. | |
| 773 | +set ci [readfile "$::autosetup(srcdir)/manifest.uuid"] | |
| 774 | +define FOSSIL_CI_PFX [string range $ci 0 12] | |
| 775 | +make-template Dockerfile.in | |
| 769 | 776 | |
| 770 | 777 | make-template Makefile.in |
| 771 | 778 | make-config-header autoconfig.h -auto {USE_* FOSSIL_*} |
| 772 | 779 |
| --- auto.def | |
| +++ auto.def | |
| @@ -764,8 +764,15 @@ | |
| 764 | catch {exec chmod u+x tools/emcc.sh} |
| 765 | } else { |
| 766 | define EMCC_WRAPPER "" |
| 767 | catch {exec rm -f tools/emcc.sh} |
| 768 | } |
| 769 | |
| 770 | make-template Makefile.in |
| 771 | make-config-header autoconfig.h -auto {USE_* FOSSIL_*} |
| 772 |
| --- auto.def | |
| +++ auto.def | |
| @@ -764,8 +764,15 @@ | |
| 764 | catch {exec chmod u+x tools/emcc.sh} |
| 765 | } else { |
| 766 | define EMCC_WRAPPER "" |
| 767 | catch {exec rm -f tools/emcc.sh} |
| 768 | } |
| 769 | |
| 770 | # Insert a prefix of the checkin ID into the Dockerfile so repeated |
| 771 | # builds of this version generate and fetch the tarball only once, |
| 772 | # keeping it in the local Docker cache. |
| 773 | set ci [readfile "$::autosetup(srcdir)/manifest.uuid"] |
| 774 | define FOSSIL_CI_PFX [string range $ci 0 12] |
| 775 | make-template Dockerfile.in |
| 776 | |
| 777 | make-template Makefile.in |
| 778 | make-config-header autoconfig.h -auto {USE_* FOSSIL_*} |
| 779 |
+65
-17
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -255,11 +255,11 @@ | ||
| 255 | 255 | <h2 id="docker">5.0 Building a Docker Container</h2> |
| 256 | 256 | |
| 257 | 257 | Fossil ships a <tt>Dockerfile</tt> at the top of its source tree which |
| 258 | 258 | you can build like so: |
| 259 | 259 | |
| 260 | -<pre><code> $ docker build -t fossil --no-cache .</code></pre> | |
| 260 | +<pre><code> $ docker build -t fossil .</code></pre> | |
| 261 | 261 | |
| 262 | 262 | If the image built successfully, you can create a container from it and |
| 263 | 263 | test that it runs: |
| 264 | 264 | |
| 265 | 265 | <pre><code> $ docker run --name fossil -p 9999:8080/tcp fossil</code></pre> |
| @@ -272,14 +272,10 @@ | ||
| 272 | 272 | Our stock <tt>Dockerfile</tt> configures Fossil with the default feature |
| 273 | 273 | set, so you may wish to modify the <tt>Dockerfile</tt> to add |
| 274 | 274 | configuration options, add APK packages to support those options, and so |
| 275 | 275 | forth. |
| 276 | 276 | |
| 277 | -It builds tip-of-trunk. To get a release version instead, append | |
| 278 | -"<tt>?r=release</tt>" to the URL in the <tt>Dockerfile</tt>, then | |
| 279 | -(re)build it. | |
| 280 | - | |
| 281 | 277 | |
| 282 | 278 | <h3>5.1 Running It in Production</h3> |
| 283 | 279 | |
| 284 | 280 | If you want the container to serve an existing repository, there are at |
| 285 | 281 | least two right ways to do it. |
| @@ -324,23 +320,14 @@ | ||
| 324 | 320 | host machine, which is unlikely to map to anything in the container's |
| 325 | 321 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 326 | 322 | preventing the server from reading the copied-in repository file. |
| 327 | 323 | 499 is the default "fossil" user ID inside the container, causing Fossil to run |
| 328 | 324 | with that user's privileges after it enters the chroot. |
| 325 | +(See [#docker-args | below] for how to change this default.) | |
| 329 | 326 | You don't have to restart the server after fixing this with |
| 330 | 327 | <tt>chmod</tt>: simply reload the browser, and Fossil will try again. |
| 331 | 328 | |
| 332 | -(Why 499? Because regular user IDs start at 500 or 1000 on most Unix | |
| 333 | -type systems, leaving those below it for "system" users like this Fossil | |
| 334 | -daemon owner; standard OS system users start at 0 and go upward, so we | |
| 335 | -started at 500 and went down one to avoid a conflict. If you use Docker | |
| 336 | -volumes, you may wish to override this at container creation time — the | |
| 337 | -"run" or "create" command — by passing an option like "<tt>-e | |
| 338 | -UID=501</tt>". The internal container user IDs are used for permissions | |
| 339 | -on the volume, where the host's user/group IDs come into play, so | |
| 340 | -syncing the in-container user ID with the host can be useful.) | |
| 341 | - | |
| 342 | 329 | This simple method has a problem: Docker containers are designed to be |
| 343 | 330 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 344 | 331 | that with the repo inside the container, it gets destroyed, too. The |
| 345 | 332 | solution is to replace the "run" command above with the following: |
| 346 | 333 | |
| @@ -355,11 +342,11 @@ | ||
| 355 | 342 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 356 | 343 | — the volume remains behind and gets remapped into the new container |
| 357 | 344 | when you recreate it by giving the above command again. |
| 358 | 345 | |
| 359 | 346 | |
| 360 | -<h3>5.2 Why Chroot?</h3> | |
| 347 | +<h3 id="docker-chroot">5.2 Why Chroot?</h3> | |
| 361 | 348 | |
| 362 | 349 | A potentially surprising feature of this container is that it runs |
| 363 | 350 | Fossil as root. Since that causes [./chroot.md | Fossil's chroot jail |
| 364 | 351 | feature] to kick in, and a Docker container is a type of über-jail |
| 365 | 352 | already, you may be wondering why we don't either: |
| @@ -391,11 +378,11 @@ | ||
| 391 | 378 | without restarting it: each hit reevaluates the repository file |
| 392 | 379 | permissions when deciding what user to become when dropping root |
| 393 | 380 | privileges. |
| 394 | 381 | |
| 395 | 382 | |
| 396 | -<h3>5.3 Extracting a Static Binary</h3> | |
| 383 | +<h3 id="docker-static">5.3 Extracting a Static Binary</h3> | |
| 397 | 384 | |
| 398 | 385 | Our 2-stage build process uses Alpine Linux only as a build host. Once |
| 399 | 386 | we've got everything reduced to the two key static binaries — Fossil and |
| 400 | 387 | Busybox — we throw all the rest of it away. |
| 401 | 388 | |
| @@ -413,10 +400,71 @@ | ||
| 413 | 400 | </code></pre> |
| 414 | 401 | |
| 415 | 402 | The resulting binary is the single largest file inside that container, |
| 416 | 403 | at about 6 MiB. (It's built stripped.) |
| 417 | 404 | |
| 405 | + | |
| 406 | +<h3 id="docker-args">5.4 Container Build Arguments</h3> | |
| 407 | + | |
| 408 | +<h4>5.4.1 Package Versions</h4> | |
| 409 | + | |
| 410 | +You can override the default versions of Fossil and BusyBox that get | |
| 411 | +fetched in the build step. To get the latest-and-greatest of | |
| 412 | +everything, you could say: | |
| 413 | + | |
| 414 | +<pre><code> $ docker build -t fossil \ | |
| 415 | + --build-arg FSLVER=trunk \ | |
| 416 | + --build-arg BBXVER=master .</code></pre> | |
| 417 | + | |
| 418 | +(But don't, for reasons we will get to.) | |
| 419 | + | |
| 420 | +Because the BusyBox configuration file we ship was created with and | |
| 421 | +tested against a specific stable release, that's the version we pull by | |
| 422 | +default. It does try to merge the defaults for any new configuration | |
| 423 | +settings into the stock set, but since it's possible this will fail, we | |
| 424 | +don't blindly update the BusyBox version merely because a new release | |
| 425 | +came out. Someone needs to get around to vetting it against our stock | |
| 426 | +configuration first. | |
| 427 | + | |
| 428 | +As for Fossil, it defaults to fetching the same version as the checkout | |
| 429 | +you're running the build command from, based on checkin ID. The most | |
| 430 | +common reason to override this is to get a release version: | |
| 431 | + | |
| 432 | +<pre><code> $ docker build -t fossil \ | |
| 433 | + --build-arg FSLVER=version-2.19 .</code></pre> | |
| 434 | + | |
| 435 | +It's best to use a specific version number rather than the generic | |
| 436 | +"release" tag because Docker caches downloaded files and tries to reuse | |
| 437 | +them across builds. If you ask for "release" before a new version is | |
| 438 | +tagged and then immediately after, you expect to get two different | |
| 439 | +tarballs, but because the URL hasn't changed, if you have an old release | |
| 440 | +tarball in your Docker cache, you'll get the old version even if you | |
| 441 | +pass the "docker build --no-cache" option. | |
| 442 | + | |
| 443 | +This is why we default to a checkin ID rather than a generic tag like | |
| 444 | +"trunk": so the URL will change each time you update your Fossil source | |
| 445 | +tree, forcing Docker to pull a fresh tarball. | |
| 446 | + | |
| 447 | +<h4>5.4.2 User & Group IDs</h4> | |
| 448 | + | |
| 449 | +The "fossil" user and group IDs inside the container default to 499. | |
| 450 | +Why? Regular user IDs start at 500 or 1000 on most Unix type systems, | |
| 451 | +leaving those below it for "system" users like this Fossil daemon owner. | |
| 452 | +Since standard OS system users start at 0 and go upward, we started at | |
| 453 | +500 and went down one to reduce the chance of a conflict to as close to | |
| 454 | +zero as we can manage. | |
| 455 | + | |
| 456 | +To change it to something else, say: | |
| 457 | + | |
| 458 | +<pre><code> $ docker build -t fossil --build-arg UID=501 .</code></pre> | |
| 459 | + | |
| 460 | +This is particularly useful if you're putting your repository on a | |
| 461 | +Docker volume since the IDs "leak" out into the host environment via | |
| 462 | +file permissions. You may therefore wish them to mean something on both | |
| 463 | +sides of the container barrier rather than have "499" appear on the host | |
| 464 | +in "<tt>ls -l</tt>" output. | |
| 465 | + | |
| 418 | 466 | |
| 419 | 467 | <h2>6.0 Building on/for Android</h2> |
| 420 | 468 | |
| 421 | 469 | <h3>6.1 Cross-compiling from Linux</h3> |
| 422 | 470 | |
| 423 | 471 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -255,11 +255,11 @@ | |
| 255 | <h2 id="docker">5.0 Building a Docker Container</h2> |
| 256 | |
| 257 | Fossil ships a <tt>Dockerfile</tt> at the top of its source tree which |
| 258 | you can build like so: |
| 259 | |
| 260 | <pre><code> $ docker build -t fossil --no-cache .</code></pre> |
| 261 | |
| 262 | If the image built successfully, you can create a container from it and |
| 263 | test that it runs: |
| 264 | |
| 265 | <pre><code> $ docker run --name fossil -p 9999:8080/tcp fossil</code></pre> |
| @@ -272,14 +272,10 @@ | |
| 272 | Our stock <tt>Dockerfile</tt> configures Fossil with the default feature |
| 273 | set, so you may wish to modify the <tt>Dockerfile</tt> to add |
| 274 | configuration options, add APK packages to support those options, and so |
| 275 | forth. |
| 276 | |
| 277 | It builds tip-of-trunk. To get a release version instead, append |
| 278 | "<tt>?r=release</tt>" to the URL in the <tt>Dockerfile</tt>, then |
| 279 | (re)build it. |
| 280 | |
| 281 | |
| 282 | <h3>5.1 Running It in Production</h3> |
| 283 | |
| 284 | If you want the container to serve an existing repository, there are at |
| 285 | least two right ways to do it. |
| @@ -324,23 +320,14 @@ | |
| 324 | host machine, which is unlikely to map to anything in the container's |
| 325 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 326 | preventing the server from reading the copied-in repository file. |
| 327 | 499 is the default "fossil" user ID inside the container, causing Fossil to run |
| 328 | with that user's privileges after it enters the chroot. |
| 329 | You don't have to restart the server after fixing this with |
| 330 | <tt>chmod</tt>: simply reload the browser, and Fossil will try again. |
| 331 | |
| 332 | (Why 499? Because regular user IDs start at 500 or 1000 on most Unix |
| 333 | type systems, leaving those below it for "system" users like this Fossil |
| 334 | daemon owner; standard OS system users start at 0 and go upward, so we |
| 335 | started at 500 and went down one to avoid a conflict. If you use Docker |
| 336 | volumes, you may wish to override this at container creation time — the |
| 337 | "run" or "create" command — by passing an option like "<tt>-e |
| 338 | UID=501</tt>". The internal container user IDs are used for permissions |
| 339 | on the volume, where the host's user/group IDs come into play, so |
| 340 | syncing the in-container user ID with the host can be useful.) |
| 341 | |
| 342 | This simple method has a problem: Docker containers are designed to be |
| 343 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 344 | that with the repo inside the container, it gets destroyed, too. The |
| 345 | solution is to replace the "run" command above with the following: |
| 346 | |
| @@ -355,11 +342,11 @@ | |
| 355 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 356 | — the volume remains behind and gets remapped into the new container |
| 357 | when you recreate it by giving the above command again. |
| 358 | |
| 359 | |
| 360 | <h3>5.2 Why Chroot?</h3> |
| 361 | |
| 362 | A potentially surprising feature of this container is that it runs |
| 363 | Fossil as root. Since that causes [./chroot.md | Fossil's chroot jail |
| 364 | feature] to kick in, and a Docker container is a type of über-jail |
| 365 | already, you may be wondering why we don't either: |
| @@ -391,11 +378,11 @@ | |
| 391 | without restarting it: each hit reevaluates the repository file |
| 392 | permissions when deciding what user to become when dropping root |
| 393 | privileges. |
| 394 | |
| 395 | |
| 396 | <h3>5.3 Extracting a Static Binary</h3> |
| 397 | |
| 398 | Our 2-stage build process uses Alpine Linux only as a build host. Once |
| 399 | we've got everything reduced to the two key static binaries — Fossil and |
| 400 | Busybox — we throw all the rest of it away. |
| 401 | |
| @@ -413,10 +400,71 @@ | |
| 413 | </code></pre> |
| 414 | |
| 415 | The resulting binary is the single largest file inside that container, |
| 416 | at about 6 MiB. (It's built stripped.) |
| 417 | |
| 418 | |
| 419 | <h2>6.0 Building on/for Android</h2> |
| 420 | |
| 421 | <h3>6.1 Cross-compiling from Linux</h3> |
| 422 | |
| 423 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -255,11 +255,11 @@ | |
| 255 | <h2 id="docker">5.0 Building a Docker Container</h2> |
| 256 | |
| 257 | Fossil ships a <tt>Dockerfile</tt> at the top of its source tree which |
| 258 | you can build like so: |
| 259 | |
| 260 | <pre><code> $ docker build -t fossil .</code></pre> |
| 261 | |
| 262 | If the image built successfully, you can create a container from it and |
| 263 | test that it runs: |
| 264 | |
| 265 | <pre><code> $ docker run --name fossil -p 9999:8080/tcp fossil</code></pre> |
| @@ -272,14 +272,10 @@ | |
| 272 | Our stock <tt>Dockerfile</tt> configures Fossil with the default feature |
| 273 | set, so you may wish to modify the <tt>Dockerfile</tt> to add |
| 274 | configuration options, add APK packages to support those options, and so |
| 275 | forth. |
| 276 | |
| 277 | |
| 278 | <h3>5.1 Running It in Production</h3> |
| 279 | |
| 280 | If you want the container to serve an existing repository, there are at |
| 281 | least two right ways to do it. |
| @@ -324,23 +320,14 @@ | |
| 320 | host machine, which is unlikely to map to anything in the container's |
| 321 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 322 | preventing the server from reading the copied-in repository file. |
| 323 | 499 is the default "fossil" user ID inside the container, causing Fossil to run |
| 324 | with that user's privileges after it enters the chroot. |
| 325 | (See [#docker-args | below] for how to change this default.) |
| 326 | You don't have to restart the server after fixing this with |
| 327 | <tt>chmod</tt>: simply reload the browser, and Fossil will try again. |
| 328 | |
| 329 | This simple method has a problem: Docker containers are designed to be |
| 330 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 331 | that with the repo inside the container, it gets destroyed, too. The |
| 332 | solution is to replace the "run" command above with the following: |
| 333 | |
| @@ -355,11 +342,11 @@ | |
| 342 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 343 | — the volume remains behind and gets remapped into the new container |
| 344 | when you recreate it by giving the above command again. |
| 345 | |
| 346 | |
| 347 | <h3 id="docker-chroot">5.2 Why Chroot?</h3> |
| 348 | |
| 349 | A potentially surprising feature of this container is that it runs |
| 350 | Fossil as root. Since that causes [./chroot.md | Fossil's chroot jail |
| 351 | feature] to kick in, and a Docker container is a type of über-jail |
| 352 | already, you may be wondering why we don't either: |
| @@ -391,11 +378,11 @@ | |
| 378 | without restarting it: each hit reevaluates the repository file |
| 379 | permissions when deciding what user to become when dropping root |
| 380 | privileges. |
| 381 | |
| 382 | |
| 383 | <h3 id="docker-static">5.3 Extracting a Static Binary</h3> |
| 384 | |
| 385 | Our 2-stage build process uses Alpine Linux only as a build host. Once |
| 386 | we've got everything reduced to the two key static binaries — Fossil and |
| 387 | Busybox — we throw all the rest of it away. |
| 388 | |
| @@ -413,10 +400,71 @@ | |
| 400 | </code></pre> |
| 401 | |
| 402 | The resulting binary is the single largest file inside that container, |
| 403 | at about 6 MiB. (It's built stripped.) |
| 404 | |
| 405 | |
| 406 | <h3 id="docker-args">5.4 Container Build Arguments</h3> |
| 407 | |
| 408 | <h4>5.4.1 Package Versions</h4> |
| 409 | |
| 410 | You can override the default versions of Fossil and BusyBox that get |
| 411 | fetched in the build step. To get the latest-and-greatest of |
| 412 | everything, you could say: |
| 413 | |
| 414 | <pre><code> $ docker build -t fossil \ |
| 415 | --build-arg FSLVER=trunk \ |
| 416 | --build-arg BBXVER=master .</code></pre> |
| 417 | |
| 418 | (But don't, for reasons we will get to.) |
| 419 | |
| 420 | Because the BusyBox configuration file we ship was created with and |
| 421 | tested against a specific stable release, that's the version we pull by |
| 422 | default. It does try to merge the defaults for any new configuration |
| 423 | settings into the stock set, but since it's possible this will fail, we |
| 424 | don't blindly update the BusyBox version merely because a new release |
| 425 | came out. Someone needs to get around to vetting it against our stock |
| 426 | configuration first. |
| 427 | |
| 428 | As for Fossil, it defaults to fetching the same version as the checkout |
| 429 | you're running the build command from, based on checkin ID. The most |
| 430 | common reason to override this is to get a release version: |
| 431 | |
| 432 | <pre><code> $ docker build -t fossil \ |
| 433 | --build-arg FSLVER=version-2.19 .</code></pre> |
| 434 | |
| 435 | It's best to use a specific version number rather than the generic |
| 436 | "release" tag because Docker caches downloaded files and tries to reuse |
| 437 | them across builds. If you ask for "release" before a new version is |
| 438 | tagged and then immediately after, you expect to get two different |
| 439 | tarballs, but because the URL hasn't changed, if you have an old release |
| 440 | tarball in your Docker cache, you'll get the old version even if you |
| 441 | pass the "docker build --no-cache" option. |
| 442 | |
| 443 | This is why we default to a checkin ID rather than a generic tag like |
| 444 | "trunk": so the URL will change each time you update your Fossil source |
| 445 | tree, forcing Docker to pull a fresh tarball. |
| 446 | |
| 447 | <h4>5.4.2 User & Group IDs</h4> |
| 448 | |
| 449 | The "fossil" user and group IDs inside the container default to 499. |
| 450 | Why? Regular user IDs start at 500 or 1000 on most Unix type systems, |
| 451 | leaving those below it for "system" users like this Fossil daemon owner. |
| 452 | Since standard OS system users start at 0 and go upward, we started at |
| 453 | 500 and went down one to reduce the chance of a conflict to as close to |
| 454 | zero as we can manage. |
| 455 | |
| 456 | To change it to something else, say: |
| 457 | |
| 458 | <pre><code> $ docker build -t fossil --build-arg UID=501 .</code></pre> |
| 459 | |
| 460 | This is particularly useful if you're putting your repository on a |
| 461 | Docker volume since the IDs "leak" out into the host environment via |
| 462 | file permissions. You may therefore wish them to mean something on both |
| 463 | sides of the container barrier rather than have "499" appear on the host |
| 464 | in "<tt>ls -l</tt>" output. |
| 465 | |
| 466 | |
| 467 | <h2>6.0 Building on/for Android</h2> |
| 468 | |
| 469 | <h3>6.1 Cross-compiling from Linux</h3> |
| 470 | |
| 471 |