Fossil SCM

Assorted prose polishing in the new systemd-container section at the end of the containers doc.

wyoung 2022-12-03 11:55 trunk
Commit 120a2076318078a3f70fc595787d51345f6533d5fd1ba5021dbe93eda3191e39
Parent b7edb5f1c5b0936…
1 file changed +48 -38
~ www/containers.md
M www/containers.md
+48 -38
--- www/containers.md
+++ www/containers.md
@@ -719,28 +719,30 @@
719719
 ```
720720
721721
 That command assumes the primary test environment for
722722
 this guide, Ubuntu 22.04 LTS with `systemd` 249. For best
723723
 results, `/var/lib/machines` should be a btrfs volume, because
724
-[`$REASONS`][mcfad]. (For CentOS Stream 9 and other Red Hattish
724
+[`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish
725725
 systems, you will have to make serveral adjustments, which we’ve
726
-collected [below](#nspawn-centos) to keep these examples clear.)
726
+collected [below](#nspawn-centos) to keep these examples clear.
727
+
728
+We’ll assume your Fossil repository stores sometning called
729
+“`myproject`” within `~/museum/myproject/repo.fossil`, named according
730
+to the reasons given [above](#repo-inside). We’ll make consistent use of
731
+this naming scheme in the examples below so that you will be able to
732
+replace the “`myproject`” element of the various file and path names.
727733
728734
 The first configuration step is to convert the Docker container into
729
-a “machine”, as systemd calls it. The easiest method is:
735
+a “machine,” as `systemd` calls it. The easiest method is:
730736
731737
 ```
732738
 $ make container
733739
 $ docker container export $(make container-version) |
734740
 machinectl import-tar - myproject
735741
 ```
736742
737
-It’s important that the name of the machine you create —
738
-“`myproject`” in this example — matches the base name
739
-of the nspawn configuration file you create as the next step.
740
-Therefore, to extend the example, the following file needs to be
741
-called `/etc/systemd/nspawn/myproject.nspawn`, and it will contain
743
+Next, create `/etc/systemd/nspawn/myproject.nspawn`, containing
742744
 something like:
743745
744746
 ----
745747
746748
 ```
@@ -781,19 +783,26 @@
781783
782784
 If you recognize most of that from the `Dockerfile` discussion above,
783785
 congratulations, you’ve been paying attention. The rest should also
784786
 be clear from context.
785787
786
-Some of this is expected to vary. For one, the command given in the
787
-`Parameters` directive assumes [SCGI proxying via nginx][DNT]. For
788
-other use cases, see our collection of [Fossil server configuration
789
-guides][srv], then adjust the command to your local needs.
790
-For another, you will likely have to adjust the `Bind` value to
791
-point at the directory containing the `repo.fossil` file referenced
792
-in the command.
793
-
794
-We also need a generic systemd unit file called
788
+Some of this is expected to vary:
789
+
790
+* The references to `example.com` and `myproject` are stand-ins for
791
+ your actual web site and repository name.
792
+
793
+* The command given in the `Parameters` directive assumes you’re
794
+ setting up [SCGI proxying via nginx][DNT], but with adjustment,
795
+ it’ll work with the other repository service methods we’ve
796
+ [documented][srv].
797
+
798
+* The path in the host-side part of the `Bind` value must point at the
799
+ directory containing the `repo.fossil` file referenced in said
800
+ command so that `/jail/museum/repo.fossil` refers to your repo out
801
+ on the host for the reasons given [above](#repo-outside).
802
+
803
+That being done, we also need a generic systemd unit file called
795804
 `/etc/systemd/system/[email protected]`, containing:
796805
797806
 ----
798807
799808
 ```
@@ -813,50 +822,51 @@
813822
814823
 You shouldn’t have to change any of this because we’ve given the
815824
 `--setting=override` flag, meaning any setting in the nspawn file
816825
 overrides the setting passed to `systemd-nspawn`. This arrangement
817826
 not only keeps the unit file simple, it allows multiple services to
818
-share the base configuration, varying on a per-repo level.
827
+share the base configuration, varying on a per-repo level through
828
+adjustments to their individual `*.nspawn` files.
819829
820
-Start the service in the normal way:
830
+You may then start the service in the normal way:
821831
822832
 ```
823833
 $ sudo systemctl enable fossil@myproject
824834
 $ sudo systemctl start fossil@myproject
825835
 ```
826836
827
-You should find it running on localhost port 9000 per the nspawn
837
+You should then find it running on localhost port 9000 per the nspawn
828838
 configuration file above, suitable for proxying Fossil out to the
829
-public using nginx, via SCGI. If you aren’t using a front-end proxy
830
-and want Fossil exposed to the world, you might say this instead in
831
-the `nspawn` file:
839
+public using nginx via SCGI. If you aren’t using a front-end proxy
840
+and want Fossil exposed to the world via HTTPS, you might say this instead in
841
+the `*.nspawn` file:
832842
833843
 ```
834
-Parameters=bin/fossil server \
835
- --cert /path/to/my/fullchain.pem \
836
- --chroot /jail \
837
- --create \
838
- --jsmode bundled \
839
- --port 443 \
840
- --user admin \
844
+Parameters=bin/fossil server \
845
+ --cert /path/to/cert.pem \
846
+ --chroot /jail \
847
+ --create \
848
+ --jsmode bundled \
849
+ --port 443 \
850
+ --user admin \
841851
 museum/repo.fossil
842852
 ```
843853
844854
 You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability
845855
 to allow Fossil to bind to this low-numbered port.
846856
847
-We use systemd’s template file feature to allow multiple Fossil
857
+We use of systemd’s template file feature to allow multiple Fossil
848858
 servers running on a single machine, each on a different TCP port,
849859
 as when proxying them out as subdirectories of a larger site.
850860
 To add another project, you must first clone the base “machine” layer:
851861
852862
 ```
853863
 $ sudo machinectl clone myproject otherthing
854864
 ```
855865
856866
 That will not only create a clone of `/var/lib/machines/myproject`
857
-as `../otherthing`, it will create a matching `nspawn` file for you
867
+as `../otherthing`, it will create a matching `otherthing.nspawn` file for you
858868
 as a copy of the first one. Adjust its contents to suit, then enable
859869
 and start it as above.
860870
861871
 [mcfad]: https://www.freedesktop.org/software/systemd/man/machinectl.html#Files%20and%20Directories
862872
@@ -863,34 +873,34 @@
863873
864874
 ### 6.3.1 <a id="nspawn-rhel"></a>Getting It Working on a RHEL Clone
865875
866876
 The biggest difference between doing this on OSes like CentOS versus
867877
 Ubuntu is that RHEL (thus also its clones) doesn’t ship btrfs in
868
-its kernel, thus has no option for installing `mkfs.btrfs`, which
869
-[`machinectl`][mctl] needs for various purposes.
878
+its kernel, thus ships with no package repositories containing `mkfs.btrfs`, which
879
+[`machinectl`][mctl] depends on for achieving its various purposes.
870880
871881
 Fortunately, there are workarounds.
872882
873883
 First, the `apt install` command above becomes:
874884
875885
 ```
876886
 $ sudo dnf install systemd-container
877887
 ```
878888
879
-Second, you have to hack around the lack of `machinectl import-tar` so:
889
+Second, you have to hack around the lack of `machinectl import-tar`:
880890
881891
 ```
882892
 $ rootfs=/var/lib/machines/fossil
883893
 $ sudo mkdir -p $rootfs
884894
 $ docker container export fossil | sudo tar -xf -C $rootfs -
885895
 ```
886896
887897
 The parent directory path in the `rootfs` variable is important,
888
-because although we aren’t using `machinectl`, the `systemd-nspawn`
889
-developers assume you’re using them together. Thus, when you give
898
+because although we aren’t able to use `machinectl` on such systems, the
899
+`systemd-nspawn` developers assume you’re using them together; when you give
890900
 `--machine`, it assumes the `machinectl` directory scheme. You could
891
-instead use `--directory`, allowing you to store the rootfs whereever
901
+instead use `--directory`, allowing you to store the rootfs wherever
892902
 you like, but why make things difficult? It’s a perfectly sensible
893903
 default, consistent with the [LHS] rules.
894904
895905
 The final element &mdash; the machine name &mdash; can be anything
896906
 you like so long as it matches the nspawn file’s base name.
897907
--- www/containers.md
+++ www/containers.md
@@ -719,28 +719,30 @@
719 ```
720
721 That command assumes the primary test environment for
722 this guide, Ubuntu 22.04 LTS with `systemd` 249. For best
723 results, `/var/lib/machines` should be a btrfs volume, because
724 [`$REASONS`][mcfad]. (For CentOS Stream 9 and other Red Hattish
725 systems, you will have to make serveral adjustments, which we’ve
726 collected [below](#nspawn-centos) to keep these examples clear.)
 
 
 
 
 
 
727
728 The first configuration step is to convert the Docker container into
729 a “machine”, as systemd calls it. The easiest method is:
730
731 ```
732 $ make container
733 $ docker container export $(make container-version) |
734 machinectl import-tar - myproject
735 ```
736
737 It’s important that the name of the machine you create &mdash;
738 “`myproject`” in this example &mdash; matches the base name
739 of the nspawn configuration file you create as the next step.
740 Therefore, to extend the example, the following file needs to be
741 called `/etc/systemd/nspawn/myproject.nspawn`, and it will contain
742 something like:
743
744 ----
745
746 ```
@@ -781,19 +783,26 @@
781
782 If you recognize most of that from the `Dockerfile` discussion above,
783 congratulations, you’ve been paying attention. The rest should also
784 be clear from context.
785
786 Some of this is expected to vary. For one, the command given in the
787 `Parameters` directive assumes [SCGI proxying via nginx][DNT]. For
788 other use cases, see our collection of [Fossil server configuration
789 guides][srv], then adjust the command to your local needs.
790 For another, you will likely have to adjust the `Bind` value to
791 point at the directory containing the `repo.fossil` file referenced
792 in the command.
793
794 We also need a generic systemd unit file called
 
 
 
 
 
 
 
795 `/etc/systemd/system/[email protected]`, containing:
796
797 ----
798
799 ```
@@ -813,50 +822,51 @@
813
814 You shouldn’t have to change any of this because we’ve given the
815 `--setting=override` flag, meaning any setting in the nspawn file
816 overrides the setting passed to `systemd-nspawn`. This arrangement
817 not only keeps the unit file simple, it allows multiple services to
818 share the base configuration, varying on a per-repo level.
 
819
820 Start the service in the normal way:
821
822 ```
823 $ sudo systemctl enable fossil@myproject
824 $ sudo systemctl start fossil@myproject
825 ```
826
827 You should find it running on localhost port 9000 per the nspawn
828 configuration file above, suitable for proxying Fossil out to the
829 public using nginx, via SCGI. If you aren’t using a front-end proxy
830 and want Fossil exposed to the world, you might say this instead in
831 the `nspawn` file:
832
833 ```
834 Parameters=bin/fossil server \
835 --cert /path/to/my/fullchain.pem \
836 --chroot /jail \
837 --create \
838 --jsmode bundled \
839 --port 443 \
840 --user admin \
841 museum/repo.fossil
842 ```
843
844 You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability
845 to allow Fossil to bind to this low-numbered port.
846
847 We use systemd’s template file feature to allow multiple Fossil
848 servers running on a single machine, each on a different TCP port,
849 as when proxying them out as subdirectories of a larger site.
850 To add another project, you must first clone the base “machine” layer:
851
852 ```
853 $ sudo machinectl clone myproject otherthing
854 ```
855
856 That will not only create a clone of `/var/lib/machines/myproject`
857 as `../otherthing`, it will create a matching `nspawn` file for you
858 as a copy of the first one. Adjust its contents to suit, then enable
859 and start it as above.
860
861 [mcfad]: https://www.freedesktop.org/software/systemd/man/machinectl.html#Files%20and%20Directories
862
@@ -863,34 +873,34 @@
863
864 ### 6.3.1 <a id="nspawn-rhel"></a>Getting It Working on a RHEL Clone
865
866 The biggest difference between doing this on OSes like CentOS versus
867 Ubuntu is that RHEL (thus also its clones) doesn’t ship btrfs in
868 its kernel, thus has no option for installing `mkfs.btrfs`, which
869 [`machinectl`][mctl] needs for various purposes.
870
871 Fortunately, there are workarounds.
872
873 First, the `apt install` command above becomes:
874
875 ```
876 $ sudo dnf install systemd-container
877 ```
878
879 Second, you have to hack around the lack of `machinectl import-tar` so:
880
881 ```
882 $ rootfs=/var/lib/machines/fossil
883 $ sudo mkdir -p $rootfs
884 $ docker container export fossil | sudo tar -xf -C $rootfs -
885 ```
886
887 The parent directory path in the `rootfs` variable is important,
888 because although we aren’t using `machinectl`, the `systemd-nspawn`
889 developers assume you’re using them together. Thus, when you give
890 `--machine`, it assumes the `machinectl` directory scheme. You could
891 instead use `--directory`, allowing you to store the rootfs whereever
892 you like, but why make things difficult? It’s a perfectly sensible
893 default, consistent with the [LHS] rules.
894
895 The final element &mdash; the machine name &mdash; can be anything
896 you like so long as it matches the nspawn file’s base name.
897
--- www/containers.md
+++ www/containers.md
@@ -719,28 +719,30 @@
719 ```
720
721 That command assumes the primary test environment for
722 this guide, Ubuntu 22.04 LTS with `systemd` 249. For best
723 results, `/var/lib/machines` should be a btrfs volume, because
724 [`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish
725 systems, you will have to make serveral adjustments, which we’ve
726 collected [below](#nspawn-centos) to keep these examples clear.
727
728 We’ll assume your Fossil repository stores sometning called
729 “`myproject`” within `~/museum/myproject/repo.fossil`, named according
730 to the reasons given [above](#repo-inside). We’ll make consistent use of
731 this naming scheme in the examples below so that you will be able to
732 replace the “`myproject`” element of the various file and path names.
733
734 The first configuration step is to convert the Docker container into
735 a “machine,” as `systemd` calls it. The easiest method is:
736
737 ```
738 $ make container
739 $ docker container export $(make container-version) |
740 machinectl import-tar - myproject
741 ```
742
743 Next, create `/etc/systemd/nspawn/myproject.nspawn`, containing
 
 
 
 
744 something like:
745
746 ----
747
748 ```
@@ -781,19 +783,26 @@
783
784 If you recognize most of that from the `Dockerfile` discussion above,
785 congratulations, you’ve been paying attention. The rest should also
786 be clear from context.
787
788 Some of this is expected to vary:
789
790 * The references to `example.com` and `myproject` are stand-ins for
791 your actual web site and repository name.
792
793 * The command given in the `Parameters` directive assumes you’re
794 setting up [SCGI proxying via nginx][DNT], but with adjustment,
795 it’ll work with the other repository service methods we’ve
796 [documented][srv].
797
798 * The path in the host-side part of the `Bind` value must point at the
799 directory containing the `repo.fossil` file referenced in said
800 command so that `/jail/museum/repo.fossil` refers to your repo out
801 on the host for the reasons given [above](#repo-outside).
802
803 That being done, we also need a generic systemd unit file called
804 `/etc/systemd/system/[email protected]`, containing:
805
806 ----
807
808 ```
@@ -813,50 +822,51 @@
822
823 You shouldn’t have to change any of this because we’ve given the
824 `--setting=override` flag, meaning any setting in the nspawn file
825 overrides the setting passed to `systemd-nspawn`. This arrangement
826 not only keeps the unit file simple, it allows multiple services to
827 share the base configuration, varying on a per-repo level through
828 adjustments to their individual `*.nspawn` files.
829
830 You may then start the service in the normal way:
831
832 ```
833 $ sudo systemctl enable fossil@myproject
834 $ sudo systemctl start fossil@myproject
835 ```
836
837 You should then find it running on localhost port 9000 per the nspawn
838 configuration file above, suitable for proxying Fossil out to the
839 public using nginx via SCGI. If you aren’t using a front-end proxy
840 and want Fossil exposed to the world via HTTPS, you might say this instead in
841 the `*.nspawn` file:
842
843 ```
844 Parameters=bin/fossil server \
845 --cert /path/to/cert.pem \
846 --chroot /jail \
847 --create \
848 --jsmode bundled \
849 --port 443 \
850 --user admin \
851 museum/repo.fossil
852 ```
853
854 You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability
855 to allow Fossil to bind to this low-numbered port.
856
857 We use of systemd’s template file feature to allow multiple Fossil
858 servers running on a single machine, each on a different TCP port,
859 as when proxying them out as subdirectories of a larger site.
860 To add another project, you must first clone the base “machine” layer:
861
862 ```
863 $ sudo machinectl clone myproject otherthing
864 ```
865
866 That will not only create a clone of `/var/lib/machines/myproject`
867 as `../otherthing`, it will create a matching `otherthing.nspawn` file for you
868 as a copy of the first one. Adjust its contents to suit, then enable
869 and start it as above.
870
871 [mcfad]: https://www.freedesktop.org/software/systemd/man/machinectl.html#Files%20and%20Directories
872
@@ -863,34 +873,34 @@
873
874 ### 6.3.1 <a id="nspawn-rhel"></a>Getting It Working on a RHEL Clone
875
876 The biggest difference between doing this on OSes like CentOS versus
877 Ubuntu is that RHEL (thus also its clones) doesn’t ship btrfs in
878 its kernel, thus ships with no package repositories containing `mkfs.btrfs`, which
879 [`machinectl`][mctl] depends on for achieving its various purposes.
880
881 Fortunately, there are workarounds.
882
883 First, the `apt install` command above becomes:
884
885 ```
886 $ sudo dnf install systemd-container
887 ```
888
889 Second, you have to hack around the lack of `machinectl import-tar`:
890
891 ```
892 $ rootfs=/var/lib/machines/fossil
893 $ sudo mkdir -p $rootfs
894 $ docker container export fossil | sudo tar -xf -C $rootfs -
895 ```
896
897 The parent directory path in the `rootfs` variable is important,
898 because although we aren’t able to use `machinectl` on such systems, the
899 `systemd-nspawn` developers assume you’re using them together; when you give
900 `--machine`, it assumes the `machinectl` directory scheme. You could
901 instead use `--directory`, allowing you to store the rootfs wherever
902 you like, but why make things difficult? It’s a perfectly sensible
903 default, consistent with the [LHS] rules.
904
905 The final element &mdash; the machine name &mdash; can be anything
906 you like so long as it matches the nspawn file’s base name.
907

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button