Opened 6 years ago

Closed 5 years ago

#5601 enhancement closed fixed (fixed)

Add a howto for "Deploying Twisted with SystemD"

Reported by: Jean-Paul Calderone Owned by: Tom Prince
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Thijs Triemstra, Richard Wall Branch: branches/systemd-howto-5601
branch-diff, diff-cov, branch-cov, buildbot
Author: rwall

Description

#5575 adds a systemd endpoint for setting up servers using sockets inherited from systemd. This requires some configuration, though. We should have a brief howto pointing out the basics necessary for using this feature.

Attachments (4)

5601-systemd-documentation.patch (4.9 KB) - added by Richard Wall 6 years ago.
an example of systemd socket activation of twistd web
systemd-howto-5601-2.patch (6.8 KB) - added by Richard Wall 5 years ago.
Updated systemd socket endpoint documentation addressing code review comments from thijs
systemd-howto-5601-3.patch (22.3 KB) - added by Richard Wall 5 years ago.
Updated patch
systemd-howto-5601-4.patch (16.0 KB) - added by Richard Wall 5 years ago.
Updated patch against source:branches/systemd-howto-5601 addressing code review comments in #comment:8

Download all attachments as: .zip

Change History (16)

Changed 6 years ago by Richard Wall

an example of systemd socket activation of twistd web

comment:1 Changed 6 years ago by Thijs Triemstra

Cc: Thijs Triemstra added
Keywords: review added

Thanks for the patch. Putting it up for review, as outlined on ReviewProcess#Authors:Howtogetyourchangereviewed.

comment:2 Changed 6 years ago by Thijs Triemstra

Author: rwall
Branch: branches/systemd-howto-5601
Keywords: review removed
Owner: set to Richard Wall

Thanks for your patch.

  1. this needs a .doc news file as described on ReviewProcess#Newsfiles
  2. Combinator in doc/core/howto/endpoints.xhtml should be linked to the wikli page?.
  3. systemd can use a link to the API documentation
  4. period behind until the first client connects
  5. curl can use an external link
  6. --nodaemon, PYTHONPATH, and index=0 should be wrapped in <code></code>
  7. twisted should be Twisted

Please diff against the branch for future patches.

comment:3 Changed 6 years ago by Thijs Triemstra

The documentation builder also failed.

Changed 5 years ago by Richard Wall

Attachment: systemd-howto-5601-2.patch added

Updated systemd socket endpoint documentation addressing code review comments from thijs

comment:4 Changed 5 years ago by Richard Wall

Keywords: review added
Owner: Richard Wall deleted

Ready for another review in attachment:systemd-howto-5601-2.patch

  • I addressed all of thijs comments
  • fixed the broken xhtml
  • added some further links
  • re-tested on Fedora 17
  • Note: The patch does contain a topfile but its empty and doesn't show up in the trac diff viewer.
  • Note: This patch is against trunk not the branch above.

-RichardW.

comment:5 Changed 5 years ago by Jean-Paul Calderone

Owner: set to Jean-Paul Calderone
Status: newassigned

comment:6 Changed 5 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: changed from Jean-Paul Calderone to Richard Wall
Status: assignednew

