Plugin authors: How to get ready for the new website

Announcements
1

We’re making great progress on the new Caddy website (thanks mainly to the Mozilla award last year), although there are still lots of details left before it’s ready to be used. Plugin authors should know of some upcoming changes to prepare for the transition! This is still a couple months out, but I want you to be able to get ready.

The new website has a few static pages, but now most will be dynamic, powered by what I call the Developer Portal (on GitHub). You will create an account with which you can publish your plugins autonomously to the download page. Here’s a high-level look at how this new site will work with regards to plugins.

  • Submitting a plugin: There will be a page where you enter the package import path, the git clone URL, and the version (commit SHA, branch, or tag) to deploy. You will then be asked to enter a description; a few concise, illustrative usage examples; and links to the plugin’s homepage, documentation, and support. For GitHub repos, some of these fields will be filled in automatically for you, with the ability to customize them.

  • Deployments: When you first submit a plugin and any time thereafter, you can initiate a deploy right from the website. An authenticated API endpoint will be made available for you to do this, and in the near future you can deploy with a GitHub webhook. For now, you simply provide the version to deploy:

    plugin-deploy.png884×606 32.9 KB

    Deploys can take a few minutes as checks and tests are performed including go build, go vet, and go test. Builds are tested across several required, common platforms. Any failures will not deploy the new version and you will be given a log to fix it. Please don’t rely on this as a CI system, though. Run tests and checks before you deploy.

  • Dependencies: This new build system does not solve dependency management. Behind the scenes it maintains a GOPATH and runs go get and go get -u in conjunction with git checkout. If your dependencies break often, consider vendoring them. Again, I realize this is not perfect, but it’s still better than what we have now where the GOPATH is manually maintained by me.

  • Documentation: The new website will host all documentation for the HTTP server and its standard directives. All plugins will be shown there as well, along with their descriptions and usage examples. Full documentation will be an off-site link to your own docs page(s). You will be asked to maintain a complete documentation either in a README or a Wiki or some custom website. Hopefully this will be easier than submitting pull requests all the time to the Caddy site. Since the usage examples will be featured on the Caddy site directly, we hope most Caddy users won’t even have to read the full docs to at least get up and running with your plugin.

    docs-page.png2880×3410 150 KB

So the main changes are:

  • You will be able to deploy new releases of your plugin on your own
  • Plugin docs will be kept off-site, except for description and usage examples

I hope everyone will enjoy this new system a lot more. It should free up a lot of my time to stay focused on developing Caddy. Thanks for using Caddy, and for making it awesome with your plugins!

Feel free to comment here if you have any questions.

7 Likes