Skip to content

docs: add Flox and systemd tutorial#438

Open
jbayer wants to merge 5 commits intomainfrom
tutorial/flox-and-systemd
Open

docs: add Flox and systemd tutorial#438
jbayer wants to merge 5 commits intomainfrom
tutorial/flox-and-systemd

Conversation

@jbayer
Copy link
Contributor

@jbayer jbayer commented Mar 12, 2026

Summary

  • Adds a new tutorial "Flox and systemd" covering how to run Flox environment services as persistent systemd units
  • Covers both systemd user units (for personal accounts) and systemd system units (for dedicated service users)
  • Uses the flox/redis FloxHub environment as a working example

Test plan

  • Verify the tutorial renders correctly with mkdocs serve
  • Verify all internal links resolve (services concept, man pages, sharing guide)
  • Walk through the tutorial steps on an Ubuntu 24.04 system with Flox 1.10.0

🤖 Generated with Claude Code

Add a tutorial covering how to run Flox environment services as
persistent systemd units, both as user units and system units.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jbayer jbayer requested a review from stahnma March 12, 2026 13:10
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Mar 12, 2026
@github-actions
Copy link

Copy link
Contributor

@dcarley dcarley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't tried the instructions end-to-end but happy to pending the conversation in: https://flox-dev.slack.com/archives/C097184TDUL/p1773241852880549

- Add Constraints section documenting known limitations
- Move linger explanation next to the enable-linger command
- Use consistent user/system unit terminology in headings
- Use flox activate -c instead of bash -c in system unit ExecStart
- Use user's own environment for redis-cli verification

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jbayer jbayer requested a review from stahnma March 12, 2026 18:54
@github-actions
Copy link

Add mkdir -p ~/.config/systemd/user/ before creating the unit file
since the directory may not exist on a fresh system.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions
Copy link

- Use flox activate -c consistently instead of -- bash -c
- Use $REDISPORT env var instead of hardcoded port in verify commands
- Add user unit and system unit cleanup sections
- Run flox pull as redis user with sudo -u redis
- Reorder chown before flox pull in system unit setup
- Add mkdir -p for systemd user unit directory

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions
Copy link

Add context explaining why you might want to register Flox services
with systemd, such as auto-starting on boot or crash recovery.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions
Copy link

@jbayer
Copy link
Contributor Author

jbayer commented Mar 12, 2026

Ok, I updated all the issues and tested it on a brand new Ubuntu 24.04 VM and it all worked.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants