Merge lp:~evarlast/serverguide/wordpress into lp:~ubuntu-core-doc/serverguide/quantal

Proposed by Jay R. Wren
Status: Merged
Approved by: Doug Smythies
Approved revision: 92
Merged at revision: 103
Proposed branch: lp:~evarlast/serverguide/wordpress
Merge into: lp:~ubuntu-core-doc/serverguide/quantal
Diff against target: 293 lines (+194/-33)
2 files modified
serverguide/C/lamp-applications.xml (+151/-0)
serverguide/C/mail.xml (+43/-33)
To merge this branch: bzr merge lp:~evarlast/serverguide/wordpress
Reviewer Review Type Date Requested Status
Doug Smythies Approve
Peter Matulis Pending
Review via email: mp+150194@code.launchpad.net

This proposal supersedes a proposal from 2012-07-27.

Description of the change

I was surprised that WordPress was not listed in the lamp applications section, so I wrote a wordpress sub section

update: fixed a/href which should have been ulink/url

To post a comment you must log in.
Revision history for this message
Peter Matulis (petermatulis) wrote : Posted in a previous version of this proposal

XML does not validate. Please correct this today as String Freeze is upon us.

====
scripts/validate.sh serverguide/C/serverguide.xml
 --Validating serverguide/C/serverguide.xml ...
lamp-applications.xml:607: element para: validity error : Element a is not declared in para list of possible children
lamp-applications.xml:608: element a: validity error : No declaration for element a
lamp-applications.xml:608: element a: validity error : No declaration for attribute href of element a
Document serverguide/C/serverguide.xml does not validate
====

review: Needs Fixing
Revision history for this message
Doug Smythies (dsmythies) wrote : Posted in a previous version of this proposal

Thanks for your good work on this new section. Would you consider having a look at, and trying to fix, the validation issues? While this merge proposal is for quantal, it would be great to get it into the 13.04 server guide.

Revision history for this message
Jay R. Wren (evarlast) wrote : Posted in a previous version of this proposal

looking into it.

Revision history for this message
Jay R. Wren (evarlast) wrote :

i don't think i'm using lp correctly. Is rev 87 showing in this merge req?

Revision history for this message
Doug Smythies (dsmythies) wrote :

Thanks for your very quick reply and re-submit on this. Now it passes the validiate step.
I looked at the compiled html and the pdf.
Myself, I have never installed wordpress before, I followed your procedure. Here are my notes:

Should this part:

"Enable this new WordPress site

cd /etc/apache2/sites-enabled
sudo ln -s ../sites-available/wordpress"

Be this instead:

"Enable this new WordPress site

sudo a2ensite wordpress"

I relaize that "a2ensite" only does what is mentioned, but it is the preferred method (I think).

At the apache restart step, I did reload instead and got:

doug@s15:/etc/apache2/sites-available$ sudo service apache2 reload
 * Reloading web server config apache2
[Sat Feb 23 15:19:58 2013] [warn] The Alias directive in /etc/apache2/sites-enabled/wordpress at line 2 will probably never match because it overlaps an earlier Alias.

Indeed, there is a directory that, I think, will be hit first:

doug@s15:~/wordpress$ ls -l -d /usr/share/wordpress/wp-content
drwxr-xr-x 5 root root 4096 Feb 23 15:07 /usr/share/wordpress/wp-content

For this:

"Your new WordPress can now be configured by visiting http://localhost/blog/wp-admin/install.php. Fill ..."

But this is the serverguide, and I have no GUI and no browser. ??

From another computer, can I browse to:

http://s15.smythies.com/blog/wp-admin/install.php

? No, I get 404 not found error.

The file is there:

doug@s15:~/wordpress$ ls -l /usr/share/wordpress/wp-admin/install.php
-rw-r--r-- 1 root root 10329 Jan 16 2012 /usr/share/wordpress/wp-admin/install.php

Perhaps because of the earlier alias warning. (?)
(note: s15 is a LAN only test computer, not available on WAN)

I do not have a way to try "http://localhost/blog/wp-admin/install.php" to see if it works.
I suspect this might be related to that file config-localhost.php, but am not sure how to prove it.

For files that do not exsist already should "Open" be changed to "Create"?

Should it be spelled out for the user to replace "yourpasswordhere" with their own desired password?

Revision history for this message
Doug Smythies (dsmythies) wrote :

