I would be very grateful for some help here, and would also be happy to offer my help in improving the documentation, but I simply don't know where to start.
I'm trying my best to work my way through the Aegir installation, but after getting very annoyed with it yesterday because it simply wouldn't work, I eventually found that the instructions I was following for 0.3 have been broken for some time. That alone might well explain why a system with so much potential hasn't seen such widespread adoption?
To compound matters further though, the documentation for 0.4 appears to completely omit the instructions on where to download the correct files, and where to place them:
http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=INSTALL.txt;...
I accept I might have failed to notice these instructions elsewhere but, given that a Google search tends to deliver people either to this wiki page - http://groups.drupal.org/aegir-hosting-system/documentation - or to the group homepage - http://groups.drupal.org/aegir-hosting-system - and that none of these pages set out in simple terms what to do, and how to do it, I'm amazed that more people are not asking for help on this.
What am I missing (apart from a brain, I mean!)?
Comments
Ok, made some progress
Ok, I've made some progress, so what's really needed here - I think - is a step that says:
I'm not sure I fully
I'm not sure I fully understood what specifically you had trouble with, but I think I'm seeing where the confusion lay and will do my best..
1) The documentation on groups.drupal.org is community-contributed and not always up to date, accurate, or closely monitored by the developers (though we do our best). We try to state in as many places as possible (especially the release notes, which is where it really matters) that the INSTALL.txt is the canonical, supported document for installing Aegir. If you want to successfully install Aegir, follow the INSTALL.txt. It seems like you found this in the end
2) Your frustration largely seems to be surrounding the fact that we don't document how to download or get the install.sh script onto your server. The INSTALL.txt document states:
This file is available alongside this one or can be downloaded through the web at:
http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=install.sh.txt;hb=provision-0.4-alpha8
(technically the install.sh.txt is found in /var/aegir/.drush/provision/, one level up from the INSTALL.txt now - I'll correct this in the docs)
In short, it doesn't really matter how you grab the install.sh.txt, as long as you get a copy of it on your server. I feel this is kind of implied by 'can be downloaded' - how else are you going to execute a script before you put it on your server? I may be missing the problem here but it seems clear to me.
I tend to grab the install.sh with curl -L -o install.sh 'http://git.aegirproject.org/....path to the install.sh.txt', but you can do it any way, even copying and pasting the script from a web browser into an empty file on your server.
3)
You wrote this:
su -s /bin/sh aegir -c "./install.sh -w [unix webserver group, e.g. www-data] -d [/path/to/aegir/home] [site URL]"These extra parameters aren't really required on at least Debian or Ubuntu servers - what OS were you using? If you were using a different OS, did you follow the HINTS txt file alongside the INSTALL.txt for your particular OS?
Since they aren't usually needed, they aren't stated explicitely in the INSTALL.txt. If you run install.sh.txt with -h, you get a list of optional and required parameters to the script - just like any other (decent) program you'd run on Linux.
4)
f you see the following:
"Installed apache configuration file for aegir.clients.tui.co.uk, you will need to restart apache"
... then you can restart apache using the following on [default Linux flavour], or the correct version for your Linux flavour:
[default apache restart command]
You won't ever not see that message, since once an apache vhost has been written, Apache will need to be restarted.
The method of restarting apache varies per OS (not just per Linux distribution) - the differences are handled in the HINTS files that are OS/distro-specific. The main INSTALL.txt is Debian-centric, although not too much.
As soon as we put something in there like 'restart it with /etc/init.d/apache2 restart, or your distro's specific method', we'll have support requests on why it didn't work :) instead, we try to keep it as generic as possible, with specifics in HINTS_$OS.txt files. So I think we are making the assumption here that if you are running your own server and have root access, you know how to restart apache. If you've an exotic flavour of Linux or another OS like Solaris where you're totally not sure, that's what the HINTS files are for.
Sorry to hear you had a frustrating time installing Aegir. It sounded like you ended up on the right path (following the INSTALL.txt), but a couple issues tripped you up, or you're running a version of Linux where some things weren't handled automatically (like you passing -d to the install.sh script), in which case the HINTS file for your OS might've come in handy.
I've a somewhat out of date screencast on installing alpha5 here. The next release of Aegir will feature a much simpler installation, whereby only the dependencies and install script need to be run (no install profile wizard with lots of steps afterward).
We can perhaps more explicitely state what to do with the install.sh script (download it and put it on your server), I just don't know what the alternative is that people have been doing :) it seems obvious to me. And I'll update the INSTALL.txt on where to find the version of the script that actually comes shipped with Provision.
Good luck!
Hi mig5, Thank you for your
Hi mig5,
Thank you for your detailed reply; I'm very grateful for your time! Apologies for not replying sooner but I've been away for a couple of days and didn't want to rush an answer out.
I also want to preface this answer with a very important point: no doubt the things I say or ask here will level some criticism at the hard-working folks who have contributed to Aegir, while my contribution to date has been precisely zero. I'm very conscious of the fact that a natural response to anything I write will be along the lines of "well then sod off, and stop picking on my work!". I do hope, however, that everyone understands that any criticism is constructive, and that the Aegir project is a truly fantastic piece of work which may yet save the world (or at least my remaining non-grey hairs... ;o).
Ok, in reply to your reply:
That's exactly the problem; I think you are over-estimating quite considerably how psychic the readers of the instructions are. In a nut-shell: instructions MUST be explicit, not implicit, as far as reasonably possible. If instructions are going to become long-winded, then we should be using the power of t'interwebs and including links to "find out more".
This, importantly, will mean that the "right" way to write an INSTALL.txt file is no longer as a text file, but as an online handbook; your INSTALL.txt might therefore only contain the following:
INSTALL.txt: We have moved installation instructions on to our website so that you will always have access to the most up-to-date version of this document. For installation instructions, please visit http://www.example.com/aegir-install-txt for the latest instructions and updates.Naturally, this also avoids the "wrong INSTALL.txt" problem I had, which I'll mention in a sec.
There's also a lot of use of the words verging on what I'd describe as "jargon". I had to go away and look up several definitions, e.g. "canonical", which appears a lot in these docs. Certainly, I'm happy to pick up new words - especially those I should maybe know already - but maybe we could aim for a bit more of a Plain English approach to docs?
The main issues I had stemmed from points 1 and 2; I was following the wrong INSTALL.txt (I don't recall seeing a note of the version number at the top of the file; maybe that and a release date would go a long way to fixing this?), and your reply to two I think sums up the issues I've been having.
Thinking about this issue more, I suspect there's possibly a lack of focus throughout all the documentation. Granted, every last bit of it is important to someone, but the overall user experience is hampered because there isn't a learning "curve" at the moment; rather, there appears to very much be a "learning cliff".
And there are blind sheep at the top of that cliff threatening to fall on you at any moment... Perhaps I've over-stretched this particular metaphor...?
I would absolutely love to be able to contribute back to this project by helping to draft up the beginnings of an introductory guide/installation guide for the Aegir project as a whole, and the Hostmaster project in particular, although I don't claim to be a terminal expert by any means.
I do think think there's a real need here to have a small team of people go through all the docs with a view to condensing, re-writing where necessary, and simplifying. They should have a strong understanding of the tone of "voice"/writing style needed throughout all the documentation, and they would need to be familiar with both the complexities of the system, and have recent experience of installing or working with this system for the first time so their experiences are still reasonably fresh in their minds.
Do you think this suggestion could have some mileage, or could you see a better way of approaching the documentation issue?
Best regards,
Alex
Actually this is an
Actually this is an interesting post. I'm certainly not a developer or IT person but, by following instructions, I have managed to install a wamp on a Windows Server 2003 and XP box and to install Drupal multi-site on both. And I have built two Drupal sites, both from scratch, no reliance on Zen theme, etc; one is up and running at a university and looks pretty good. I am now trying to set up a Linode for a Drupal multi-site and I admit to being over-my-head but I am determined and am figuring it out. When I landed here, it was because I came across the aegir lamp stackscript at linode, followed the link, thought "wow" when I read what aegir was all about. Sounds like something I might want. But I began reading the how-to's and my mind got muddier than I was comfortable with. I thought I had finally landed on something that was way beyond my grasp. Right before I clicked away, I discovered this post. Misery loves company and I thought to myself, oh boy, at least I'm not alone. I won't be tackling this install right now as I would drive people nuts with my inexperienced questions. However, after reading the post above, the thought that comes to mind is that documentation should follow the example of science writers, writing that I have done quite a bit of, although not recently. The practice in science writing is to navigate between writing that easily informs while upping the knowledge level as one progresses into the text. Translated that means that writing aims for a fog index of 6th grade, surprisingly enough, and active voice. When a term/jargon is introduced, it's introduced at the back-end of the sentence and then, once explanation has occurred, it can be freely used it the rest of the document. A fast example: "To deliver web pages to someone viewing them through a browser, there must be something in place that has that job of serving up the pages. That job is done by a server and one of the most popular servers is called 'apache.' Apache is a set of files that etc." From now on, Apache is used in text without explanation.
I do empathize with the developers. Once one has mastered a field and its jargon, it's often the case that it is very difficult to write for an audience that is not at the same level. We actually can forget "what we didn't know" when we first began learning. So, the jargon becomes the language for communication; it's comfortable; and it's easy to not get that others don't get it. Of course, one could simply decide that this is for developers at a certain level; nothing wrong with that.
Anyway, it looks too challenging for me so I'm on my way outta here. Ciao...
Documentation standards, etc.
This is just a set of thoughts after last two posts: nwwoman, it won't be too challenging, please just be patient and work things through - your experience can help lots of others if you can? Can you write things down as you do them, especially if they seem silly :) - and share on here? The "heavyweight" technical team are surely used to talking to people who already know the jargon, as you suggest, and that is just fair enough, they are specialists. There is maybe a place for that discussion that is away from the ordinary mortal but surely it still has a greater value when it is accessible to the rest of us? The rest of us though, can take your good/bad experience and maybe help you, or help the next person ...
However I do have to take exception to comment before yours: "There's also a lot of use of the words verging on what I'd describe as "jargon". I had to go away and look up several definitions, e.g. "canonical", which appears a lot in these docs. Certainly, I'm happy to pick up new words - especially those I should maybe know already - but maybe we could aim for a bit more of a Plain English approach to docs?"
Canonical is a normal English word; it is Plain English. There are words in the documentation which verge on jargon but canonical is definitely not one of them. Perhaps there is a strong argument for a group of us forming a Plain English documentation team. Perhaps we need to find a middle ground between the over-technical or over-jargon-laden, and the straightforward misinterpretation that has occurred just because of the language used? Criticising documentation for over-complexity is "fair game"; criticising it for using normal English is a touch unfair. If you both would be interested in being part of a "Plain English" effort I would be very glad to join you but it has to be "plain" English, not frightened of using technical terms where alternatives are less acceptable, not afraid of of normal English words, and not seeing tech-friendly documentation as being a fault rather than a help? Fortunately I'm in a place where I can do test installs, follow "howto" etc, on CentOS or Ubuntu VMs, so I can actually test things without upsetting customers :) Worked on that basis, we can maybe work together and help people to avoid the issues you have seen / read?
As I said, just thoughts after reading the last couple of posts.
I hear you and normally I
I hear you and normally I would jump. But right now, I am in the interesting position of having to have a style-being-designed Drupal site up by July 31 and I'm in the process of figuring out how the heck to create a multi-site set-up on a Linode (linode.com) server that I have only finished installing Ubuntu 8.04 on. I've never done such an install; second ago figured out what a stackscript is and trying to figure out if it's a good short-cut or one of those horrid share-hosting-like fantastico installs. There's a reason I'm working on a beautiful weekend, unfortunately. I have been wanting to help with documentation of nearly everything in Drupal but tackling this will have to wait until this project's done. I am actually wondering how much it would cost/how much time it would take.... to have someone do the install of the LAMP and Drupal multi-site setup for me, so I could focus on something else. Interested?
check PM
but do you need multi-site, or Aegir? given deadline is there a way to do a multi-site for now, and a "real" Aegir once pressure off? just trying to find options :)
Sent you a direct email...
Sent you a direct email...