Fossil SCM
Edit pass on §5.1 of build.wiki, fixing a number of unclear bits, particularly with regard to images vs containers.
Commit
e2b9114b18519888096d3559fcf28d5dcde488daf9d2acda7170d7d8ada9b05b
Parent
f76e762fb700828…
1 file changed
+16
-11
+16
-11
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -283,38 +283,43 @@ | ||
| 283 | 283 | |
| 284 | 284 | If you want the container to serve an existing repository, there are at |
| 285 | 285 | least two right ways to do it. |
| 286 | 286 | |
| 287 | 287 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| 288 | -into the container at build time. It will become one of the container's | |
| 289 | -base layers, so that each time you restart the container, it gets reset | |
| 290 | -to its prior state. This almost certainly is not what you want. | |
| 288 | +into the image at build time. It will become one of the image's base | |
| 289 | +layers, so that each time you build a container from that image, the | |
| 290 | +repo gets reset to its build-time state. Worse, restarting the container | |
| 291 | +will do the same thing, since the base image layers are immutable in | |
| 292 | +Docker. This is almost certainly not what you want. | |
| 291 | 293 | |
| 292 | -The simplest correct method is to stop the container if it was running, | |
| 294 | +The correct ways put the repo into the <i>container</i> created from the | |
| 295 | +image, not in the <i>image</i> itself. | |
| 296 | + | |
| 297 | +The simplest method is to stop the container if it was running, | |
| 293 | 298 | then say: |
| 294 | 299 | |
| 295 | 300 | <pre><code> $ docker cp /path/to/repo.fossil fossil:/jail/museum/repo.fossil |
| 296 | 301 | $ docker start fossil |
| 297 | 302 | $ docker exec fossil chown 0 /jail/museum/repo.fossil</code></pre> |
| 298 | 303 | |
| 299 | 304 | That copies the local Fossil repo into the container where the server |
| 300 | 305 | expects to find it, so that the "start" command causes it to serve from |
| 301 | -that copied-in file instead. Since it lives atop the base layers, it | |
| 306 | +that copied-in file instead. Since it lives atop the immutable base layers, it | |
| 302 | 307 | persists as part of the container proper, surviving restarts. |
| 303 | 308 | |
| 304 | 309 | (The same is true of the default mode of operation: the <tt>fossil |
| 305 | 310 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 306 | -layer.) | |
| 311 | +image.) | |
| 307 | 312 | |
| 308 | 313 | If you skip the "chown" command and put "http://localhost:9999/" into |
| 309 | 314 | your browser, expecting to see the copied-in repo's home page, you will |
| 310 | -get an opaque "Not Found" error instead. This is because the user and | |
| 315 | +get an opaque "Not Found" error. This is because the user and | |
| 311 | 316 | group ID of the file will be that of your local user on the container's |
| 312 | 317 | host machine, which won't map to anything in the container's |
| 313 | 318 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 314 | 319 | preventing the server from reading the copied-in repository file. You |
| 315 | -don't have to restart the server after fixing this: simply reload the | |
| 320 | +don't have to restart the server after fixing this with <tt>chmod</tt>: simply reload the | |
| 316 | 321 | browser, and Fossil will try again. |
| 317 | 322 | |
| 318 | 323 | This simple method has a problem: Docker containers are designed to be |
| 319 | 324 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 320 | 325 | that with the repo inside the container, it gets destroyed, too. The |
| @@ -325,13 +330,13 @@ | ||
| 325 | 330 | -v museum:/jail/museum fossil |
| 326 | 331 | </code></pre> |
| 327 | 332 | |
| 328 | 333 | Now when you "docker cp" the local repo into the container, it lands on |
| 329 | 334 | a separate [https://docs.docker.com/storage/volumes/ | Docker volume] |
| 330 | -mounted inside it, which has an independent lifetime. When you need to | |
| 331 | -rebuild the container — such as to upgrade to a newer version of Fossil | |
| 332 | -— the volume remains behind and gets remapped into the new contanier | |
| 335 | +mounted inside it, giving those files an independent lifetime. When you need to | |
| 336 | +rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil | |
| 337 | +— the volume remains behind and gets remapped into the new container | |
| 333 | 338 | when you recreate it by giving the above command again. |
| 334 | 339 | |
| 335 | 340 | |
| 336 | 341 | <h3>5.2 Why Chroot?</h3> |
| 337 | 342 | |
| 338 | 343 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -283,38 +283,43 @@ | |
| 283 | |
| 284 | If you want the container to serve an existing repository, there are at |
| 285 | least two right ways to do it. |
| 286 | |
| 287 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| 288 | into the container at build time. It will become one of the container's |
| 289 | base layers, so that each time you restart the container, it gets reset |
| 290 | to its prior state. This almost certainly is not what you want. |
| 291 | |
| 292 | The simplest correct method is to stop the container if it was running, |
| 293 | then say: |
| 294 | |
| 295 | <pre><code> $ docker cp /path/to/repo.fossil fossil:/jail/museum/repo.fossil |
| 296 | $ docker start fossil |
| 297 | $ docker exec fossil chown 0 /jail/museum/repo.fossil</code></pre> |
| 298 | |
| 299 | That copies the local Fossil repo into the container where the server |
| 300 | expects to find it, so that the "start" command causes it to serve from |
| 301 | that copied-in file instead. Since it lives atop the base layers, it |
| 302 | persists as part of the container proper, surviving restarts. |
| 303 | |
| 304 | (The same is true of the default mode of operation: the <tt>fossil |
| 305 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 306 | layer.) |
| 307 | |
| 308 | If you skip the "chown" command and put "http://localhost:9999/" into |
| 309 | your browser, expecting to see the copied-in repo's home page, you will |
| 310 | get an opaque "Not Found" error instead. This is because the user and |
| 311 | group ID of the file will be that of your local user on the container's |
| 312 | host machine, which won't map to anything in the container's |
| 313 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 314 | preventing the server from reading the copied-in repository file. You |
| 315 | don't have to restart the server after fixing this: simply reload the |
| 316 | browser, and Fossil will try again. |
| 317 | |
| 318 | This simple method has a problem: Docker containers are designed to be |
| 319 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 320 | that with the repo inside the container, it gets destroyed, too. The |
| @@ -325,13 +330,13 @@ | |
| 325 | -v museum:/jail/museum fossil |
| 326 | </code></pre> |
| 327 | |
| 328 | Now when you "docker cp" the local repo into the container, it lands on |
| 329 | a separate [https://docs.docker.com/storage/volumes/ | Docker volume] |
| 330 | mounted inside it, which has an independent lifetime. When you need to |
| 331 | rebuild the container — such as to upgrade to a newer version of Fossil |
| 332 | — the volume remains behind and gets remapped into the new contanier |
| 333 | when you recreate it by giving the above command again. |
| 334 | |
| 335 | |
| 336 | <h3>5.2 Why Chroot?</h3> |
| 337 | |
| 338 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -283,38 +283,43 @@ | |
| 283 | |
| 284 | If you want the container to serve an existing repository, there are at |
| 285 | least two right ways to do it. |
| 286 | |
| 287 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| 288 | into the image at build time. It will become one of the image's base |
| 289 | layers, so that each time you build a container from that image, the |
| 290 | repo gets reset to its build-time state. Worse, restarting the container |
| 291 | will do the same thing, since the base image layers are immutable in |
| 292 | Docker. This is almost certainly not what you want. |
| 293 | |
| 294 | The correct ways put the repo into the <i>container</i> created from the |
| 295 | image, not in the <i>image</i> itself. |
| 296 | |
| 297 | The simplest method is to stop the container if it was running, |
| 298 | then say: |
| 299 | |
| 300 | <pre><code> $ docker cp /path/to/repo.fossil fossil:/jail/museum/repo.fossil |
| 301 | $ docker start fossil |
| 302 | $ docker exec fossil chown 0 /jail/museum/repo.fossil</code></pre> |
| 303 | |
| 304 | That copies the local Fossil repo into the container where the server |
| 305 | expects to find it, so that the "start" command causes it to serve from |
| 306 | that copied-in file instead. Since it lives atop the immutable base layers, it |
| 307 | persists as part of the container proper, surviving restarts. |
| 308 | |
| 309 | (The same is true of the default mode of operation: the <tt>fossil |
| 310 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 311 | image.) |
| 312 | |
| 313 | If you skip the "chown" command and put "http://localhost:9999/" into |
| 314 | your browser, expecting to see the copied-in repo's home page, you will |
| 315 | get an opaque "Not Found" error. This is because the user and |
| 316 | group ID of the file will be that of your local user on the container's |
| 317 | host machine, which won't map to anything in the container's |
| 318 | <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, effectively |
| 319 | preventing the server from reading the copied-in repository file. You |
| 320 | don't have to restart the server after fixing this with <tt>chmod</tt>: simply reload the |
| 321 | browser, and Fossil will try again. |
| 322 | |
| 323 | This simple method has a problem: Docker containers are designed to be |
| 324 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 325 | that with the repo inside the container, it gets destroyed, too. The |
| @@ -325,13 +330,13 @@ | |
| 330 | -v museum:/jail/museum fossil |
| 331 | </code></pre> |
| 332 | |
| 333 | Now when you "docker cp" the local repo into the container, it lands on |
| 334 | a separate [https://docs.docker.com/storage/volumes/ | Docker volume] |
| 335 | mounted inside it, giving those files an independent lifetime. When you need to |
| 336 | rebuild the container or its underlying image — such as to upgrade to a newer version of Fossil |
| 337 | — the volume remains behind and gets remapped into the new container |
| 338 | when you recreate it by giving the above command again. |
| 339 | |
| 340 | |
| 341 | <h3>5.2 Why Chroot?</h3> |
| 342 | |
| 343 |