Thanks for your continued work on this. I'm pretty happy we might get docs for using systemd support in less than a year after getting systemd support in. ;)

  1. I think this whole section added to endpoints.xhtml would be better as the start of a brand new document about deploying Twisted applications. The brief systemd example already in endpoints.xhtml can link people to the new document. Adding all of this systemd material to the endpoints document is going to mostly be presenting it to the wrong audience.
  2. I'm not sure it's a good idea to involve Combinator in the example. Hardly anyone has any idea what Combinator is. Practically no one is going to want to deploy a Twisted service using it, let alone a systemd managed service (I suspect). If the idea is to demonstrate setting something in the environment, then something more generally known or used might be better - perhaps OPENSSL_CONF (which I think Twisted's SSL support will even respect (by accident)). Something even more widely known and simple would be better, but I can't think of any other interesting environment variables from the real world right now.
  3. This is a pretty big chunk of nice documentation. I think it merits a topfile with some contents, rather than just a misc!

Changed 5 years ago by Richard Wall

Attachment: systemd-howto-5601-3.patch added

Updated patch

comment:7 Changed 5 years ago by Richard Wall

Keywords: review added
Owner: Richard Wall deleted

Ready for another review in attachment:systemd-howto-5601-3.patch

  • Moved all the systemd documentation to a separate file
  • Linked to it from the core deployment overview page
  • Separate sections for starting a twisted service statically
  • ...and starting a twisted service with socket activation.

This patch is against trunk.

-RichardW.

comment:8 Changed 5 years ago by Tom Prince

Keywords: review removed
Owner: set to Richard Wall

Thanks for your work on this.

  1. Man page urls should probably point at freedesktop.org rather than at 0pointer.de.
  2. sudo probably isn't needed for status.
  3. The [Install] section is implicitly reference (in the discussion of the symlink created by systemd enable), but nowhere explained.
  4. It might be worth pointing out that using socket activation allows you bind privileged ports (i.e. <1024) while running as non-root.
  5. There is an error building documentation. I think this is probably due to the heading Create a systemd.service file containing a link. (Please file a ticket for getting lore to support this for latex)

Please resubmit, with a patch against the branch, after addressing the above point.

comment:9 in reply to:  8 Changed 5 years ago by Richard Wall

Cc: Richard Wall added
Keywords: review added
Owner: Richard Wall deleted

Replying to tom.prince:

Thanks for your work on this.

  1. Man page urls should probably point at freedesktop.org rather than at [http://0pointer.de/public/systemd-man/ 0pointer.de].

Yep, I agree. Done.

  1. sudo probably isn't needed for status.

Done.

  1. The [Install] section is implicitly reference (in the discussion of the symlink created by systemd enable), but nowhere explained.

Done.

  1. It might be worth pointing out that using socket activation allows you bind privileged ports (i.e. <1024) while running as non-root.

Added a paragraph to that effect and reformatted the socekt activation quote to make it more readable. It isn't actually a very readable explanation, but I couldn't think of anything better.

  1. There is an error building documentation. I think this is probably due to the heading Create a systemd.service file containing a link. (Please file a ticket for getting lore to support this for latex)

Lore seems to build the docs fine for me...

[richard@zorin doc]$ ../bin/lore/lore --config template=core/howto/template.tpl
[########################################] (*Done*)                            s)h)rred)

...maybe the buildbot has a different version of lore.

Anyway, I removed the links from the headings - hopefully that will fix the problem.

Please resubmit, with a patch against the branch, after addressing the above point.

  • I also deleted a couple of old listings files which were introduced to this branch by a previous patch.
  • Used the word "directive" instead of "option"

See attachment:systemd-howto-5601-4.patch

Changed 5 years ago by Richard Wall

Attachment: systemd-howto-5601-4.patch added

Updated patch against source:branches/systemd-howto-5601 addressing code review comments in #comment:8

comment:10 Changed 5 years ago by Richard Wall

One other thing. I think the topfile has wrong extension. Should be...

twisted/topfiles/5601.feature => twisted/topfiles/5601.doc

...can the reviewer / merger do that for me in the branch?

comment:11 Changed 5 years ago by Tom Prince

Keywords: review removed
Owner: set to Tom Prince

One last point,

  1. In the see also, link to the main systemd page: http://www.freedesktop.org/wiki/Software/systemd/ rather than the list of man page.

I'll merge with this change.

comment:12 Changed 5 years ago by Tom Prince

Resolution: fixed
Status: newclosed

(In [37132]) Merge systemd-howto-5601: Add a howto for "Deploying Twisted with SystemD"

Author: rwall Reviewers: thijs, exarkun, tom.prince Fixes: #5601

A new "Deploying Twisted with systemd" howto document which demonstrates how to start a Twisted service using systemd socket activation.

Note: See TracTickets for help on using tickets.