Fossil SCM
Made a better distinction between bind mounts and Docker volumes in the new Docker section of the build doc.
Commit
958a6af94b246050e4898cdbc88d4fb6d4dbf90bc47a60769a2d10ba034080b6
Parent
a88478391e555ed…
1 file changed
+21
-12
+21
-12
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -322,14 +322,10 @@ | ||
| 322 | 322 | That copies the local Fossil repo into the container where the server |
| 323 | 323 | expects to find it, so that the "start" command causes it to serve from |
| 324 | 324 | that copied-in file instead. Since it lives atop the immutable base layers, it |
| 325 | 325 | persists as part of the container proper, surviving restarts. |
| 326 | 326 | |
| 327 | -(The same is true of the default mode of operation: the <tt>fossil | |
| 328 | -server --create</tt> flag initializes a fresh Fossil repo atop the base | |
| 329 | -image.) | |
| 330 | - | |
| 331 | 327 | Notice that the copy command changes the name of the repository database. |
| 332 | 328 | The container configuration expects it to be called |
| 333 | 329 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 334 | 330 | system. This is because there is only one repository inside this |
| 335 | 331 | container, so we don't have to name it after the project it contains, as |
| @@ -355,21 +351,34 @@ | ||
| 355 | 351 | The simple storage method above has a problem: Docker containers are designed to be |
| 356 | 352 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 357 | 353 | that with the repo inside the container, it gets destroyed, too. The |
| 358 | 354 | solution is to replace the "run" command above with the following: |
| 359 | 355 | |
| 360 | -<pre><code> $ docker create \ | |
| 361 | - --name fossil -p 9999:8080/tcp \ | |
| 362 | - -v museum:/jail/museum fossil | |
| 356 | +<pre><code> $ docker run \ | |
| 357 | + --name fossil-bind-mount -p 9999:8080 \ | |
| 358 | + -v ~/museum:/jail/museum fossil | |
| 363 | 359 | </code></pre> |
| 364 | 360 | |
| 365 | -Now when you "docker cp" the local repo into the container, it lands on | |
| 366 | -a separate [https://docs.docker.com/storage/volumes/ | Docker volume] | |
| 367 | -mounted inside it, giving those files an independent lifetime. When you need to | |
| 361 | +Because this bind mount maps a host-side directory (<tt>~/museum</tt>) | |
| 362 | +into the container, you don't need to <tt>docker cp</tt> the repo into | |
| 363 | +the container at all. It still expects to find the repository as | |
| 364 | +<tt>repo.fossil</tt> under that directory, but now both the host and the | |
| 365 | +container can see that file. (Beware: This may create a | |
| 366 | +[https://www.sqlite.org/howtocorrupt.html | risk of data corruption] due | |
| 367 | +to SQLite locking issues if you try to modify the DB from both sides at | |
| 368 | +once.) | |
| 369 | + | |
| 370 | +Instead of a bind mount, you could instead set up | |
| 371 | +a separate [https://docs.docker.com/storage/volumes/ | Docker volume], | |
| 372 | +at which point you <i>would</i> need to <tt>docker cp</tt> the repo file | |
| 373 | +into the container. | |
| 374 | + | |
| 375 | +Either way, files in these mounted directories have a lifetime independent | |
| 376 | +of the container(s) they're mounted into. When you need to | |
| 368 | 377 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 369 | -— the volume remains behind and gets remapped into the new container | |
| 370 | -when you recreate it by giving the above command again. | |
| 378 | +— the external directory remains behind and gets remapped into the new container | |
| 379 | +when you recreate it with <tt>-v</tt>. | |
| 371 | 380 | |
| 372 | 381 | |
| 373 | 382 | <h3 id="docker-chroot">5.2 Why Chroot?</h3> |
| 374 | 383 | |
| 375 | 384 | A potentially surprising feature of this container is that it runs |
| 376 | 385 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -322,14 +322,10 @@ | |
| 322 | That copies the local Fossil repo into the container where the server |
| 323 | expects to find it, so that the "start" command causes it to serve from |
| 324 | that copied-in file instead. Since it lives atop the immutable base layers, it |
| 325 | persists as part of the container proper, surviving restarts. |
| 326 | |
| 327 | (The same is true of the default mode of operation: the <tt>fossil |
| 328 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 329 | image.) |
| 330 | |
| 331 | Notice that the copy command changes the name of the repository database. |
| 332 | The container configuration expects it to be called |
| 333 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 334 | system. This is because there is only one repository inside this |
| 335 | container, so we don't have to name it after the project it contains, as |
| @@ -355,21 +351,34 @@ | |
| 355 | The simple storage method above has a problem: Docker containers are designed to be |
| 356 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 357 | that with the repo inside the container, it gets destroyed, too. The |
| 358 | solution is to replace the "run" command above with the following: |
| 359 | |
| 360 | <pre><code> $ docker create \ |
| 361 | --name fossil -p 9999:8080/tcp \ |
| 362 | -v museum:/jail/museum fossil |
| 363 | </code></pre> |
| 364 | |
| 365 | Now when you "docker cp" the local repo into the container, it lands on |
| 366 | a separate [https://docs.docker.com/storage/volumes/ | Docker volume] |
| 367 | mounted inside it, giving those files an independent lifetime. When you need to |
| 368 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 369 | — the volume remains behind and gets remapped into the new container |
| 370 | when you recreate it by giving the above command again. |
| 371 | |
| 372 | |
| 373 | <h3 id="docker-chroot">5.2 Why Chroot?</h3> |
| 374 | |
| 375 | A potentially surprising feature of this container is that it runs |
| 376 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -322,14 +322,10 @@ | |
| 322 | That copies the local Fossil repo into the container where the server |
| 323 | expects to find it, so that the "start" command causes it to serve from |
| 324 | that copied-in file instead. Since it lives atop the immutable base layers, it |
| 325 | persists as part of the container proper, surviving restarts. |
| 326 | |
| 327 | Notice that the copy command changes the name of the repository database. |
| 328 | The container configuration expects it to be called |
| 329 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 330 | system. This is because there is only one repository inside this |
| 331 | container, so we don't have to name it after the project it contains, as |
| @@ -355,21 +351,34 @@ | |
| 351 | The simple storage method above has a problem: Docker containers are designed to be |
| 352 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 353 | that with the repo inside the container, it gets destroyed, too. The |
| 354 | solution is to replace the "run" command above with the following: |
| 355 | |
| 356 | <pre><code> $ docker run \ |
| 357 | --name fossil-bind-mount -p 9999:8080 \ |
| 358 | -v ~/museum:/jail/museum fossil |
| 359 | </code></pre> |
| 360 | |
| 361 | Because this bind mount maps a host-side directory (<tt>~/museum</tt>) |
| 362 | into the container, you don't need to <tt>docker cp</tt> the repo into |
| 363 | the container at all. It still expects to find the repository as |
| 364 | <tt>repo.fossil</tt> under that directory, but now both the host and the |
| 365 | container can see that file. (Beware: This may create a |
| 366 | [https://www.sqlite.org/howtocorrupt.html | risk of data corruption] due |
| 367 | to SQLite locking issues if you try to modify the DB from both sides at |
| 368 | once.) |
| 369 | |
| 370 | Instead of a bind mount, you could instead set up |
| 371 | a separate [https://docs.docker.com/storage/volumes/ | Docker volume], |
| 372 | at which point you <i>would</i> need to <tt>docker cp</tt> the repo file |
| 373 | into the container. |
| 374 | |
| 375 | Either way, files in these mounted directories have a lifetime independent |
| 376 | of the container(s) they're mounted into. When you need to |
| 377 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 378 | — the external directory remains behind and gets remapped into the new container |
| 379 | when you recreate it with <tt>-v</tt>. |
| 380 | |
| 381 | |
| 382 | <h3 id="docker-chroot">5.2 Why Chroot?</h3> |
| 383 | |
| 384 | A potentially surprising feature of this container is that it runs |
| 385 |