diff --git a/docs/usage.md b/docs/usage.md index 242a250..2320568 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,6 +4,44 @@ nav_order: 3 # Operating system content and usage +## Configuring systemd units + +To add a custom systemd unit: + +```dockerfile +COPY mycustom.service /usr/lib/systemd/system +RUN ln -s mycustom.service /usr/lib/systemd/system/default.target.wants +``` + +It will *not* work currently to do `RUN systemctl enable mycustom.service` instead +of the second line - unless you also write a +[systemd preset file](https://www.freedesktop.org/software/systemd/man/latest/systemd.preset.html) +enabling that unit. + +### Static enablement versus presets + +systemd presets are designed for "run once" semantics - thereafter, OS upgrades +won't cause new services to start. In contrast, "static enablement" by creating +the symlink (as is done above) bypasses the preset logic. + +In general, it's recommended to follow the "static enablement" approach because +it more closely aligns with "immutable infrastructure" model. + +### Using presets + +If nevertheless you want to use presets instead of "static enablement", One +recommended pattern to avoid this problem (nd is also somewhat of a best +practice anyways) is to use a common prefix (e.g. `examplecorp-` for all of your +custom systemd units), resulting in `examplecorp-checkin.service`, +`examplecorp-agent.service` etc. + +Then you can write a single systemd preset file to e.g. +`/usr/lib/systemd/system-preset/50-examplecorp.preset` that contains: + +```systemd +enable examplecorp-* +``` + ## Automatic updates enabled by default The base image here enables the