I am trying to use w3m to access the install.php from localhost. It seems to be working, I just have to learn how to use w3m properly.

I forgot to mention, that the test computer is actually 12.04 and not 12.10. I do not have an Ubuntu server 12.10 computer at the moment.

Revision history for this message
Jay R. Wren (evarlast) wrote :

yes, a2ensite should be used. I'll update.

Its not obvious that the instructions and wordpress packaging use a config per virtual host. I'll update the docs to state as much.

Revision history for this message
Doug Smythies (dsmythies) wrote :

Thanks for continued quick work.
I got frustrated trying to continue with w3m on the server itaelf.
So, (after more study) I copied /etc/wordpress/config-localhost.php
to config-s15.smythies.com.php . Then I was able to access and complete the install via http://s15.smythies.com/blog/wp-admin/install.php .
Now it seems to be working, but complaining about no theme and actual blog pages are blank. This could well be because I am hurrying to much and don't know what I'm doing.

Revision history for this message
Doug Smythies (dsmythies) wrote :

Peter M: Could you please comment on the references.
I am wondering about: The link to someone's own web site; The Ubuntu community link.

Here is a reference quote from a "needs fixing" reject of one of my MP's a year ago:

"I do not like the references used here. We should always strive to point users to definitive resources (typically upstream), not the community documentation [1] nor the forums [2]."

Revision history for this message
Doug Smythies (dsmythies) wrote :

Jay: I made a mistake above. There are 62 other links to Ubuntu community pages in the server guide. The issue (if I had bothered to re-read the entire old thread) was with a link I trying to give to an Ubuntu forums thread. Sorry for any confusion.

Revision history for this message
Peter Matulis (petermatulis) wrote :

Yes, I re-confirm my above position on references.

lp:~evarlast/serverguide/wordpress updated
88. By Jay R. Wren

merging upstream

89. By Jay R. Wren

WordPress section: use a2ensite instead of ln -s & clarify config-VHOST.php file

90. By Jay R. Wren

merge with upstream

91. By Jay R. Wren

WordPress section: remove link to a blog

linking to blog documentation is not recommended. I've removed the link.

Revision history for this message
Jay R. Wren (evarlast) wrote :

I removed a blog link, should I just remove all of the references link?

I really don't like this policy. It is dishonest. As a publisher of non fiction, I want to cite my references. Blogs and community documentation are my references.

Who set this policy and how can I urge them to reconsider?

lp:~evarlast/serverguide/wordpress updated
92. By Jay R. Wren

change wordpress references to MLA format

http://www.easybib.com/reference/guide/mla/website

Revision history for this message
Peter Matulis (petermatulis) wrote :

Jay, as sole driver for the Server Guide Project, I set this policy.

The "references" you speak of should instead be thought of as "further reading". Official documentation, such as this Guide, should ideally not include links to unofficial documentation.

Revision history for this message
Jay R. Wren (evarlast) wrote :

Understood.

I've been in academic writing for too much lately where one always cites references. From the point of view that this is documentation for a product, it makes sense to not reference community documentation.

Revision history for this message
Doug Smythies (dsmythies) wrote :

The link that has been in debate on this thread no longer works for me. I went back to the earlier version of this wordpress document, and the link no longer worked there either. I took out the whole reference.

I also changed this paragraph:

        <para>Your new <application>WordPress</application> can now be configured by visiting
<ulink url="http://localhost/blog/wp-admin/install.php">http://localhost/blog/wp-admin/install.php</ulink>.
Fill out the Site Title, username, password, and E-mail and click Install WordPress.
        </para>

To:

        <para>Your new <application>WordPress</application> can now be configured by visiting
            <ulink url="http://localhost/blog/wp-admin/install.php">http://localhost/blog/wp-admin/install.php</ulink>.
            (Or <ulink url="http://NAME_OF_YOUR_VIRTUAL_HOST/blog/wp-admin/install.php">http://NAME_OF_YOUR_VIRTUAL_HOST/blog/wp-admin/install.php</ulink>
            if your server has no GUI and you are completing <application>WordPress</application>
            configuration via a web browser running on another computer.) Fill out the Site Title,
            username, password, and E-mail and click Install WordPress.
        </para>

review: Approve
Revision history for this message
Doug Smythies (dsmythies) wrote :

I am not an expert, but the edits to mail.xml look O.K. to me.
/etc/dovecot/conf.d/10-auth.conf already has this line:

