Add a howto for "Deploying Twisted with SystemD"

[Jean-Paul Calderone]

#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.

[Richard Wall]

an example of systemd socket activation of twistd web

[Thijs Triemstra]

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

[Thijs Triemstra]

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.

[Thijs Triemstra]

The documentation builder also ​failed.

[Richard Wall]

Updated systemd socket endpoint documentation addressing code review comments from thijs

[Richard Wall]

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.

[Jean-Paul Calderone]

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!

[Richard Wall]

Updated patch

[Richard Wall]

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.

[Tom Prince]

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.

[Richard Wall]

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​

[Richard Wall]

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

[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?

[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.

[Tom Prince]

(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.