Maintenance: Planio will be observing a scheduled maintenance window this Sunday, November 10, 2024 from 20:00 UTC until 21:00 UTC to perform important network maintenance in our primary data center. Your Planio account will be unavailable for a few minutes during this maintenance window.
Issue #2701
closedCrane documentation doesn't answer critical installation and usage questions
Description
I've read through the following:
- https://docs.pulpproject.org/plugins/pulp_docker/user-guide/recipes.html
- https://docs.pulpproject.org/plugins/crane/index.html
- https://github.com/pulp/crane/blob/master/docs/index.rst
None of these documents state how to install Crane. I'd expect to see the following documented:
- How can Crane be installed? Is Crane a pure-Python application that can be installed in all the usual ways, such as in a virtualenv with pip, with
python setup.py install
, withpython setup.py install --user
, from PyPi, etc? Are there distrubution-specific methods for installing Crane, such as with RPMs? Are there other ways? - What is Crane? Is it a daemon? A library? Something else? An experienced Pythonista might intuit that, since Flask is a library for building web applications, Crane is probably a daemon that uses Flask. But others who know less about the Python ecosystem wouldn't be able to figure that out. And a user shouldn't need to care or know about implementation details like which library is used to make Crane.
- How does Crane interact with the rest of the world? Is it a library that other applications use? Is it a daemon that should be started some-how? If a daemon, how can it be started by hand, or by an init system (SysV, systemd)?
- If Crane is a daemon, then how should messages be sent to it? Should the firewall be opened up so that other applications in the wild can talk directly to Crane? Should a web server (like Apache, Nginx, LightTPD, etc) be configured with a reverse proxy?
Updated by mhrivnak over 7 years ago
Fair points. This generally could be more clear.
That said, as for what crane is, I feel like this is fairly clear that it is a python web application:
http://docs.pulpproject.org/plugins/crane/index.html#what-is-crane
Do you have any specific suggestions for improving that? Maybe calling it a WSGI app would help?
And for deployment, this also seems fairly clear that you can install by RPM and look for the example apache config:
http://docs.pulpproject.org/plugins/crane/index.html#deployment
It does assume some familiarity with mod_wsgi, but if you're deploying a WSGI app with apache (or anything else), I think that's reasonable. Should we be more explicit about that? Again, any specific suggestions would be helpful. Maybe we should specifically call out that crane is a WSGI app? That's a well-documented and well-understood deployment model.
Updated by Ichimonji10 over 7 years ago
That said, as for what crane is, I feel like this is fairly clear that it is a python web application: http://docs.pulpproject.org/plugins/crane/index.html#what-is-crane
Yes, that's true. The documentation clearly states that Crane is a Python web application. But that leaves a lot of un-answered questions. To explain, I'll note some concrete examples of web applications that I've encountered, and then then I'll list a few of the questions that are left un-answered by stating that "Crane is a Python web application."
Several years ago, I also worked with several web applications built on Django, for both work and school purposes. When working on each of these project, I had to decide how to deploy them. If you've worked with Django recently, you'll know that they strongly suggest using the WSGI deployment model: HTTP requests are received by a web server, WSGI requests are forwarded to a daemon, and that daemon executes your application's code. However, this didn't used to be the case. I used at least the following deployment options:
- FastCGI
- SCGI
- WSGI
More contemporarily, I also maintain Subsonic and Syncthing installations. The former is a Java application (that makes use of Apache Tomcat), and the latter is a Go application. Both speak HTTP, and can be configured to either directly receive client requests, or to sit behind a proxy.
So, given some web application, there's several questions that must be answered before a system administrator can deploy it:
- Is the web application a stand-alone daemon? Or is the web application embedded into the process space of some other daemon (notably, Apache).
- Assuming the application is a stand-alone daemon, how do I start and stop it? Bonus points for providing systemd unit files and/or SysV scripts.
- Assuming the application is a stand-alone daemon, what protocols does it speak? Does it speak FastCGI, SCGI, WSGI, HTTP, or something else?
- Assuming the application speaks HTTP, is it safe to expose it directly to the world at large? Or should the application be placed behind a reverse proxy?
I think the questions above are essential. I also think that it would be helpful to answer the following:
- Assuming the application is a stand-alone daemon, does it need to run as a particular user or with any special permissions? This is of concern because Crane accesses files created by Pulp.
- Assuming the application is a stand-alone daemon, over which channels can it speak? Can it communicate over a network socket on localhost, over a unix socket, or something else?
- Assuming the application can run behind a reverse proxy, are there special steps that need to be taken to make everything work right? (For a great example of explaining this, see Syncthing's Reverse Proxy Setup page. For a great example of what can go wrong, see Subsonic issue #23 .)
- Given that Crane is a daemon, does it have explicit support for unix signals? For example, can I send a SIGHUP signal to make Crane reload?
- Is the configuration file required or optional?
So, how can we answer these questions? I think a statement like the following would be dramatically helpful:
Crane is a web application that implements a sub-set of the Docker v2 API. It's implemented as a daemon that speaks the WSGI protocol.
There we go. In two sentences, we've explained what Crane is and given a high-level explanation of how to deploy it (set up a web server with a reverse proxy that forwards WSGI messages to a Crane daemon).
Do you have any specific suggestions for improving that? Maybe calling it a WSGI app would help?
Yes, and yes.
And for deployment, this also seems fairly clear that you can install by RPM and look for the example apache config: http://docs.pulpproject.org/plugins/crane/index.html#deployment
That deployment example is lacking. Here's some questions that are left un-answered:
- What is the name of the RPM that should be installed?
- Is the RPM available via the repositories that ship with F24, F25, RHEL 7, etc?
- Is the RPM available via some third-party repository, and can you give me a file that I can plunk in ``/etc/yum.repos.d/``? This is especially useful for other RPM-based distributions, like CentOS.
- What do I do with the sample Apache configuration? Should I install it as ``/etc/httpd/apache.conf``?
- Why are the only mentions of WSGI in the "User Authentication" section? Shouldn't an "Installation" section somewhere else mention WSGI and Crane's deployment model?
Again, any specific suggestions would be helpful.
I have a few more suggestions:
- Document the installation and configuration steps in that order.
- Document which version(s) of Python are supported.
- Document each of the installation methods. I'd recommend listing both "Red Hat / Fedora installation" and "source installation". These don't need to be terribly extensive. Just noting the different options is very helpful.
Updated by elyezer over 7 years ago
Can you also provide more documentation on how to configure Crane with SSL?
That will help testing Crane under https and as a secure registry.
Updated by bmbouter over 5 years ago
- Status changed from NEW to CLOSED - WONTFIX
Updated by bmbouter over 5 years ago
Pulp 2 is approaching maintenance mode, and this Pulp 2 ticket is not being actively worked on. As such, it is being closed as WONTFIX. Pulp 2 is still accepting contributions though, so if you want to contribute a fix for this ticket, please reopen or comment on it. If you don't have permissions to reopen this ticket, or you want to discuss an issue, please reach out via the developer mailing list.