auth_mechanisms = plain

So does it need the line 222 edit below also? Adds this:

auth_mechanisms = plain login

?

review: Approve
Revision history for this message
Doug Smythies (dsmythies) wrote :

Changing the "auto_machanisms" code area to:

            <para>
            In order to let <application>Outlook</application> clients use SMTP-AUTH, in the <emphasis>authentication mechanisms</emphasis>
            section of /etc/dovecot/conf.d/10-auth.conf change this line:
            </para>

<programlisting>
auth_mechanisms = plain
</programlisting>

            <para>
            To this:
            </para>

<programlisting>
auth_mechanisms = plain login
</programlisting>

review: Approve
Revision history for this message
Doug Smythies (dsmythies) wrote :

See raring revision 104 for the carry forward edits of the Wordpress section. The main.xml had several things already done on the 13.04 (raring) branch, so will take longer to sort out.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'serverguide/C/lamp-applications.xml'
2--- serverguide/C/lamp-applications.xml 2012-04-06 20:16:46 +0000
3+++ serverguide/C/lamp-applications.xml 2013-03-03 16:18:21 +0000
4@@ -502,4 +502,155 @@
5
6 </sect2>
7 </sect1>
8+ <sect1 id="wordpress" status="review">
9+ <title>WordPress</title>
10+ <para>
11+ Wordpress is a blog tool, publishing platform and CMS
12+ implemented in PHP and licensed under the GNU GPLv2.
13+ </para>
14+ <sect2 id="wordpress-installation" status="review">
15+ <title>Installation</title>
16+ <para>To install <application>WordPress</application>, run the following
17+ comand in the command prompt:
18+ </para>
19+
20+<screen>
21+ <command>sudo apt-get install wordpress</command>
22+</screen>
23+
24+ <para>
25+ You should also install <application>apache2</application> web
26+ server and mysql server. For installing <application>apache2</application> web
27+ server, please refer to <xref linkend="http-installation"/>
28+ sub-section in <xref linkend="httpd"/> section.
29+ For installing <application>mysql</application> server, please refer
30+ to <xref linkend="mysql-installation"/> sub-section in
31+ <xref linkend="mysql"/> section.
32+ </para>
33+
34+ </sect2>
35+ <sect2 id="wordpress-configuration" status="review">
36+ <title>Configuration</title>
37+
38+ <para>
39+ For configuring your first <application>WordPress</application>
40+ application, configure an apache site.
41+ Open <filename>/etc/apache2/sites-available/wordpress</filename> and write the
42+ following lines:
43+ </para>
44+
45+ <programlisting>
46+ Alias /blog /usr/share/wordpress
47+ Alias /blog/wp-content /var/lib/wordpress/wp-content
48+ &lt;Directory /usr/share/wordpress&gt;
49+ Options FollowSymLinks
50+ AllowOverride Limit Options FileInfo
51+ DirectoryIndex index.php
52+ Order allow,deny
53+ Allow from all
54+ &lt;/Directory&gt;
55+ &lt;Directory /var/lib/wordpress/wp-content&gt;
56+ Options FollowSymLinks
57+ Order allow,deny
58+ Allow from all
59+ &lt;/Directory&gt;
60+ </programlisting>
61+
62+ <para>Enable this new <application>WordPress</application> site</para>
63+
64+<screen>
65+ <command>sudo a2ensite wordpress</command>
66+</screen>
67+
68+ <para>
69+ Once you configure the <application>apache2</application> web server and
70+ make it ready for your <application>WordPress</application>
71+ application, you should restart it. You
72+ can run the following command to restart the
73+ <application>apache2</application> web server:
74+ </para>
75+
76+<screen>
77+<command>sudo service apache2 restart</command>
78+</screen>
79+
80+ <para>
81+ To facilitate multiple <application>WordPress</application> installations, the name of this
82+ configuration file is based on the Host header of the HTTP request.
83+ This means that you can have a configuration per VirtualHost by simply
84+ matching the hostname portion of this configuration with your Apache
85+ Virtual Host. e.g. /etc/wordpress/config-10.211.55.50.php,
86+ /etc/wordpress/config-hostalias1.php, etc. These instructions assume
87+ you can access Apache via the localhost hostname (perhaps by using an
88+ ssh tunnel) if not, replace /etc/wordpress/config-localhost.php with
89+ /etc/wordpress/config-NAME_OF_YOUR_VIRTUAL_HOST.php.
90+ </para>
91+ <para>
92+ Once the configuration file is written, it is up to you to choose a
93+ convention for username and password to mysql for each
94+ <application>WordPress</application>
95+ database instance. This documentation shows only one, localhost,
96+ example.
97+ </para>
98+ <para>
99+ Now configure <application>WordPress</application> to use a mysql database.
100+ Open <filename>/etc/wordpress/config-localhost.php</filename> file and write
101+ the following lines:
102+ </para>
103+
104+<programlisting>
105+&lt;?php
106+define('DB_NAME', 'wordpress');
107+define('DB_USER', 'wordpress');
108+define('DB_PASSWORD', 'yourpasswordhere');
109+define('DB_HOST', 'localhost');
110+define('WP_CONTENT_DIR', '/var/lib/wordpress/wp-content');
111+?&gt;
112+</programlisting>
113+ <para>Now create this mysql database. Open a temporary file with mysql commands
114+ <filename>wordpress.sql</filename> and write the following lines:
115+ </para>
116+<programlisting>
117+CREATE DATABASE wordpress;
118+GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER
119+ON wordpress.*
120+TO wordpress@localhost
121+IDENTIFIED BY 'yourpasswordhere';
122+FLUSH PRIVILEGES;
123+</programlisting>
124+ <para>Execute these commands.</para>
125+<screen>
126+<command>cat wordpress.sql | sudo mysql --defaults-extra-file=/etc/mysql/debian.cnf</command>
127+</screen>
128+ <para>Your new <application>WordPress</application> can now be configured by visiting
129+<ulink url="http://localhost/blog/wp-admin/install.php">http://localhost/blog/wp-admin/install.php</ulink>.
130+Fill out the Site Title, username, password, and E-mail and click Install WordPress.
131+ </para>
132+ <para>Note the generated password (if applicable) and click the login password. Your
133+<application>WordPress</application> is now ready for use.
134+ </para>
135+ </sect2>
136+ <sect2 id="wordpress-references" status="review">
137+ <title>References</title>
138+
139+ <itemizedlist>
140+ <listitem>
141+ <para>
142+ <ulink url="https://codex.wordpress.org/">WordPress.org Codex</ulink>
143+ </para>
144+ </listitem>
145+ <listitem>
146+ <para>
147+ Hartman, Justin. "WordPress Installation on Debian" Debian Wiki authoried by Justin Hartman 18 August 2008. Web. 25 July 2012 <ulink url="http://linux.justinhartman.com/Wordpress_Installation_on_Debian">http://linux.justinhartman.com/Wordpress_Installation_on_Debian</ulink>.
148+ </para>
149+ </listitem>
150+ <listitem>
151+ <para>
152+ <ulink url="https://help.ubuntu.com/community/WordPress">Ubuntu Wiki WordPress</ulink>
153+ </para>
154+ </listitem>
155+ </itemizedlist>
156+
157+ </sect2>
158+ </sect1>
159 </chapter>
160
161=== modified file 'serverguide/C/mail.xml'
162--- serverguide/C/mail.xml 2012-08-20 08:09:16 +0000
163+++ serverguide/C/mail.xml 2013-03-03 16:18:21 +0000
164@@ -214,40 +214,36 @@
165 <command>sudo apt-get install dovecot-common</command>
166 </screen>
167 <para>
168- Next you will need to edit <filename>/etc/dovecot/dovecot.conf</filename>. In the <emphasis>auth default</emphasis>
169- section uncomment the <emphasis>socket listen</emphasis> option and change the following:
170+ Next you will need to edit <filename>/etc/dovecot/conf.d/10-master.conf</filename>. Change the following:
171 </para>
172 <programlisting>
173- socket listen {
174- #master {
175- # Master socket provides access to userdb information. It's typically
176- # used to give Dovecot's local delivery agent access to userdb so it
177- # can find mailbox locations.
178- #path = /var/run/dovecot/auth-master
179- #mode = 0600
180- # Default user/group is the one who started dovecot-auth (root)
181- #user =
182- #group =
183- #}
184- client {
185- # The client socket is generally safe to export to everyone. Typical use
186- # is to export it to your SMTP server so it can do SMTP AUTH lookups
187- # using it.
188- path = /var/spool/postfix/private/auth-client
189- mode = 0660
190- user = postfix
191- group = postfix
192- }
193+service auth {
194+ # auth_socket_path points to this userdb socket by default. It's typically
195+ # used by dovecot-lda, doveadm, possibly imap process, etc. Its default
196+ # permissions make it readable only by root, but you may need to relax these
197+ # permissions. Users that have access to this socket are able to get a list
198+ # of all usernames and get results of everyone's userdb lookups.
199+ unix_listener auth-userdb {
200+ #mode = 0600
201+ #user =
202+ #group =
203+ }
204+
205+ # Postfix smtp-auth
206+ unix_listener /var/spool/postfix/private/auth {
207+ mode = 0660
208+ user = postfix
209+ group = postfix
210 }
211 </programlisting>
212
213 <para>
214- In order to let <application>Outlook</application> clients use SMTP-AUTH, in the <emphasis>auth default</emphasis>
215- section of /etc/dovecot/dovecot.conf add <emphasis>"login"</emphasis>:
216+ In order to let <application>Outlook</application> clients use SMTP-AUTH, in the <emphasis>authentication mechanisms</emphasis>
217+ section of /etc/dovecot/conf.d/10-auth.conf add <emphasis>"login"</emphasis>:
218 </para>
219
220 <programlisting>
221- mechanisms = plain login
222+auth_mechanisms = plain login
223 </programlisting>
224
225 <para>
226@@ -372,6 +368,19 @@
227 <command>sudo service postfix restart</command>
228 </screen>
229 </sect3>
230+ <sect3 id="postfix-smtps">
231+ <title>Smtps</title>
232+ <para>
233+ If you need smtps, edit <filename>/etc/postfix/master.cf</filename> and uncomment the following line:
234+ </para>
235+ <programlisting>
236+smtps inet n - - - - smtpd
237+ -o smtpd_tls_wrappermode=yes
238+ -o smtpd_sasl_auth_enable=yes
239+ -o smtpd_client_restrictions=permit_sasl_authenticated,reject
240+ -o milter_macro_daemon_name=ORIGINATING
241+ </programlisting>
242+ </sect3>
243 <sect3 id="postfix-logs">
244 <title>Log Files</title>
245 <para>
246@@ -428,7 +437,7 @@
247 <listitem>
248 <para>
249 To increase the amount of information logged when troubleshooting <emphasis>SASL</emphasis> issues you can set the following options in
250- <filename>/etc/dovecot/dovecot.conf</filename>
251+ <filename>/etc/dovecot/conf.d/10-logging.conf</filename>
252 </para>
253 <programlisting>
254 auth_debug=yes
255@@ -716,7 +725,7 @@
256 </para>
257 <para>
258 Once you have chosen your mailbox type, edit the file
259- <filename>/etc/dovecot/dovecot.conf</filename> and change
260+ <filename>/etc/dovecot/conf.d/10-mail.conf</filename> and change
261 the following line:
262 </para>
263 <programlisting>
264@@ -759,14 +768,15 @@
265 <title>Dovecot SSL Configuration</title>
266 <para>
267 To configure <application>dovecot</application> to use SSL, you can edit the file
268- <filename>/etc/dovecot/dovecot.conf</filename> and amend
269+ <filename>/etc/dovecot/conf.d/10-ssl.conf</filename> and amend
270 following lines:
271 </para>
272 <programlisting>
273-ssl_cert_file = /etc/ssl/certs/ssl-cert-snakeoil.pem
274-ssl_key_file = /etc/ssl/private/ssl-cert-snakeoil.key
275-ssl_disable = no
276-disable_plaintext_auth = no
277+<![CDATA[
278+ssl = yes
279+ssl_cert = </etc/ssl/certs/dovecot.pem
280+ssl_key = </etc/ssl/private/dovecot.pem
281+]]>
282 </programlisting>
283 <para>
284 You can get the SSL certificate from a Certificate Issuing
285@@ -778,7 +788,7 @@
286 for details about how to create self signed SSL certificate. Once
287 you create the certificate, you will have a key file and a
288 certificate file. Please copy them to the location pointed
289- in the <filename>/etc/dovecot/dovecot.conf</filename>
290+ in the <filename>/etc/dovecot/conf.d/10-ssl.conf</filename>
291 configuration file.
292 </para>
293 </sect2>

Subscribers

People subscribed via source and target branches