Fossil SCM
Polishing pass on the container repo storage section of the build docs.
Commit
3e332637f15f88ffa3690e183be559ed1a1da1dd25bc52a6fb8551239f193031
Parent
f93843838088576…
1 file changed
+12
-5
+12
-5
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -273,11 +273,11 @@ | ||
| 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 | 277 | |
| 278 | -<h3>5.1 Running It in Production</h3> | |
| 278 | +<h3 id="docker-storage">5.1 Repository Storage Options</h3> | |
| 279 | 279 | |
| 280 | 280 | If you want the container to serve an existing repository, there are at |
| 281 | 281 | least two right ways to do it. |
| 282 | 282 | |
| 283 | 283 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| @@ -288,10 +288,13 @@ | ||
| 288 | 288 | Docker. This is almost certainly not what you want. |
| 289 | 289 | |
| 290 | 290 | The correct ways put the repo into the <i>container</i> created from the |
| 291 | 291 | <i>image</i>, not in the image itself. |
| 292 | 292 | |
| 293 | + | |
| 294 | +<h4>5.1.1 Storing the Repo Inside the Container</h4> | |
| 295 | + | |
| 293 | 296 | The simplest method is to stop the container if it was running, |
| 294 | 297 | then say: |
| 295 | 298 | |
| 296 | 299 | <pre><code> $ docker cp /path/to/my-project.fossil fossil:/jail/museum/repo.fossil |
| 297 | 300 | $ docker start fossil |
| @@ -304,16 +307,17 @@ | ||
| 304 | 307 | |
| 305 | 308 | (The same is true of the default mode of operation: the <tt>fossil |
| 306 | 309 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 307 | 310 | image.) |
| 308 | 311 | |
| 309 | -Notice that the name of the repository database likely needs to change | |
| 310 | -in the copy. The container configuration expects it to be called | |
| 312 | +Notice that the copy command changes the name of the repository database. | |
| 313 | +The container configuration expects it to be called | |
| 311 | 314 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 312 | 315 | system. This is because there is only one repository inside this |
| 313 | 316 | container, so we don't have to name it after the project it contains, as |
| 314 | -is traditional. | |
| 317 | +is traditional. A generic name lets us hard-code the server start | |
| 318 | +command. | |
| 315 | 319 | |
| 316 | 320 | If you skip the "chown" command above and put "http://localhost:9999/" into |
| 317 | 321 | your browser, expecting to see the copied-in repo's home page, you will |
| 318 | 322 | get an opaque "Not Found" error. This is because the user and |
| 319 | 323 | group ID of the file will be that of your local user on the container's |
| @@ -324,11 +328,14 @@ | ||
| 324 | 328 | with that user's privileges after it enters the chroot. |
| 325 | 329 | (See [#docker-args | below] for how to change this default.) |
| 326 | 330 | You don't have to restart the server after fixing this with |
| 327 | 331 | <tt>chmod</tt>: simply reload the browser, and Fossil will try again. |
| 328 | 332 | |
| 329 | -This simple method has a problem: Docker containers are designed to be | |
| 333 | + | |
| 334 | +<h4>5.1.2 Storing the Repo Outside the Container</h4> | |
| 335 | + | |
| 336 | +The simple storage method above has a problem: Docker containers are designed to be | |
| 330 | 337 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 331 | 338 | that with the repo inside the container, it gets destroyed, too. The |
| 332 | 339 | solution is to replace the "run" command above with the following: |
| 333 | 340 | |
| 334 | 341 | <pre><code> $ docker create \ |
| 335 | 342 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -273,11 +273,11 @@ | |
| 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. |
| 282 | |
| 283 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| @@ -288,10 +288,13 @@ | |
| 288 | Docker. This is almost certainly not what you want. |
| 289 | |
| 290 | The correct ways put the repo into the <i>container</i> created from the |
| 291 | <i>image</i>, not in the image itself. |
| 292 | |
| 293 | The simplest method is to stop the container if it was running, |
| 294 | then say: |
| 295 | |
| 296 | <pre><code> $ docker cp /path/to/my-project.fossil fossil:/jail/museum/repo.fossil |
| 297 | $ docker start fossil |
| @@ -304,16 +307,17 @@ | |
| 304 | |
| 305 | (The same is true of the default mode of operation: the <tt>fossil |
| 306 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 307 | image.) |
| 308 | |
| 309 | Notice that the name of the repository database likely needs to change |
| 310 | in the copy. The container configuration expects it to be called |
| 311 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 312 | system. This is because there is only one repository inside this |
| 313 | container, so we don't have to name it after the project it contains, as |
| 314 | is traditional. |
| 315 | |
| 316 | If you skip the "chown" command above and put "http://localhost:9999/" into |
| 317 | your browser, expecting to see the copied-in repo's home page, you will |
| 318 | get an opaque "Not Found" error. This is because the user and |
| 319 | group ID of the file will be that of your local user on the container's |
| @@ -324,11 +328,14 @@ | |
| 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 | |
| 334 | <pre><code> $ docker create \ |
| 335 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -273,11 +273,11 @@ | |
| 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 id="docker-storage">5.1 Repository Storage Options</h3> |
| 279 | |
| 280 | If you want the container to serve an existing repository, there are at |
| 281 | least two right ways to do it. |
| 282 | |
| 283 | The wrong way is to use the <tt>Dockerfile COPY</tt> command to bake it |
| @@ -288,10 +288,13 @@ | |
| 288 | Docker. This is almost certainly not what you want. |
| 289 | |
| 290 | The correct ways put the repo into the <i>container</i> created from the |
| 291 | <i>image</i>, not in the image itself. |
| 292 | |
| 293 | |
| 294 | <h4>5.1.1 Storing the Repo Inside the Container</h4> |
| 295 | |
| 296 | The simplest method is to stop the container if it was running, |
| 297 | then say: |
| 298 | |
| 299 | <pre><code> $ docker cp /path/to/my-project.fossil fossil:/jail/museum/repo.fossil |
| 300 | $ docker start fossil |
| @@ -304,16 +307,17 @@ | |
| 307 | |
| 308 | (The same is true of the default mode of operation: the <tt>fossil |
| 309 | server --create</tt> flag initializes a fresh Fossil repo atop the base |
| 310 | image.) |
| 311 | |
| 312 | Notice that the copy command changes the name of the repository database. |
| 313 | The container configuration expects it to be called |
| 314 | <tt>repo.fossil</tt>, which it almost certainly was not out on the host |
| 315 | system. This is because there is only one repository inside this |
| 316 | container, so we don't have to name it after the project it contains, as |
| 317 | is traditional. A generic name lets us hard-code the server start |
| 318 | command. |
| 319 | |
| 320 | If you skip the "chown" command above and put "http://localhost:9999/" into |
| 321 | your browser, expecting to see the copied-in repo's home page, you will |
| 322 | get an opaque "Not Found" error. This is because the user and |
| 323 | group ID of the file will be that of your local user on the container's |
| @@ -324,11 +328,14 @@ | |
| 328 | with that user's privileges after it enters the chroot. |
| 329 | (See [#docker-args | below] for how to change this default.) |
| 330 | You don't have to restart the server after fixing this with |
| 331 | <tt>chmod</tt>: simply reload the browser, and Fossil will try again. |
| 332 | |
| 333 | |
| 334 | <h4>5.1.2 Storing the Repo Outside the Container</h4> |
| 335 | |
| 336 | The simple storage method above has a problem: Docker containers are designed to be |
| 337 | killed off at the slightest cause, rebuilt, and redeployed. If you do |
| 338 | that with the repo inside the container, it gets destroyed, too. The |
| 339 | solution is to replace the "run" command above with the following: |
| 340 | |
| 341 | <pre><code> $ docker create \ |
| 342 |