search

haraka / Haraka

A fast, highly extensible, and event driven SMTP server
https://haraka.github.io
MIT License
5.09k stars 661 forks source link

provide default ini config file for every plugin #1376

Closed celesteking closed 8 years ago

celesteking commented 8 years ago

please

msimerson commented 8 years ago

Why?

Unless you have some good reason which didn't come up in #1339, and which also somehow avoids the "how do we keep installed/config up-to-date," we are likely to decline this request.

celesteking commented 8 years ago

There's no clamd config in haraka dir either.

The reason is to see what are the default options and what options are available. (quick list without the need of documentation scan)

celesteking commented 8 years ago

That is, I don't need the config to be installed, I need a quick list of all options and their default values.

msimerson commented 8 years ago

We have already provided exactly that.

baudehlo commented 8 years ago

I do think default options should be put into the core config file now, not just documented.

On Fri, Mar 4, 2016 at 1:35 PM, Matt Simerson notifications@github.com wrote:

We have already provided exactly that https://github.com/haraka/Haraka/blob/master/docs/plugins/clamd.md#configuration .

— Reply to this email directly or view it on GitHub https://github.com/haraka/Haraka/issues/1376#issuecomment-192400345.

celesteking commented 8 years ago

Yes, that might work, but would require going through documentation and fishing out parameters. for ex https://github.com/haraka/Haraka/blob/master/docs/plugins/limit.md or https://github.com/haraka/Haraka/blob/master/docs/plugins/relay.md -- a lot of text. access.md is much better , though.

baudehlo commented 8 years ago

This should be turned into a bigger ticket, something along the lines of: "Now config is not copied over, every plugin with INI config should have a default config file showing the defaults".

On Fri, Mar 4, 2016 at 1:53 PM, celesteking notifications@github.com wrote:

Yes, that might work, but would require going through documentation and fishing out parameters. for ex https://github.com/haraka/Haraka/blob/master/docs/plugins/limit.md or https://github.com/haraka/Haraka/blob/master/docs/plugins/relay.md -- a lot of text. access.md is much better , though.

— Reply to this email directly or view it on GitHub https://github.com/haraka/Haraka/issues/1376#issuecomment-192408194.

msimerson commented 8 years ago

Now [that] config is not copied over, every plugin with INI config should have a default config file showing the defaults

+1

msimerson commented 8 years ago

I'd also like to remove all of the config sections from the .md files, instead putting them inline (with comments) in the .ini files, and just adding a reference with a URL in the documentation.

baudehlo commented 8 years ago

That will not be very nice for people reading on the web site.

On Fri, Mar 4, 2016 at 2:16 PM, Matt Simerson notifications@github.com wrote:

Reopened #1376 https://github.com/haraka/Haraka/issues/1376.

— Reply to this email directly or view it on GitHub https://github.com/haraka/Haraka/issues/1376#event-578232790.

msimerson commented 8 years ago

That will not be very nice for people reading on the web site.

It could actually be a nicer experience. The easy not-so-great experience is a link to the .ini file, which is dead simple. The much-nicer-experience would be for the web site to include the .ini file inline, nicely formatted with syntax coloring like GitHub does for .ini code blocks (ie, much better than a <pre> tag).

smfreegard commented 8 years ago

No all plugins use the .ini format, so comments would be an issue in those cases.

IMO - this is a retrograde step, people will be less likely to read the docs if the .ini has everything in-line and therefore we'll end up doing more support for people who can't be arsed to read the docs.

msimerson commented 8 years ago

people will be less likely to read the docs if the .ini has everything in-line

People have no choice but to read the docs, as we no longer install default config files.

The question is a matter of imposing a development and maintenance burden on developers, having to maintain configuration documentation in the config file and the docs, or just in the config files themselves.

sumpton commented 8 years ago

I gag on concepts like "people will be less likely to read the docs if the .ini has everything in-line"

Good documentation, I suggest, can lead readers in any number of ways. It just takes notes. "More details here [link]". Also, there are examples of good documentation all over the place (Internet). I won't suggest the ones that come to mind for me, because I personally don't care what style or approach you adopt, or who you copy, but I do suggest not reinventing.

I am new to this project, and have dreams of using it extensively for a project. I currently don't know if there will be a demand for the functionality, but I can't think of a better project to work with. I have used MTA's more than casual since 1996, and got out of hosting about 75,000 accounts by migrating to Rackspace about 8 years ago. What a relief!

