ostree/docs
Colin Walters f81b9fa166 sysroot: Rework /var handling to act like Docker VOLUME /var
We've long struggled with semantics for `/var`.  Our stance of
"/var should start out empty and be managed by the OS" is a strict
one, that pushes things closer to the original systemd upstream
ideal of the "OS state is in /usr".

However...well, a few things.  First, we had some legacy bits
here which were always populating the deployment `/var`.  I don't
think we need that if systemd is in use, so detect if the tree
has `usr/lib/tmpfiles.d`, and don't create that stuff at
`ostree admin stateroot-init` time if so.

Building on that then, we have the stateroot `var` starting out
actually empty.

When we do a deployment, if the stateroot `var` is empty,
make a copy (reflink if possible of course) of the commit's `/var`
into it.

This matches the semantics that Docker created with volumes,
and this is sufficiently simple and easy to explain that I think
it's closer to the right thing to do.

Crucially...it's just really handy to have some pre-existing
directories in `/var` in container images, because Docker (and podman/kube/etc)
don't run systemd and hence don't run `tmpfiles.d` on startup.

I really hit on the fact that we need `/var/tmp` in our container
images by default for example.

So there's still some overlap here with e.g. `/usr/lib/tmpfiles.d/var.conf`
as shipped by systemd, but that's fine - they don't actually conflict
per se.
2024-02-09 17:46:12 -05:00
..
_sass/color_schemes docs: Add Jekyll and theme config 2020-10-01 19:32:12 +02:00
_config.yml docs: Use upstream theme & update to 0.4.1 2023-03-10 12:17:16 +01:00
adapting-existing.md docs: Add var.md 2023-12-08 14:01:13 -05:00
atomic-upgrades.md *: rename master to main in tests & examples 2021-05-07 16:55:03 +02:00
authenticated-repos.md docs: Add authenticated-repos.md 2023-09-27 14:02:55 -04:00
bootloaders.md doc: Add section about ostree and aboot 2024-01-05 17:34:09 +00:00
buildsystem-and-repos.md docs: Fix various typos 2020-10-19 10:55:49 -04:00
composefs.md docs/composefs: Add note about toplevel dirs 2024-01-02 15:18:37 -05:00
contributing-tutorial.md Update doc about adding new function to libostree 2022-07-14 16:05:53 +08:00
CONTRIBUTING.md *: rename master branch to main 2021-05-07 16:55:03 +02:00
deployment.md docs: update boot loader spec link 2023-07-25 21:42:41 +02:00
formats.md lib/core: introduce 'bare-split-xattrs' mode 2022-03-02 16:45:00 +00:00
Gemfile docs: Provide bundler setup for building site locally 2021-05-21 10:13:15 -06:00
ima.md docs/ima: Also link the SUSE docs 2022-05-06 14:43:58 -04:00
index.md Update Torizon information 2023-12-07 10:08:16 -03:00
introduction.md docs: Move and update pages from the manual 2020-10-02 14:34:48 +02:00
prep-docs.sh docs: Publish man pages 2022-04-08 19:25:32 -06:00
README-historical.md docs: Move historical README to the docs 2020-10-02 14:38:28 +02:00
README.md docs: Copy in API docs and add link 2021-05-21 10:46:49 -06:00
related-projects.md Update Torizon information 2023-12-07 10:08:16 -03:00
repo.md lib/core: introduce 'bare-split-xattrs' mode 2022-03-02 16:45:00 +00:00
repository-management.md *: rename master to main in tests & examples 2021-05-07 16:55:03 +02:00
var.md sysroot: Rework /var handling to act like Docker VOLUME /var 2024-02-09 17:46:12 -05:00

This documentation is written in Jekyll format to be published on GitHub Pages. The rendered HTML will be automatically built and published, but you can also use Jekyll locally to test changes.

First you need to install Ruby and RubyGems to get Jekyll and the other gem dependencies. This is easiest using the distro's packages. On RedHat systems this is rubygems and on Debian systems this is ruby-rubygems.

Next Bundler is needed to install the gems using the provided Gemfile. You can do this by running gem install bundler or using distro packages. On RedHat systems this is rubygem-bundler and on Debian systems this is ruby-bundler.

Now you can prepare the Jekyll environment. Change to this directory and run:

bundle config set --local path vendor/bundle
bundle install

Finally, run the prep-docs.sh script and then render and serve the site locally with Jekyll:

./prep-docs.sh
bundle exec jekyll serve