Crane

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.

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.

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.

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.