We are working on a project we hope scales, and our base technology is Node.js, so the attraction to Haraka is obvious, and I am grateful it exists. I would likely have used Exim, but now like very much that one Node script will rewrite both from and two, with Redis lookups for both, error where it should.

This long preamble is to simply say that Haraka is another important project on our already complicated stack. The desire is not to need to become expert with everything. I found getting started with Haraka challenging, and have needed to research lots of inconsistencies, and drill down into code to find out how it works, or if there is a pattern I am missing. It took days instead of hours.

The documentation that exists is pretty good, but it is not organized in a way that gives confidence that what has not been read is essential. I found I had to read everything, some several times, just to get going. Smarter people likely get there much faster.

I learn best with working examples. I found the default plugins.ini to be confusing. The order made sense but I didn't instantly understand that would script could hook all the events. Once understood, the design is pretty great.

I suggest one or two basic, but practical configurations. Just add comments to the directives in the "ini" files, or have a section of recipes for how to do something, and tie it the already great documentation from them. Or, just copy someone you think is doing a great job.

I would like to see Redis used consistently, and supporting ioredis, because our primary Redis store is a Cluster.

Again, I do appreciate all the work that has been invested into Haraka. Thanks.

baudehlo commented 8 years ago

I'd love to see some love given to the haraka.github.com repository that supported this kind of thing. Meanwhile fix the document titles code which is massively broken.

On Fri, Mar 4, 2016 at 2:26 PM, Matt Simerson notifications@github.com wrote:

That will not be very nice for people reading on the web site.

It could actually be a nicer experience. The easy not-so-great experience is a link to the .ini file, which is dead simple. The much-nicer-experience would be for the web site to include the .ini file inline, nicely formatted like GitHub does for .ini code blocks (ie, much better than a

 tag).

—
Reply to this email directly or view it on GitHub
https://github.com/haraka/Haraka/issues/1376#issuecomment-192428114.
msimerson commented 8 years ago

I found getting started with Haraka challenging, and have needed to research lots of inconsistencies, and drill down into code to find out how it works, or if there is a pattern I am missing. It took days instead of hours.

We hear you. In the meantime, there are two install guides on the wiki.

I would like to see Redis used consistently, and supporting ioredis, because our primary Redis store is a Cluster.

We are nearly there. Last year, we had 5 plugins each with duplicated redis functions. Now all the redis-using plugins inherit from the redis plugin. It's now a SMOP to update the redis plugin and add a config setting which chooses which redis driver to load. PRs are welcome.

sumpton commented 8 years ago

What a nice response; thanks. I appreciate the effort and super pleased that this project is active.

I did enjoy the benefits of the wiki and got a very basic system running, including relaying. One typical use of some systems is to check for an existing alias and not just the domain. I could do this easily now, but it looks pretty obscure when I started.

I also found it confusing how to pass messages between stages, and where to rewrite mail_from (mailFrom :) ). Everything became easy when I understood that several hooks could be in one script -- obvious once you see it, and as I said, others reach enlightenment faster -- I wasn't comfortable using notes. As it is, I reverted to how we typically message between async stages with a locals object ({}). Now that I have a better understanding of a "connection" and "transaction" things are pretty clear.

My suggestion is to have one or two plugins that represent best practices, but not overwhelming, with rich comments. The comments could point to documentation, but also act as reminders for the second and third pass through the code. One example could have several hooks, registering them at the top, and perhaps comments at the function definition showing the alternative registering the hook directly -- or making that clear. The other would be one hook example.

My point is that even knowing one script is an example to follow, with notations, makes all the other scripts easier to understand. For me it was a starting point. I forget which one I decided I would use as a guide, but that is how I jumped in for my own custom plugin.

My points of confusion included:

There was more that, but my point is that looking back, all this is pretty simple and the code base is amazing. I just struggled a lot initially, and spent a lot of "what if" time. One of you Gurus would have written my 200 lines -- 20 that do much of anything -- in an hour or so.

The pleasure of Haraka is customizing it, using Node.js, with the comfort of knowing it scales. For me, it is more than I hoped for when looking for solution.

baudehlo commented 8 years ago

I'm going to close this because the changes made in 2.8 (config isn't even copied to local installations) make part of this kind of redundant.

We do need better documentation, but that's not worth having a ticket for - every open source project does.